Matrix Class

Realsoft 3D Matrix is a row dominated 4x4 matrix. Realsoft 3D uses matrices to represent spaces and transformations for geometric objects.

  | a0  a1  a2  a3 |
  |                |
  | b0  b1  b2  b3 |
  |                |
  | c0  c1  c2  c3 |
  |                |
  | d0  d1  d2  d3 |

Matrix operations (such as concatenation, scale, translate etc. concatenate the new matrix on the right side. In other words, the latest operation is executed the first using 'first in last out' prinsiple.a0, a1, a2, a3, b0, ... d3 - 16 floating point numbers defining 4 x 4 matrix. For example:

m.a0 = m.b1 = m.c2 = 1.0; // reset scale transformation component to identity

Methods
Method:

r3Matrix - constructor

Syntax:

v = new r3Matrix()

Parameters:

a0, ... d3 - sixteen floating point numbers

Returns:

m - new matrix object

Description:

Creates a new matrix object. If you don't pass any parameters to the constructor, an indentity matrix is created. If the number of parameters is four, then the constructor assumes that the parameters define a coordinate system's origin, horizontal, vertical and normal axes.

Example:

// identity matrix;

Method:

identity - identity

Syntax:

v.identity();

Parameters:

-

Returns:

-

Description:

Make the matrix identity matrix

Example:

v.identity();

Method:

set - set matrix attributes

Syntax:

m.set(a0, a1, ... d3);

Parameters:

a0, ... - sixteen floating point numbers

Returns:

-

Description:

Set matrix

Example:

-

Method:

translate - concatenate translation transformation to the matrix

Syntax:

m.translate(x, y, z);

Parameters:

x, y, z - floating point numbers specifying translation in x, y and z dimensions

Returns:

-

Description:

Concatenates given translation vector to the matrix.

Example:

m = new r3Matrix();

Method:

scale - concatenate scale transformation to the matrix

Syntax:

m.scale(fX, fY, fZ);

Parameters:

vX, vY, vZ - scale factors in x, y and z dimensions.

Returns:

-

Description:

Concatenates scale transformation to the matrix. vOrigin parameter may be given to specify scale origin. vOrigin defines a point which is translated to origin before the actual scale is applied. If no scale origin is given, [0, 0, 0] is assumed.

Example:

m = new r3Matrix();

Method:

rotate - concatenate rotation transformation

Syntax:

v.rotate(fAngle, vAxis);

Parameters:

fAngle - rotation angle in radians

Returns:

-

Description:

Concatenates rotation specified by angle, origin and rotation axis to the matrix. The rotation angle is defined in radians. If no origin is specified, [0, 0, 0] is assumed.

Example:

// rotate about the 'y' axis

Method:

rotate2v - concatenate rotation defined by two vectors

Syntax:

v.rotate2v(vFrom, vTo);

Parameters:

fOrigin - rotation origin

Returns:

-

Description:

Concatenates rotation specified by two vectors.

Example:

// rotate 90 degrees about the 'y' axis

Method:

skew - concatenate skew

Syntax:

m.skew(fAngle, vFrom, vTo);

Parameters:

fAngle - skewing angle in radians

Returns:

-

Description:

Concatenates skew transformation into the matrix. Skew transformation is defined in space defined by two vectors 'vFrom' and 'vTo'.

[Note] Note
The skewing angle must satisfy the following constraints:
-PI/2 < angle < PI/2
.

Example:

// skewing space is x - y plane

Method:

invert - inversion

Syntax:

m.invert();

Parameters:

-

Returns:

-

Description:

Invert the matrix. Assumes that the matrix is inversible.

Example:

m.invert();

Method:

mktran - make transformation matrix

Syntax:

m3 = m.mktran(m2);

Parameters:

m2 - matrix specifying target space

Returns:

m3 - transformation matrix mapping points from 'm' to 'm2'

Description:

Computes a matrix which maps a point from space defined by matrix 'm' to target space specified by 'm2'.

Example:

mSrcSpace = new r3Matrix(o, h, v, n);

Method:

transform - transform a vector

Syntax:

m.transform(vTo, vFrom);

Parameters:

vFrom - vector to be transformed

Returns:

-

Description:

Transform given vector. If two parameters are given, the method transforms the given 'vFrom' vector and assigns the result to 'vTo' (operation doesn't change 'vFrom'). If only one parameter is specified, the paramater acts as both source and target i.e. the result is assigned back to the given vector.

Example:

// define a transformation matrix

Method:

transforml - transform by 3 x 3 top-left sub-matrix

Syntax:

m.transforml(vTo, vFrom);

Parameters:

vFrom - vector to be transformed

Returns:

-

Description:

Transforms a vector by operating the parameter only with the 3*3 top-left submatrix, which is the linear part of the affine matrix operator. This means that you can use the transforml() method to transform vectors.

Example:

// define a transformation matrix

Method:

null - make the matrix null matrix

Syntax:

m.null()

Parameters:

-

Returns:

-

Description:

Sets all matrix components to null

Example:

m.null();

Method:

transpose - transpose matrix

Syntax:

m.transpose()

Parameters:

-

Returns:

-

Description:

Transpose matrix

Example:

m.transpose()

Method:

cmp - matrix comparison

Syntax:

b = m.cmp(m2);

Parameters:

m2 - matrix to be compared

Returns:

b - boolean, true if matrices are identical.

Description:

Compares the matrix 'm' against the given matrix 'm2' and returns true if the two matrices are identical.

Example:

rc = m.cmp(m2);

Method:

copy - copy a matrix

Syntax:

m2 = m.copy();

Parameters:

-

Returns:

m2 - new matrix

Description:

Creates an identical copy of matrix.

Example:

m2 = m.copy();

Method:

orthogonal - make orthogonal projection matrix

Syntax:

m.orthogonal(fLeft, fRight, fTop, fBottom, fNear, fFar);

Parameters:

fLeft ... - minimum and maximum clipping planes

Returns:

-

Description:

Concatenates orghogonal projection to the matrix. Transformation maps fNear to 0 and fFar to 1.0

Example:

m.orthogonal(-0.1, 0.1, -0.1, 0.1, 0.1, 5.0)

Method:

perspective - concatenate perspective projection

Syntax:

m.perspective(fMinX, fMaxX, fMinY, fMaxY, fNear, fFar);

Parameters:

fMinX ... - clipping planes specifying perspective projection

Returns:

-

Description:

Concatenate perspective projection to the matrix. Projection maps 'fNear ... fFar' to '0 ... 1'

Example:

-