BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_matrix4
Next|Prev|Up
The Structure
Members
Arithmetic
BrMatrix4Mul()
BrMatrix4Inverse()
BrMatrix4Apply()
BrMatrix4ApplyP()
BrMatrix4ApplyV()
BrMatrix4TApply()
BrMatrix4TApplyP()
BrMatrix4TApplyV()
BrMatrix4Pre34()
BrMatrix4PreTransform()
BrMatrix4Adjoint()
BrMatrix4Determinant()
Conversion
BrMatrix4ToEuler()
BrMatrix4ToQuat()
Copy/Assign
BrMatrix4Copy()
BrMatrix4Copy34()
Referencing & Lifetime
Initialisation
BrMatrix4Identity()
BrMatrix4Scale()
BrMatrix4Perspective()

br_matrix4


The Structure

A four column, four row, scalar array, used as a 3D affine matrix for general purpose 3D transformations (translation, scaling, shearing, rotation). Functions are provided to allow it be used as though it were an integral type. It has the following form:

It can be noted that the bottom row has a translational effect. Also note, that the matrix determinant represents the volume change effected.

The typedef

(See matrix.h for precise declaration and ordering)

br_scalar m[4][4] Four rows of four columns

Related Functions

Image Support

See BrActorToScreenMatrix4()
83.

Maths

See BrEulerToMatrix4()121, BrQuatToMatrix4()315, BrMatrix34Copy4()206.

Related Structures

See br_matrix34187, br_renderbounds_cbfn307.

Members

br_scalar m[4][4]

Each element of the matrix can be freely and individually accessed.

This matrix can also be thought of as an array of four br_vector4365 structures, e.g. br_vector4 m[4]. Thus m[row] can be cast as (br_vector4*).

Arithmetic


BrMatrix4Mul()

Description:
Multiply two matrices together and place the result in a third matrix. Equivalent to the expression:

Declaration:
void BrMatrix4Mul(br_matrix4* A, const br_matrix4* B, const br_matrix4* C)

Arguments:
br_matrix4 * A

A pointer to the destination matrix (must be different from both sources).

const br_matrix4 * B

Pointer to the left hand source matrix.

const br_matrix4 * C

Pointer to the right hand source matrix.

Remarks:
The result in A is equivalent to the following:

See Also:
BrMatrix4Pre34()
219, BrMatrix4PreTransform()220


BrMatrix4Inverse()

Description:
Compute the inverse of the supplied 3D affine matrix. Equivalent to the expression:

Declaration:
br_scalar BrMatrix4Inverse(br_matrix4* A, const br_matrix4* B)

Arguments:
br_matrix4 * A

A pointer to the destination matrix (must be different from source).

const br_matrix4 * B

A pointer to the source matrix.

Result:
br_scalar

If the inverse exists, the determinant of the source matrix is returned. If there is no inverse, scalar zero is returned.

Remarks:
Remember that while an inverse may be obtained using double precision arithmetic, this does not necessarily mean that it can using the br_scalar
332 type. This difference is most marked between fixed and floating point BRender libraries.

See Also:
BrMatrix4Adjoint()220, BrMatrix4Determinant()221.


BrMatrix4Apply()

Description:
Applies a transform to a 3D point which may have non-unity homogenous co-ordinates. Equivalent to the expression:

Declaration:
void BrMatrix4Apply(br_vector4* A, const br_vector4* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source, and not part of transform), to hold the transformed point.

const br_vector4 * B

A pointer to the source vector, holding the point to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied.

Remarks:
The result in A is equivalent to the following:


BrMatrix4ApplyP()

Description:
Applies a transform to a 3D point. Equivalent to the expression:

Declaration:
void BrMatrix4ApplyP(br_vector4* A, const br_vector3* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source, and not part of transform), to hold the transformed point.

const br_vector3 * B

A pointer to the source vector, holding the point to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied.

Remarks:
The result in A is equivalent to the following:


BrMatrix4ApplyV()

Description:
Applies a transform to a 3D vector, i.e. as for a point but without translation components (a vector has no location). Equivalent to the expression:

Declaration:
void BrMatrix4ApplyV(br_vector4* A, const br_vector3* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source, and not part of transform), to hold the transformed vector.

const br_vector3 * B

A pointer to the source vector, holding the vector to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied.

Remarks:
The result in A is equivalent to the following:


BrMatrix4TApply()

Description:
Applies a transform to a transposed 3D point which may have non-unity homogenous co-ordinates. Equivalent to the expression:

Declaration:
void BrMatrix4TApply(br_vector4* A, const br_vector4* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source), to hold the transformed point.

const br_vector4 * B

A pointer to the source vector, holding the point to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied transposed.

Remarks:
The result in A is equivalent to the following:


BrMatrix4TApplyP()

Description:
Applies a transposed transform to a 3D point. Equivalent to the expression:

Declaration:
void BrMatrix4TApplyP(br_vector4* A, const br_vector3* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source, and not part of transform), to hold the transformed point.

const br_vector3 * B

A pointer to the source vector, holding the point to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied transposed.

Remarks:
The result in A is equivalent to the following:


BrMatrix4TApplyV()

Description:
Applies a transposed transform to a 3D vector, i.e. as for a point but without translation components (a vector has no location). Equivalent to the expression:

Declaration:
void BrMatrix4TApplyV(br_vector4* A, const br_vector3* B, const br_matrix4* C)

Arguments:
br_vector4 * A

A pointer to the destination vector (must be different from source, and not part of transform), to hold the transformed vector.

const br_vector3 * B

A pointer to the source vector, holding the vector to be transformed.

const br_matrix4 * C

A pointer to the transform matrix to be applied transposed.

Remarks:
The result in A is equivalent to the following:


BrMatrix4Pre34()

Description:
Pre-multiply one matrix by another. Equivalent to the expression:

Declaration:
void BrMatrix4Pre34(br_matrix4* A, const br_matrix34* B)

Arguments:
br_matrix4 * A

A pointer to the subject matrix (may be same as B).

const br_matrix34 * B

A pointer to the pre-multiplying matrix.

Remarks:
The result in A is equivalent to the following:

See Also:
BrMatrix4Mul()
215.


BrMatrix4PreTransform()

Description:
Pre-multiply a matrix by a generic transform. Equivalent to the expression:

Declaration:
void BrMatrix4PreTransform(br_matrix4* mat, const br_transform* xform)

Arguments:
br_matrix4 * mat

A pointer to the subject matrix.

const br_transform * xform

The pre-multiplying generic transform.

Effects:
The transform is first converted to a general 3x4 transform matrix using BrTransformToMatrix34()
343 and then applied as a pre-multiplying matrix using BrMatrix4Pre34()219.


BrMatrix4Adjoint()

Description:
Find the adjoint of a matrix - the transposed matrix of co-factors. Equivalent to the expression:

Declaration:
void BrMatrix4Adjoint(br_matrix4* A, const br_matrix4* B)

Arguments:
br_matrix4 * A

A pointer to the destination matrix (may be same as source).

const br_matrix4 * B

A pointer to the source matrix.

See Also:
BrMatrix4Inverse()
215.


BrMatrix4Determinant()

Description:
Calculate the determinant of a matrix. Equivalent to the expression:

Declaration:
br_scalar BrMatrix4Determinant(const br_matrix4* mat)

Arguments:
const br_matrix4 * mat

A pointer to the source matrix.

Result:
br_scalar

The determinant of the source matrix.

See Also:
BrMatrix4Inverse()
215.


Conversion

From Eulers and Quaternions

See BrEulerToMatrix4()
121, BrQuatToMatrix4()315.

To Eulers and Quaternions

See BrMatrix4ToEuler()221, BrMatrix4ToQuat()222 as described below.


BrMatrix4ToEuler()

Description:
Convert a 3D affine matrix to a Euler angle set, that would have the same rotational effect.

Declaration:
br_euler* BrMatrix4ToEuler(br_euler* euler, const br_matrix4* mat)

Arguments:
br_euler * euler

A pointer to the destination Euler angle set to receive the conversion. The Euler angle set's Euler order is used to determine each angle.

const br_matrix4 * mat

A pointer to the source matrix to convert from.

Result:
br_euler *

Returns euler for convenience.

Remarks:
Translation and projective (fourth column) components of the matrix are lost in conversion.


BrMatrix4ToQuat()

Description:
Convert a 3D affine matrix to a quaternion, that would have the same rotational effect.

Declaration:
br_quat* BrMatrix4ToQuat(br_quat* q, const br_matrix4* mat)

Arguments:
br_quat * q

A pointer to the destination quaternion to receive the conversion.

const br_matrix4 * mat

A pointer to the source matrix to convert from.

Result:
br_quat * q

Returns q for convenience.

Remarks:
Translation and projective (fourth column) components of the matrix are lost in conversion.


Copy/Assign

Although copy by structure assignment currently works, use BrMatrix4Copy()
222 to ensure compatibility.


BrMatrix4Copy()

Description:
Copy a matrix. Equivalent to the expression:

Declaration:
void BrMatrix4Copy(br_matrix4* A, const br_matrix4* B)

Arguments:
br_matrix4 * A

A pointer to the destination matrix (may be the same as source - though redundant).

const br_matrix4 * B

A pointer to the source matrix.


BrMatrix4Copy34()

Description:
Copy a 3x4 matrix into a 4x4 matrix. Equivalent to the expression:

Declaration:
void BrMatrix4Copy34(br_matrix4* A, const br_matrix34* B)

Arguments:
br_matrix4 * A

A pointer to the destination matrix.

const br_matrix34 * B

A pointer to the source 3x4 matrix.

Effects:
The source is copied into the destination, and the fourth column of the destination is set to the implicit (0,0,0,1) column vector.

See Also:
BrMatrix34Copy4()
206.


Referencing & Lifetime

This structure may be freely referenced, though take care if there is potential to supply the same matrix as more than one argument to the same function.

Initialisation

No static initialisers are provided. However, four BR_VECTOR4() macros would serve as well.

All other initialisation should use BrMatrix4Copy()222 or any of the following initialisation functions.


BrMatrix4Identity()

Description:
Set the specified matrix to the identity transformation matrix. Equivalent to:

Declaration:
void BrMatrix4Identity(br_matrix4* mat)

Arguments:
br_matrix4 * mat

A pointer to the destination matrix.

Effects:
Stores the identity matrix at the destination.


BrMatrix4Scale()

Description:
Set the specified matrix to a matrix representing a specific scaling. Equivalent to:

Declaration:
void BrMatrix4Scale(br_matrix4* mat, br_scalar sx, br_scalar sy, br_scalar sz)

Arguments:
br_matrix4 * mat

A pointer to the destination matrix.

br_scalar sx

Scaling component along the x axis.

br_scalar sy

Scaling component along the y axis.

br_scalar sz

Scaling component along the z axis.


BrMatrix4Perspective()

Description:
Generate a perspective transformation matrix, that can be used to convert from a camera actor's co-ordinate space into the homogenous screen space (assuming a centred projection). This maps the viewing volume into the rendering volume, a cuboid delimited by the homogenous screen co-ordinates (left, bottom, near) (1,1,+1) to (+1,+1,1). The matrix created is equivalent to the following (a=field of view).

Declaration:
void BrMatrix4Perspective(br_matrix4* mat, br_angle field_of_view, br_scalar aspect, br_scalar hither, br_scalar yon)

Arguments:
br_matrix4 * mat

A pointer to the destination matrix to receive the perspective transform.

br_angle field_of_view

Field of view, i.e. the angle subtended at the camera between the top and bottom of the view volume.

br_scalar aspect

Scaling factor for width of viewing volume, i.e. xb1 1 in y view ordinates is mapped to the height of the output image, and xb1 aspect in x view ordinates is mapped to the width of the output image.

br_scalar hither

z ordinate of front of view volume. The value should be less than zero.

br_scalar yon

z ordinate of back of view volume. The value should be less than hither.

Effects:
Calculates the camera to screen transformation matrix and stores it at mat.

Remarks:
Note that hither and yon are of opposite sign to the comparable values of hither_z and yon_z that would be specified in br_camera
107. This is because they are ordinates as opposed to distances.

Note that the front clip plane is at a homogenous screen z ordinate of -1.

See Also:
br_camera107, BrActorToScreenMatrix4()83.



Generated with CERN WebMaker