BRender Technical Reference Manual:4 Data Structures (Alphabetical Reference):br_vector3
Next|Prev|Up
The Structure
Members
Arithmetic
BrVector3Negate()
BrVector3Add()
BrVector3Accumulate()
BrVector3Sub()
BrVector3Scale()
BrVector3InvScale()
BrVector3Dot()
BrVector3Cross()
BrVector3Length()
BrVector3LengthSquared()
BrVector3Normalise()
BrVector3NormaliseQuick()
BrVector3NormaliseLP()
Copy/Assign
BrVector3Copy()
Referencing & Lifetime
Initialisation
BrVector3Set()
BrVector3SetFloat()
BrVector3SetInt()

br_vector3

The Structure

This is the three ordinate vector structure, typically used for 3D calculations. Functions are provided to allow it be used as though it were an integral type.

The typedef

(See vector.h for precise declaration and ordering)

br_scalar v[3] Ordinates (0=x, 1=y, 2=z)

Related Functions

Image Support

See BrOriginToScreenXYZO()252, BrPointToScreenXYZO()252, BrPointToScreenXYZOMany()253.

Maths

See BrMatrix34[Pre|Post]Rotate()[197|201], BrMatrix[34|4][T]Apply[V|P]()[190-193|216-219].

Related Structures

See br_matrix23171, br_matrix34187, br_model228, br_vertex367, br_transform339, br_bounds105.

Members

br_scalar v[3]

First, second and third ordinate. Conventionally, the first ordinate is the x-axis component, the second, the y axis component, and the third, the z axis component. Remember that BRender has a right handed co-ordinate system and so, with the x axis positive to the right, and the y axis positive upwards, the z axis is therefore positive toward you (typically, the z axis points out of the screen).

Arithmetic

BrVector3Negate()

Description:
Negate a vector and place the result in a second destination vector. Equivalent to the expression:

Declaration:
void BrVector3Negate(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

BrVector3Add()

Description:
Add two vectors and place the result in a third destination vector.

Equivalent to the expression:

Declaration:
void BrVector3Add(br_vector3* v1, const br_vector3* v2, const br_vector3* v3)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the first vector of the sum.

const br_vector3 * v3

A pointer to the second vector of the sum.

BrVector3Accumulate()

Description:
Add one vector to another. Equivalent to the expression:

Declaration:
void BrVector3Accumulate(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

A pointer to the accumulating vector (may be same as v2).

const br_vector3 * v2

A pointer to the vector to add.

BrVector3Sub()

Description:
Subtract one vector from another and place the result in a third destination vector.

Equivalent to the expression:

Declaration:
void BrVector3Sub(br_vector3* v1, const br_vector3* v2, const br_vector3* v3)

Arguments:
br_vector3 * v1

A pointer to the destination vector (may be same as v2 or v3).

const br_vector3 * v2

A pointer to the additive vector.

const br_vector3 * v3

A pointer to the subtractive vector.

BrVector3Scale()

Description:
Scale a vector by a scalar and place the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3Scale(br_vector3* v1, const br_vector3* v2, br_scalar s)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

br_scalar s

Scale factor.

BrVector3InvScale()

Description:
Scale a vector by the reciprocal of a scalar and place the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3InvScale(br_vector3* v1, const br_vector3* v2, br_scalar s)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

br_scalar s

Reciprocal scale factor.

BrVector3Dot()

Description:
Calculate the dot product of two vectors. Equivalent to the expression:

Declaration:
br_scalar BrVector3Dot(const br_vector3* v1, const br_vector3* v2)

Arguments:
const br_vector3 * v1

Pointer to left hand vector (may be same as v2).

const br_vector3 * v2

Pointers to right hand vector (may be same as v1).

Result:
br_scalar

Returns the dot product of the two source vectors. Equivalent to:

BrVector3Cross()

Description:
Calculate the cross product of two vectors and store the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3Cross(br_vector3* v1, const br_vector3* v2, const br_vector3* v3)

Arguments:
br_vector3 * v1

Pointer to destination vector (must be different from both v1 and v2).

const br_vector3 * v2

Pointer to left hand vector.

const br_vector3 * v3

Pointers to right hand vector.

Remarks:
The cross product of the two source vectors is equivalent to:

BrVector3Length()

Description:
Calculate the length of a vector. Equivalent to the expression:

Declaration:
br_scalar BrVector3Length(const br_vector3* v1)

Arguments:
const br_vector3 * v1

A pointer to the source vector.

Result:
br_scalar

Returns the length of the vector. Equivalent to:

See Also:
BrVector3LengthSquared()360

BrVector3LengthSquared()

Description:
Calculate the squared length of a vector. Equivalent to the expression:

or

Declaration:
br_scalar BrVector3LengthSquared(const br_vector3* v1)

Arguments:
const br_vector3 * v1

A pointer to the source vector.

Result:
br_scalar

Returns the squared length of the vector. Equivalent to:

See Also:
BrVector3Length()360

BrVector3Normalise()

Description:
Normalise a vector and place the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3Normalise(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

Remarks:
If the source vector's length is zero*1 the unit vector along the x axis is stored at the destination instead.

BrVector3NormaliseQuick()

Description:
Normalise a vector with non-zero length and place the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3NormaliseQuick(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

Remarks:
No check made for zero length, hence quicker.

BrVector3NormaliseLP()

Description:
Normalise a vector with non-zero length using low precision*2 arithmetic and place the result in a destination vector. Equivalent to the expression:

Declaration:
void BrVector3NormaliseLP(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

Remarks:
No check is made for zero length. The destination vector will be left unchanged if the reciprocal of length of the vector is zero.

Copy/Assign

Although copy by structure assignment currently works, use BrVector3Copy()362 to ensure compatibility.

BrVector3Copy()

Description:
Copy a vector. Equivalent to the expression:

Declaration:
void BrVector3Copy(br_vector3* v1, const br_vector3* v2)

Arguments:
br_vector3 * v1

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

const br_vector3 * v2

A pointer to the source vector.

Referencing & Lifetime

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

Initialisation

The following macro may be used as a static initialiser.

BR_VECTOR3(a,b,c)
Macro expands to {BR_SCALAR(a),BR_SCALAR(b),BR_SCALAR(c)}.

All other initialisation should use the functions, BrVector3Set()363, BrVector3SetInt()364, BrVector3SetFloat()363 or BrVector3Copy()362.

BrVector3Set()

Description:
Set a vector with a triple of scalars.

Declaration:
void BrVector3Set(br_vector3* v1, br_scalar s1, br_scalar s2, br_scalar s3)

Arguments:
br_vector3 * v1

A pointer to the destination vector.

br_scalar s1

The first vector element (x axis component).

br_scalar s2

The second vector element (y axis component).

br_scalar s3

The third vector element (z axis component).

Example:
br_vector3 *va;
...
BrVector3Set(va,BR_SCALAR(1.0),BR_SCALAR(-1.0),BR_SCALAR(2.0));

BrVector3SetFloat()

Description:
Set a vector from a triple of standard C floating point numbers.

Declaration:
void BrVector3SetFloat(br_vector3* v1, float f1, float f2, float f3)

Arguments:
br_vector3 * v1

A pointer to the destination vector.

float f1

The first vector element (x axis component).

float f2

The second vector element (y axis component).

float f3

The third vector element (z axis component).

Example:
br_vector3 *va;
...
BrVector3Set(va,1.f,-1.f,1.5f);

BrVector3SetInt()

Description:
Set a vector from a triple of standard C integers.

Declaration:
void BrVector3SetInt(br_vector3* v1, int i1, int i2, int i3)

Arguments:
br_vector3 * v1

A pointer to the destination vector.

int i1

The first vector element (x axis component).

int i2

The second vector element (y axis component).

int i3

The third vector element (z axis component).

Example:
br_vector3 *va;
...
BrVector3Set(va,1,-1,2);

Generated with CERN WebMaker