4.2.3 Transforms

(use-modules (sly math transform))

Transforms are 4x4 transformation matrices. Matrices are the fundamental structure for modeling affine transformations such as translation, rotation, and scaling. Complex transformations are created by composing many simpler ones with the transform* procedure.

It’s a good idea to use transforms in a functional manner by treating them as immutable. This is made easy because almost every procedure in this module returns a new transform rather than mutating an existing one. However, in some cases it is necessary to use mutable transforms via transform*! for performance reasons.

Scheme Procedure: make-transform aa ab ac ad ba bb bc bd ca cb cc cd da db dc dd

Create a new transform initialized with the given 16 values in column-major format.

Scheme Variable: null-transform

A transform composed entirely of zeroes.

Scheme Variable: identity-transform

The multiplicative identity transform.

Scheme Syntax: transform? obj

Return #t if obj is a transform.

Scheme Syntax: transform-matrix transform

Return the underlying 4x4 floating point array for transform.

Scheme Procedure: transpose transform

Return a transform that is the transpose of transform.

Scheme Procedure: transform-vector2 transform v

Apply transform to the 2D vector v.

Scheme Procedure: transform-position transform

Return a 3D vector containing the positional data stored in transform.

Scheme Procedure: transform+ . transforms

Return the sum of transforms. Return null-transform if called without any arguments.

Scheme Procedure: transform* . transforms

Return the product of transforms. Return identity-transform if called without any arguments.

Scheme Procedure: transform*! dest a b

Multiply a and b, storing the result in dest.

Scheme Procedure: translate v

Create a new transform that translates by the 2D or 3D vector v.

Scheme Procedure: scale v

Scheme Procedure: scale scalar

Create a new transform that scales by the 2D or 3D vector v, or by scalar to scale evenly in all dimensions.

Scheme Procedure: rotate-x angle

Create a new transform that rotates the x axis by angle radians.

Scheme Procedure: rotate-y angle

Create a new transform that rotates the y axis by angle radians.

Scheme Procedure: rotate-z angle

Create a new transform that rotates the z axis by angle radians.

Scheme Procedure: rotate q

Convert the quaternion q into a rotation transform. See Quaternions for more information.

One of the most common composite transformations is a translation multiplied by a scale multiplied by a rotation. The build-transform procedure is a convenience procedure for this case.

Scheme Procedure: build-transform [#:position=(vector3 0 0 0)] [#:scale=1] [#:rotation=null-quaternion]

Build a transform by multiplying the following transforms:

• translation by position
• rotation by rotation
• scaling by scale

The procedures below are useful for creating projection and view matrices for cameras. See Cameras for more details.

Scheme Procedure: orthographic-projection left right top bottom near far

Create a new transform that represents an orthographic projection for the vertical clipping plane left and right, the horizontal clipping plane top and bottom, and the depth clipping plane near and far.

Scheme Procedure: perspective-projection field-of-vision aspect-ratio near far

Create a new transform that represents a perspective projection with a field-of-vision in degrees, the desired aspect-ratio, and the depth clipping plane near and far.

Scheme Procedure: look-at eye center [up=(vector3 0 1 0)]

Create a view transform that looks from 3D vector eye at the 3D vector center, with the 3D vector up indicating which direction points up.