BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_matrix23
Next|Prev|Up
The Structure
Members
Arithmetic
BrMatrix23Mul()
BrMatrix23Inverse()
BrMatrix23LPInverse()
BrMatrix23ApplyP()
BrMatrix23ApplyV()
BrMatrix23TApplyP()
BrMatrix23TApplyV()
BrMatrix23Pre()
BrMatrix23PreTranslate()
BrMatrix23PreScale()
BrMatrix23PreShearX()
BrMatrix23PreShearY()
BrMatrix23PreRotate()
BrMatrix23Post()
BrMatrix23PostTranslate()
BrMatrix23PostScale()
BrMatrix23PostShearX()
BrMatrix23PostShearY()
BrMatrix23PostRotate()
Copy/Assign
BrMatrix23Copy()
Access & Maintenance
BrMatrix23LPNormalise()
Initialisation
BrMatrix23Identity()
BrMatrix23Translate()
BrMatrix23Scale()
BrMatrix23ShearX()
BrMatrix23ShearY()
BrMatrix23Rotate()

# br_matrix23

## The Structure

A two column, three row, scalar array, used as a 2D affine matrix, typically for texture map 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:

Note that this is effectively used as a 33 matrix, but omitting the redundant, third column for storage purposes. Thus:

It is applied to homogenous 2D co-ordinates, which similarly omit the third element for sake of economy.

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

### The typedef

(See matrix.h for precise declaration and ordering)

br_scalar m[3][2] Three rows of two columns

See br_material
151.

## Members

#### br_scalar m[3][2]

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

This matrix can also be thought of as an array of three br_vector2349 structures, e.g. br_vector2 m[3]. Thus m[row] can be cast as (br_vector2*).

## BrMatrix23Mul()

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

Declaration:
void BrMatrix23Mul(br_matrix34* A, const br_matrix34* B, const br_matrix34* C)

Arguments:
br_matrix23 * A

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

const br_matrix23 * B

Pointer to the left hand source matrix.

const br_matrix23 * C

Pointer to the right hand source matrix.

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

BrMatrix23Pre()
176, BrMatrix23Post()179

## BrMatrix23Inverse()

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

Declaration:
br_scalar BrMatrix23Inverse(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

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

const br_matrix23 * 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:
The result in A is equivalent to the following:

BrMatrix23LPInverse()
173.

## BrMatrix23LPInverse()

Description:
Compute the inverse of the supplied length preserving
*1 transformation matrix. The resulting matrix is undefined for non-length preserving matrices.

Equivalent to the expression:

Declaration:
void BrMatrix23LPInverse(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

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

const br_matrix23 * B

A pointer to the source matrix.

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

BrMatrix23Inverse()172.

## BrMatrix23ApplyP()

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

Declaration:
void BrMatrix23ApplyP(br_vector2* A, const br_vector2* B, const br_matrix23* C)

Arguments:
br_vector2 * A

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

const br_vector2 * B

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

const br_matrix23 * C

A pointer to the transform matrix to be applied.

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

## BrMatrix23ApplyV()

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

Declaration:
void BrMatrix23ApplyV(br_vector2* A, const br_vector2* B, const br_matrix23* C)

Arguments:
br_vector2 * A

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

const br_vector2 * B

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

const br_matrix23 * C

A pointer to the transform matrix to be applied.

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

## BrMatrix23TApplyP()

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

Declaration:
void BrMatrix23TApplyP(br_vector2* A, const br_vector2* B, const br_matrix23* C)

Arguments:
br_vector2 * A

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

const br_vector2 * B

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

const br_matrix23 * C

A pointer to the transform matrix to be applied transposed - the translation elements are presumed zero or irrelevant.

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

## BrMatrix23TApplyV()

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

Declaration:
void BrMatrix23TApplyV(br_vector2* A, const br_vector2* B, const br_matrix23* C)

Arguments:
br_vector2 * A

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

const br_vector2 * B

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

const br_matrix23 * C

A pointer to the transform matrix to be applied transposed - the translation elements are presumed zero or irrelevant.

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

## BrMatrix23Pre()

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

Declaration:
void BrMatrix23Pre(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

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

const br_matrix23 * B

A pointer to the pre-multiplying matrix.

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

BrMatrix23Post()
179, BrMatrix23Mul()172

## BrMatrix23PreTranslate()

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

Declaration:
void BrMatrix23PreTranslate(br_matrix23* mat, br_scalar dx, br_scalar dy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar dx

The x axis component used to form the translation matrix.

br_scalar dy

The y axis component used to form the translation matrix.

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

BrMatrix23PostTranslate()
179, BrMatrix23Translate()184

## BrMatrix23PreScale()

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

Declaration:
void BrMatrix23PreScale(br_matrix23* mat, br_scalar sx, br_scalar sy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sx

Scaling component along the x axis.

br_scalar sy

Scaling component along the y axis.

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

BrMatrix23PostScale()
180, BrMatrix23Scale()185

## BrMatrix23PreShearX()

Description:
Pre-multiply a matrix by an x invariant shearing transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PreShearX(br_matrix23* mat, br_scalar sy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sy

Shear factor by which the x co-ordinate is included in the transformed y co-ordinate.

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

BrMatrix23PostShearX()
181, BrMatrix23ShearX()177

## BrMatrix23PreShearY()

Description:
Pre-multiply a matrix by a y invariant shearing transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PreShearY(br_matrix23* mat, br_scalar sx)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sx

Shear factor by which the y co-ordinate is included in the transformed x co-ordinate.

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

BrMatrix23PostShearY()
181, BrMatrix23ShearY()186

## BrMatrix23PreRotate()

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

Declaration:
void BrMatrix23PreRotate(br_matrix23* mat, br_angle rz)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_angle rz

The clockwise angle about the z axis used to form the rotation matrix.

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

BrMatrix23PostRotate()
182, BrMatrix23Rotate()186

## BrMatrix23Post()

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

Declaration:
void BrMatrix23Post(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

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

const br_matrix23 * B

A pointer to the post-multiplying matrix.

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

BrMatrix23Pre()
176, BrMatrix23Mul()172.

## BrMatrix23PostTranslate()

Description:
Post-multiply a matrix by a translation transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PostTranslate(br_matrix23* mat, br_scalar dx, br_scalar dy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar dx

The x axis component used to form the translation matrix.

br_scalar dy

The y axis component used to form the translation matrix.

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

BrMatrix23PreTranslate()
176, BrMatrix23Translate()184.

## BrMatrix23PostScale()

Description:
Post-multiply a matrix by a scaling transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PostScale(br_matrix23* mat, br_scalar sx, br_scalar sy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sx

Scaling component along the x axis.

br_scalar sy

Scaling component along the y axis.

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

BrMatrix23PreScale()
177, BrMatrix23Scale()185.

## BrMatrix23PostShearX()

Description:
Post-multiply a matrix by an x invariant shearing transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PostShearX(br_matrix23* mat, br_scalar sy)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sy

Shear factor by which the x co-ordinate is included in the transformed y coordinate.

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

BrMatrix23PreShearX()
177, BrMatrix23ShearX()185.

## BrMatrix23PostShearY()

Description:
Post-multiply a matrix by a y invariant shearing transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PostShearY(br_matrix23* mat, br_scalar sx)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_scalar sx

Shear factor by which the y co-ordinate is included in the transformed x coordinate.

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

BrMatrix23PreShearY()
181, BrMatrix23ShearY()186.

## BrMatrix23PostRotate()

Description:
Post-multiply a matrix by a rotational transform matrix. Equivalent to the expression:

Declaration:
void BrMatrix23PostRotate(br_matrix23* mat, br_angle rz)

Arguments:
br_matrix23 * mat

A pointer to the subject matrix.

br_angle rz

The clockwise angle about the z axis used to form the rotation matrix.

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

BrMatrix23PreRotate()
178, BrMatrix23Rotate()186.

## Copy/Assign

Although copy by structure assignment currently works, use BrMatrix23Copy()
182 to ensure compatibility.

## BrMatrix23Copy()

Description:
Copy a matrix. Equivalent to the expression:

Declaration:
void BrMatrix23Copy(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

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

const br_matrix23 * B

A pointer to the source matrix.

## Access & Maintenance

Members may be freely accessed. Maintenance is only required for length preserving matrices that have been modified.

## BrMatrix23LPNormalise()

Description:
Normalise a length preserving
*2 matrix. Equivalent to the expression:

Declaration:
void BrMatrix23LPNormalise(br_matrix23* A, const br_matrix23* B)

Arguments:
br_matrix23 * A

A pointer to the destination matrix, which must not point to the source matrix.

const br_matrix23 * B

A pointer to the source matrix.

Effects:
The destination matrix is the source matrix adjusted so that it represents a length preserving transformation.

Remarks:
This function is typically applied to a length preserving matrix which has undergone a long sequence of operations, to ensure that the final matrix is still truly length-preserving.

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, three BR_VECTOR2() macros would serve as well.

All other initialisation should use the functions BrMatrix23Identity()184, BrMatrix23Translate()184, BrMatrix23Scale()185, BrMatrix23Shear[X|Y]()185|186, BrMatrix23Rotate()186, or BrMatrix23Copy()182.

## BrMatrix23Identity()

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

Declaration:
void BrMatrix23Identity(br_matrix23* mat)

Arguments:
br_matrix23 * mat

A pointer to the destination matrix.

Effects:
Stores the identity matrix at the destination.

## BrMatrix23Translate()

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

Declaration:
void BrMatrix23Translate(br_matrix23* mat, br_scalar dx, br_scalar dy)

Arguments:
br_matrix23 * mat

A pointer to the destination matrix.

br_scalar dx

Translation component along the x axis.

br_scalar dy

Translation component along the y axis.

BrMatrix23PreTranslate()
176, BrMatrix23PostTranslate()179.

## BrMatrix23Scale()

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

Declaration:
void BrMatrix23Scale(br_matrix23* mat, br_scalar sx, br_scalar sy)

Arguments:
br_matrix23 * 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.

BrMatrix23PreScale()
177, BrMatrix23PostScale()180.

## BrMatrix23ShearX()

Description:
Set the specified matrix to a matrix representing a shear, invariant along the x axis. Thus values of y co-ordinates will be scaled in proportion to the value of the x co-ordinate. Equivalent to:

Declaration:
void BrMatrix23ShearX(br_matrix23* mat, br_scalar sy)

Arguments:
br_matrix23 * mat

A pointer to the destination matrix.

br_scalar sy

Shear factor by which the x co-ordinate is included in the transformed y co-ordinate.

BrMatrix23PreShearX()
177, BrMatrix23PostShearX()181.

## BrMatrix23ShearY()

Description:
Set the specified matrix to a matrix representing a shear, invariant along the y axis. Thus values of x co-ordinates will be scaled in proportion to the value of the y co-ordinate. Equivalent to:

Declaration:
void BrMatrix23ShearX(br_matrix23* mat, br_scalar sx)

Arguments:
br_matrix23 * mat

A pointer to the destination matrix.

br_scalar sx

Shear factor by which the y co-ordinate is included in the transformed x co-ordinate.

BrMatrix23PreShearY()
178, BrMatrix23PostShearY()181.

## BrMatrix23Rotate()

Description:
Set the specified matrix to a matrix representing a rotation about the z axis though a specified angle. Equivalent to:

Declaration:
void BrMatrix23Rotate(br_matrix23* mat, br_angle rz)

Arguments:
br_matrix23 * mat

A pointer to the destination matrix.

br_angle rz

Clockwise rotation about the z axis.