BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_quat

The Structure
Members
Arithmetic
BrQuatMul()
BrQuatInvert()
BrQuatSlerp()
Conversion
BrQuatToEuler()
BrQuatToMatrix34()
BrQuatToMatrix4()
Copy/Assign
Access & Maintenance
BrQuatNormalise()
Initialisation

`br_quat`

The Structure

The quaternion is an extension of the complex number, with the addition of two further imaginary components. BRender restricts itself to using unit quaternions, which have the useful property of being able to easily represent a 3D transform consisting of a rotation about an arbitrary vector.

The x, y and z components of the quaternion hold the elements of this vector scaled to a length equal to the sine of half the angle of rotation. The w component holds the cosine of half the angle. The magnitude of a unit quaternion is of course 1 (w2+x2+y2+z2=1).

The quaternion is written thus:

NB Do not confuse the quaternion with 3D vectors or homogenous co-ordinates, i.e. br_quat311 and br_vector4365 have no relationship.

The `typedef`

(See quat.h for precise declaration and ordering)

br_scalar w Real component

br_scalar x `i' component (vector, x axis component)

br_scalar y `j' component (vector, y axis component)

br_scalar z `k' component (vector, z axis component)

Related Functions

Maths

See BrEulerToQuat()120, BrMatrix34ToQuat()204, BrMatrix4ToQuat()222.

Related Structures

See br_transform339.

Members

`br_scalar w`

Real component of quaternion. Represents the cosine of half the rotation about the (i,j,k) vector component of the quaternion.

`br_scalar x`

First imaginary component of quaternion. Represents the x axis component of the vector about which the rotation occurs.

`br_scalar y`

Second imaginary component of quaternion. Represents the y axis component of the vector about which the rotation occurs.

`br_scalar z`

Third imaginary component of quaternion. Represents the z axis component of the vector about which the rotation occurs.

Arithmetic

`BrQuatMul()`

Multiply two quaternions.

br_quat* BrQuatMul(br_quat* q, const br_quat* l, const br_quat* r)

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

const br_quat * l

A pointer to the left hand source quaternion.

const br_quat * r

A pointer to the right hand source quaternion.

The resultant quaternion is computed as follows:

The destination quaternion pointer is returned as supplied for convenience.

Quaternion multiplication has the effect of concatenating the individual transformations that each represents. It is not commutative.

`BrQuatInvert()`

Obtain the inverse of a unit quaternion. This is effectively the rotation reversed (about the same vector component).

br_quat* BrQuatInvert(br_quat* q, const br_quat* qq)

A pointer to the destination quaternion (can be same as source).

const br_quat * qq

A pointer to the source quaternion.

The resultant quaternion is computed as follows:

The destination quaternion pointer is returned as supplied for convenience.

`BrQuatSlerp()`

The `Slerp' operation (spherical, linear interpolation) interpolates linearly between two quaternions along the most direct path between the two orientations.

br_quat* BrQuatSlerp(br_quat* q, const br_quat* l, const br_quat* r, br_scalar t, br_int_16 spins)

A pointer to the destination quaternion (can be same as either source).

const br_quat * l

A pointer to the starting quaternion (equivalent to result with t=0).

const br_quat * l

A pointer to the finishing quaternion (equivalent to result with t=1).

br_scalar t

Interpolation parameter in the range [0,1].

br_int_16

Number of extra spins in the interpolated path.

A special value of zero causes interpolation along the shortest path.

A special value of -1 causes interpolation along the longest path.

Computes the quaternion between l and r corresponding to position t along the interpolated path between them.

The destination quaternion pointer is returned as supplied for convenience.

Conversion

From Eulers and Matrices

See BrEulerToQuat()120, BrMatrix34ToQuat()204, BrMatrix4ToQuat()222.

To Eulers and Matrices

See BrQuatToEuler()314, BrQuatToMatrix34()314, and BrQuatToMatrix4()315 as described below.

Also see BrTransformToTransform()343.

`BrQuatToEuler()`

Convert a unit quaternion to an Euler angle set, that would have the same transformational effect.

br_euler* BrQuatToEuler(br_euler* euler, const br_quat* q)

br_euler * euler

A pointer to the destination Euler angle set to receive the conversion.

const br_quat * q

A pointer to the source unit quaternion.

Returns euler for convenience.

`BrQuatToMatrix34()`

Convert a unit quaternion to a 3D affine matrix, that would have the same transformational effect.

br_matrix34* BrQuatToMatrix34(br_matrix34* mat, const br_quat* q)

br_matrix34 * mat

A pointer to the destination matrix to receive the conversion.

const br_quat * q

A pointer to the source unit quaternion.

br_matrix34 *

Returns mat for convenience.

The resulting matrix at mat is equivalent to the following:

`BrQuatToMatrix4()`

Convert a unit quaternion to a 3D affine matrix, that would have the same transformational effect.

br_matrix4* BrQuatToMatrix4(br_matrix4* mat, const br_quat* q)

br_matrix4 * mat

A pointer to the destination matrix to receive the conversion.

const br_quat * q

A pointer to the source unit quaternion.

Returns mat for convenience.

BrQuatToMatrix34()314.

Copy/Assign

Use structure assignment to copy quaternions.

Access & Maintenance

Members may be freely accessed. Maintenance is only required for unit quaternions that have been modified.

`BrQuatNormalise()`

Normalise a quaternion.

br_quat* BrQuatNormalise(br_quat* q, const br_quat* qq)

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

const br_quat * qq

A pointer to the source quaternion.

The destination is each element of the source divided by its magnitude.

BRender assumes that only unit quaternions are used, and due to this assumption being embodied in certain calculations, if non-unit quaternions are used it is likely that unwanted side effects such as scaling will be introduced. This function ensures that the quaternion is a unit one, and is intended to be applied to unit quaternions that have resulted from a large number of intermediate calculations and may have drifted (due to precision limitations) from unit magnitude.

Initialisation

The following macro may be used as a static initialiser. Note the order in which the components are specified.

BR_QUAT(x,y,z,w)

Macro expands to {BR_SCALAR(x),BR_SCALAR(y),BR_SCALAR(z),BR_SCALAR(w)}.

All other initialisation should be member-wise or by using structure assignment.

Generated with CERN WebMaker