BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_transform
Next|Prev|Up
The Structure
Members
Arithmetic
Conversion
BrTransformToMatrix34()
BrTransformToTransform()
Copy/Assign
Access & Maintenance
Referencing & Lifetime
Initialisation

br_transform


The Structure

This is BRender's generic transformation type, primarily used to specify a transformation from one actor's space to another's. In an actor it represents the transform to be applied to co-ordinates (such as of a model) in its space to bring them into the co-ordinate space of its parent.

The typedef

(See transform.h for precise declaration and ordering)

Transform Type

br_uint_16 type Specifies how the transformation is represented.

Translation Transform

br_vector3 t.translate.t Translation for the Translation transform type

Euler Transform

br_vector3 t.euler.t Translation for the Euler transform type

br_euler t.euler.e Euler angle set of the Euler transform type

Look Up Transform

br_vector3 t.look_up.t Translation for the Look Up transform type

br_vector3 t.look_up.look Look-at vector for the Look Up transform type

br_vector3 t.look_up.up Look-up vector for the Look Up transform type

Quaternion Transform

br_vector3 t.quat.t Translation for the Quaternion transform type

br_quat t.quat.q Quaternion rotation for the Quaternion transform type

Matrix Transform

br_matrix34 t.mat Matrix34 for both Matrix transform types

Related Functions

Scene Modelling

See BrActorToActorMatrix34()
82 and BrActorToScreenMatrix4()83.

Related Structures

Scene Modelling

See br_actor74.

Members

Transform Type

br_uint_16 type

This member defines which other members of the transform structure have meaning. It should never be modified directly except for initialisation purposes. Refer to BrTransformToTransform()343 for details of how to convert from one transform to another.

This member may have any one of the following values:

Identity Transform

The identity transform is engaged when type is set to BR_TRANSFORM_IDENTITY. This is effectively a Null transform, making actors effectively share the same co-ordinate space as their parent.

Translation Transform

The translation transform is engaged when type is set to BR_TRANSFORM_TRANSLATION. This is solely a translation, i.e. no rotation or scaling is involved.

br_vector3 t.translate.t

This member only has meaning for this transform type
*1. It contains the vector representing the translation.

Euler Transform

The Euler transform is engaged when type is set to BR_TRANSFORM_EULER. This consists of a three rotations about a combination of orthogonal axes and a translation (effectively applied after the rotations). See br_euler118 for more information.

br_vector3 t.euler.t

This member contains the vector representing the translation component of the transform.

br_vector3 t.euler.e

This member contains the vector representing the rotation components of the transform.

Look Up Transform*2

The Look Up transform effectively consists of a pair of rotations and a translation. The first rotation is defined about the origin between the negative z axis and the look vector. The second rotation is defined about the new z axis between the new positive x axis and the cross product of the up and look vectors. The translation is then applied.

The Look Up transform is a convenient method of making an actor such as a camera point toward a particular position. It has the effect of making the actor's negative*3 z axis lie along the look vector, and its positive y axis lie in the plane defined by the up and look vectors (or more precisely, its positive x axis will lie along the cross product of the up and look vectors). Remember that the look and up vectors will be in the co-ordinate space of the actor's parent and thus from its point of view, so if pointing at a particular actor, in order to compute look, that actor's co-ordinates will also need to be transformed into the co-ordinate space of the parent (see BrActorToActorMatrix34()82). Incidentally, things can be simplified by using intermediate dummy actors (BR_ACTOR_NONE).

The translation is applied at the end.

br_vector3 t.look_up.t

This member contains the vector representing the translation component of the transform.

br_vector3 t.look_up.look

This member contains the vector that defines the rotation of the negative z axis.

br_vector3 t.look_up.up

This member contains the vector that defines the rotation about the look vector.

Quaternion Transform

The unit quaternion transform represents a rotation about an arbitrary vector.

br_vector3 t.quat.t

This member contains the vector representing the translation component of the transform.

br_vector3 t.quat.q

This member contains the vector representing the rotation component of the transform.

Matrix Transforms

Matrix transforms represent BRender's most general form of transformation. See br_matrix34187 for details of how matrix transformations are performed.

BR_TRANSFORM_MATRIX34_LP is a slightly more specialised form which requires that the matrix have no scaling effect, i.e. is length preserving.

br_matrix34 t.mat

This member contains the 3D affine matrix representing the entire transform.

Arithmetic

See BrMatrix34PreTransform()198, BrMatrix34PostTransform()203, and BrMatrix4PreTransform()220.

Conversion

Also see BrMatrix34ToEuler()204, BrMatrix34ToQuat()204, BrEulerToMatrix34()120 and BrQuatToMatrix34()314.

From Matrices and Other Transforms

See BrMatrix34ToTransform()204 and BrTransformToTransform()343.

To Matrices and Other Transforms

See BrTransformToMatrix34()343 and BrTransformToTransform()343 as described below.


BrTransformToMatrix34()

Description:
Convert a generic transform to a 3D affine matrix, that would have the same transformational effect.

Declaration:
void BrTransformToMatrix34(br_matrix34* mat, const br_transform* xform)

Arguments:
br_matrix34 * mat

A pointer to the destination matrix to receive the conversion.

const br_transform * xform

A pointer to the source generic transform.

Effects:
When the transform is the identity

Uses to BrMatrix34Identity()207 to re-initialise the destination matrix to the identity matrix.

When the transform is a translation

Uses to BrMatrix34Translate()208 to re-initialise the destination matrix to a translation matrix.

When the transform is a Euler angle set

Calls BrEulerToMatrix34()120 and copies the transforms' translation to the respective elements of the destination matrix.

When the transform is a Look-Up

The normalised and negated Look vector provides the third row of the matrix.

The normalised cross product of this with the Up vector provides the first row.

The cross product of these two rows provides the second row.

The translation vector provides the fourth and last row.

When the transform is a quaternion

Calls BrQuatToMatrix34()314 and copies the transforms' translation to the respective elements of the destination matrix.

When the transform is a 34 matrix

Directly copies the matrix from the source transform.

When the transform is a 34 length preserving matrix

Directly copies the matrix from the source transform.


BrTransformToTransform()

Description:
Convert from one transform to another, that would have the same transformational effect (where possible).

Declaration:
void BrTransformToTransform(br_transform* dest, const br_transform* src)

Arguments:
br_transform * dest

A pointer to the destination generic transform to receive the conversion. The destination's type member is unchanged.

const br_transform * src

A pointer to the source generic transform to be converted.

Effects:
When the transforms' types are the same

The transform structure is copied entire.

When the destination transform is of matrix type

Calls BrTransformToMatrix34()343 then normalises if necessary.

In other cases

Converts the transform via an intermediate 3x4 matrix by first calling BrTransformToMatrix34()343 and then BrMatrix34ToTransform()204.

Remarks:
The transformation type in the destination transform must be set before conversion is performed*4.

In some cases it may not be possible to preserve all components of a transformation across the conversion. For example, a conversion of a matrix to a quaternion would lose any scaling or shearing components.


Copy/Assign

Although copy by structure assignment currently works, use BrTransformToTransform()
343 to ensure compatibility.

Access & Maintenance

Only the members corresponding to the currently set type should be accessed. The type should not be modified except for initialisation. The structure may be re-initialised, but any current references must be expecting this. No specific maintenance required, but refer to the descriptions of underlying structures for details of their maintenance requirements.

Referencing & Lifetime

This structure may be freely referenced, though take care when changing the type of a transform that any current references will take note. In the same vein, try to avoid referencing members of `live' transforms. The structure should remain valid as long as required by any references.

Initialisation

First set the type member to the desired transform type and then initialise the appropriate members using their respective assignment methods. The simplest initialisation is to the Identity, which is also the only safe static initialisation.


Generated with
CERN WebMaker