[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Matrices

Class: <matrix4f>

4x4 matrix. Internally it is represented as an array of 16 floats, stored in column-major order. (It is the same order OpenGL uses, so it can be passed to OpenGL calls without overhead).

Inherits <sequence> and <collection>. When a matrix4f is treated as a sequence, it works as if it is a single sequence of floats in column-major order.

Function: make-matrix4f &optional init

Returns a new matrix4f instance. If init is omitted, the matrix is a unit matrix. Otherwise, init must be a f32vector of length 16, and the elements in the matrix is initialized by ones in f32vector.

 
;; Creates a matrix like this:
;;    1 2 3 4
;;    0 1 0 5
;;    0 0 1 6
;;    0 0 0 1

(make-matrix4f '#f32vector(1 0 0 0
                           2 1 0 0
                           3 0 1 0
                           4 5 6 1))
Function: matrix4f m00 m10 m20 m30 m01 m11 m21 m31 m02 m12 m22 m32 m03 m13 m23 m33

Creates a new matrix4f instance with give values.

Function: matrix4f? obj

Returns true iff obj is a matrix4f.

Reader syntax: #,(matrix4f elt …)

A matrix4f is represented extrenally using SRFI-10 syntax. The elements are listed in column-major order.

Function: list->matrix4f l
Function: matrix4f->list m

Converts between list of 16 real numbers and matrix4f.

Function: f32vector->matrix4f v &optional start

Creates a new matrix4f and initializes it with 16 elements in f32vector v. If optional start is given, it specifies the start offset in vector v to be used as initial values. The f32vector v must have enough length.

Function: matrix4f->f32vector m

Returns a new f32vector that has elements from matrix4f m.

Function: matrix4f-copy m

Returns a new copy of m.

Function: matrix4f-copy! dstm srcm

Copies contents of srcm to dstm.

Function: matrix4f-set! m i value

Sets a real number value to i-th element of matrix m. Since the matrix is laid out in column-major order, the one-dimensional index m{i} and two-dimensional index m(i,j) corresponds as follows:

 
  m(0,0) = m{0}   m(0,1) = m{4}   m(0,2) = m{8}   m(0,3) = m{12}
  m(1,0) = m{1}   m(1,1) = m{5}   m(1,2) = m{9}   m(1,3) = m{13}
  m(2,0) = m{2}   m(2,1) = m{6}   m(2,2) = m{10}  m(2,3) = m{14}
  m(3,0) = m{3}   m(3,1) = m{7}   m(3,2) = m{11}  m(3,3) = m{15}
Function: matrix4f-ref m i &optional fallback

Returns the i-th element of matrix m. If i is out of range, an error is signalled, unless fallback is provided, in such a case fallback is returned.

Function: matrix4f-set2! m i j value

Sets value to (i, j) element of matrix m.

Function: matrix4f-ref2 m i j

Returns the (i, j) element of matrix m.

Function: matrix4f-row m i
Function: matrix4f-column m i
Function: matrix4f-column/shared m i

Returns i-th row vector or i-th column vector of matrix m, as a vector4f instance.

Furthermore, the returned vector from matrix4f-column/shared shares the storage with m.

Function: matrix4f-mul m obj

Obj may be a scalar (real number), a vector4f, a point4f, or a matrix4f. Returns m x obj.

Function: matrix4f-mul! m obj

Obj may be a scalar or a matrix4f. Matrix m is multiplied by obj, and the result is set to m destructively.

Function: matrix4f-transpose m
Function: matrix4f-transpose! m

Returns a transposed matrix of m. The destructive version modifies m.

Function: matrix4f-determinant m

Returns a determinant of m.

Function: matrix4f-inverse m &optional (error-on-singular? #t)
Function: matrix4f-inverse! m &optional (error-on-singular? #t)

Returns a inverse matrix of m. The destructive version modifies m. If given m is a singular matrix, an error is signalled by default. However, if #f is given to the optional error-on-singular? argument, #f is returned in such a case.

Function: translation->matrix4f translation-vector
Function: translation->matrix4f! m translation-vector

Returns a matrix which represents a translation by translation-vector, which must be either a vector4f, a point4f, or a f32vector of length 3 or 4. Only the first three elements in translation-vector is used. The destructive version updates m.

Function: rotation->matrix4f axis angle
Function: rotation->matrix4f! m axis angle

Returns a matrix which represents a rotation around axis by angle radian. Axis must be a vector4f or a f32vector of length 3 or 4, and must be normalized. The result is undefined if anormalized vector is passed as axis. The destructive version updates m.

Function: scale->matrix4f scale-vector
Function: scale->matrix4f! m scale-vector

Returns a matrix which represents a scale by scale-vector, which must be either a vector4f, a point4f, or a f32vector of length 3 or 4. Only the first three elements in scale-vector is used. Each element of scale-vector represents the scale factor along x, y, and z axis. The destructive version updates m.

Function: trs->matrix4f translation rotation-axis rotation-angle scale
Function: trs->matrix4f! m translation rotation-axis rotation-angle scale

This combines above three procedure. Returns a matrix that represents translation, rotation and scale, specified by translation, rotation-axis, rotation-angle and scale. The destructive version updates m.

If T, R and S, are the matrices that represent translation, rotation and scale, respectively, then these procedures effectively calculates a matrix TRS.

Function: tqs->matrix4f translation rotation-quat scale
Function: tqs->matrix4f! m translation rotation-quat scale

A variation of trs->matrix4f. Instead of axis and angle, rotation is represented by a quaternion rotation-quat. See section Quaternions, for more details about quaternions.

Function: euler-angle->matrix4f xangle yangle zangle &optional order
Function: euler-angle->matrix4f! m xangle yangle zangle &optional order

Returns a matrix that represents rotation along x, y and z axis by xangle, yangle, and zangle, respectively.

The order of rotation can be specified by the optional argument order, which may be one of the symbols xyz, xzy, yzx, yxz, zxy, or zyx. For example, symbol xyz means rotation around x-axis, then y-axis, then z-axis. Thus, if we write each rotation as Rx, Ry, and Rz, the returned matrix is RzRyRx. The default value of order is xyz.

The desrtuctive version modifies m.

Function: matrix4f-decompose m

Matrix m is a composition of translation, rotation, shear and scale. Suppose transformation is applied in the reverse order. This procedure decompose m into each individual transformation.

Returns five values.

If m is singular, certain part of rotation matrix can't be recovered. In such a case, r becomes also singular matrix.

If the original matrix has negative scale factor in any of x, y, or z scale, the decomposed scale factor will have all negative components. The signs of elements of r are adjusted accordingly.

Due to the precision errors, you will see small values appear in shear component even m is pure TRS matrix.

Function: matrix4f-decompose! m t r h s

Linear update version of matrix4f-decompose. The result vectors and matrices are stored in t, r, h and s. The return value is a boolean value indicates m is non-singular or not.

Function: matrix4f->translation m

Extract the translation component from the given TRS matrix m and returns it as a <vector4f>.

Function: matrix4f->translation! m v

Extract the translation component from the given TRS matrix m and stores the result into a <vector4f> v. Returns v.

Function: matrix4f->rotation m

From given orthogonal matrix m, extracts and returns and rotation axis and angle, as a vector4f and a real number.

Function: matrix4f->rotation! m v

Same as above, except the storage of vector4f v is reused to store the result axis.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Shiro Kawai on June, 7 2008 using texi2html 1.78.