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()
BrMatrix4Determinant()
Conversion
BrMatrix4ToEuler()
BrMatrix4ToQuat()
Copy/Assign
BrMatrix4Copy()
BrMatrix4Copy34()
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_matrix34`187, `br_renderbounds_cbfn`307.

## 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_vector4`365 structures, e.g. `br_vector4 m[4]`. Thus `m[row]` can be cast as `(br_vector4*)`.

## `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:

`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.

`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:

`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.

`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.

`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.

`BrMatrix34Copy4()`
206.

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.

`br_camera`107, `BrActorToScreenMatrix4()`83.