class HT_Matrix

This class implements the 4 x 4 matrices used to represent the transformations of the 3D transformation pipeline. The matrix is formed using the base class HT_Row_Vector. For additional operations, see class HT_Row_Vector, and class HT_Adjoint_Matrix.

In Heidi, matrices are understood to represent transformations as right multipliers of row vectors.

See Also

HT_Row_Vector, HT_Vector, HT_Adjoint_Matrix

Operators

operator *             Performs matrix multiplication (same as multiply method).
operator =             Performs matrix assignment.
operator *=            Performs matrix multiplication (same as multiply method).
operator /=                              Scales the matrix by a scalar value.
operator []            Access matrix elements of an HT_Matrix object by row and column indices.

Comparison Methods

is_identity            Tests whether this HT_Matrix object represents the identity matrix.

Access Methods 

adjoin                 Returns the adjoint matrix for this HT_Matrix object.
change_basis           Appends a basis to the transformation represented by this HT_Matrix object.
identity               Sets this HT_Matrix object to the identity matrix.
multiply               Performs matrix multiplication.
project                Applies projection to matrix.
rotate, rotate_x, rotate_y, rotate_z
                       Appends a rotation to the transformation represented by this HT_Matrix object.
scale                  Appends a scale transformation to the transformation represented by this HT_Matrix object.
shear_x, shear_y, shear_z
                       Appends a shear to the transformation represented by this HT_Matrix object.
transform              Applies the transformation defined by this HT_Matrix object to a point or an array of points.
translate              Appends a translation to the transformation represented by this HT_Matrix object.

Constructor

HT_Matrix              Creates an HT_Matrix object and initialize it.

 

HT_Matrix::adjoin

Purpose

Returns the adjoint matrix of this HT_Matrix object.

Synopsis

HT_Adjoint_Matrix const & adjoin (void)

Details

The adjoint matrix of a non-singular matrix is its inverse multiplied by its determinant. This can be used only for applying to normal vectors and planes the appropriate transformation corresponding to this HT_Matrix object or for back transforming points.

For more information see, class HT_Adjoint_Matrix.

 

HT_Matrix::change_basis

Purpose

Appends a basis to the transformation represented by this HT_Matrix object.

Synopsis

void change_basis (
    HT_Vector const & x,
    HT_Vector const & y,
    HT_Vector const & z
)

Details

This routine changes the orientation of the coordinate system.

 

HT_Matrix::HT_Matrix

Purpose

Constructor to initialize a new HT_Matrix object.

Synopsis

HT_Matrix ()

Details

Initializes to the identity matrix.

 

HT_Matrix::identity

Purpose

Sets this HT_Matrix object to the identity matrix.

Synopsis

void identity (void)

Details

Sets this HT_Matrix object to the identity matrix.

 

HT_Matrix::is_identity

Purpose

Tests whether this HT_Matrix object represents the identity matrix.

Synopsis

HT_Boolean is_identity (void)

Details

Returns non-zero if this matrix is the identity matrix.

 

HT_Matrix::multiply

Purpose

Performs matrix multiplication.

Synopsis

void multiply (HT_Matrix const & right, HT_Matrix & result)
void multiply (HT_Matrix const & right)

Details

The first form multiplies the matrix in this HT_Matrix object on the right by the matrix in right and returns the result in result.

The second form replaces the matrix in this HT_Matrix object by the result.

 

HT_Matrix::operator...

Purpose

Provides matrix operations.

Synopsis

HT_Matrix const & operator*= (HT_Matrix const & mat)
HT_Matrix const & operator*= (float value)
HT_Matrix operator* (stack HT_Matrix const & right)
HT_Matrix const & operator/= (float value)
HT_Matrix const & operator= (HT_Adjoint_Matrix const & a)

Details

The first method multiplies this matrix by the matrix in mat.

The second method scales this matrix by the scalar value.

The third method multiplies this matrix by the matrix in right and returns the result without updating this matrix.

The fourth method scales this matrix by the scalar 1/value.

The fifth method assigns an adjoint to this matrix.

 

HT_Matrix::operator [ ]

Purpose

To access matrix elements of an HT_Matrix object by row and column indices.

Synopsis

HT_Row_Vector const & operator [] (int index) const

Details

This operator, in conjunction with "helper" class HT_Row_Vector, allows matrix access by the traditional double index method.

(m[i][j])

 

HT_Matrix::project

Purpose

Applies projection to matrix.

Synopsis

void project (float width, float height, float depth, 
    HT_Boolean perspective)

Details

Either a parallel or a perspective projection is applied to the matrix and is generated from width, height, and depth. A parallel projection is applied if the perspective parameter is false, otherwise, a perspective projection is applied.

 

HT_Matrix::rotate...

Purpose

Appends a rotation to the transformation represented by this HT_Matrix object.

Synopsis

void rotate_x (float angle)
void rotate_y (float angle)
void rotate_z (float angle)
void rotate (float x_angle, float y_angle, float z_angle)
void rotate (HT_Vector const & axis, float angle)

 Details

Each of these replaces the matrix M in this HT_Matrix object with MR, where R is a rotation matrix.

In each of the first three forms, R is a rotation through the specified angle about the X, Y or Z axes respectively. The fourth form consists of applying each of the first three in order. In the fifth form the R represents the rotation through the given angle about an axis through the origin along the given vector.

These are used primarily to construct modeling matrices.

 

HT_Matrix::scale

Purpose

Appends a scale transformation to the transformation represented by this HT_Matrix object.

Synopsis

void scale (float scale_factor)
void scale (float scale_x, float scale_y, float scale_z )

Details

Both of these methods replace the matrix M in this HT_Matrix object with MS, where S is the matrix of a scale transformation.

In the first form, S represents a symmetric (isotropic) scaling by a uniform scale factor. In the second form, the scale transformation is anisotropic, with given scale factors on each axis.

These are used primarily to construct modeling matrices.

 

HT_Matrix::shear...

Purpose

Appends a shear to the transformation represented by this HT_Matrix object.

Synopsis

void shear_x (float y, float z)
void shear_y (float x, float z)
void shear_z (float x, float y)

Details

Each of these replaces the matrix M in this HT_Matrix object by MS, where S is the matrix representing a shear transformation. For a given axis, the shear values indicate the angle of shear in the remaining two axes, in radians. For example, for shear_x, the y and z values specify the angles to shear off of the Y and Z axes, respectively.

These are used primarily to construct modeling matrices.

 

HT_Matrix::transform

Purpose

Applies the transformation defined by this HT_Matrix object to a point or an array of points.

Synopsis

void transform (
    HT_Point const & pt_in, 
    HT_Point & pt_out,
    float * w = null
) 
void transform (
    int count, 
    HT_Point const * pt_array_in, 
    HT_Point * pt_array_out,
    float * w_array_out = null
)

Details

The first form transforms a single input point pt_in to produce a single output point pt_out, and, optionally a fourth component *w_out. The second form does the same for an array of count input points, to produce an array of output points and an array of w values.

Specifically, if pt_in is an input point, and if M is the 4x4 matrix in this HT_Matrix object, then

           [x',y',z',w'] = [pt_in.x, pt_in.y, pt_in.z, 1] M 
and [pt_out.x, pt_out.y, pt_out.z] = [x'/w',y'/w',z'/w'], provided w'> 0.
If w'£ 0, then [pt_out.x, pt_out.y, pt_out.z] = [x',y',z'].
If the w_out argument is supplied, then *w_out = w'.

Note: This function does not perform a completely general perspective transformation. In particular, it gives the correct perspective transformation only for the case w'>0. This case is true for points in the view frustum in the Heidi 3D transformation scheme.

 

HT_Matrix::translate

Purpose

Appends a translation to the transformation represented by this HT_Matrix object.

Synopsis

void translate (
    float x,
    float y,
    float z
)
void translate (HT_Vector const & vec)

Details

Each of these replaces the matrix M in this HT_Matrix object by MT, where T is the matrix representing a translation transformation.

These are used primarily to construct modeling matrices.