QuesaMath.h

Discussion

Functions

( TQ3BoundingBox * ) Q3BoundingBox_Copy (
    const TQ3BoundingBox *bBox,
    TQ3BoundingBox *result
);

Discussion

Copy a bounding box.

Available in inline form as Q3BFastoundingBox_Copy.

Parameter Descriptions

bBox

Address of source bounding box.

result

Address of bounding box to set (may be the same as bBox).

function result

Convenience copy of result parameter.

( TQ3BoundingBox * ) Q3BoundingBox_Reset (
    TQ3BoundingBox *bBox
);

Discussion

Reset (set to empty) a bounding box.

Available in inline form as Q3FastBoundingBox_Reset.

Parameter Descriptions

bBox

Address of bounding box to reset.

function result

Convenience copy of bBox parameter.

( TQ3BoundingBox * ) Q3BoundingBox_Set (
    TQ3BoundingBox *bBox,
    const TQ3Point3D *min,
    const TQ3Point3D *max,
    TQ3Boolean isEmpty
);

Discussion

Set a bounding box.

Available in inline form as Q3FastBoundingBox_Set.

Parameter Descriptions

bBox

Address of bounding box to set.

min

Address of point indicating minimum X, Y, and Z.

max

Address of point indicating maximum X, Y, and Z.

isEmpty

True if the bounding box is empty, false otherwise.

function result

Convenience copy of bBox parameter.

( TQ3BoundingBox * ) Q3BoundingBox_SetFromPoints3D (
    TQ3BoundingBox *bBox,
    const TQ3Point3D *points3D,
    TQ3Uns32 numPoints,
    TQ3Uns32 structSize
);

Discussion

Set a bounding box to just enclose a set of 3D points.

Parameter Descriptions

bBox

Address of bounding box to set.

points3D

Array of 3D points.

numPoints

How many points are in the array.

structSize

Size of each array element, typically sizeof(TQ3Point3D).

function result

Convenience copy of bBox parameter.

( TQ3BoundingBox * ) Q3BoundingBox_SetFromRationalPoints4D (
    TQ3BoundingBox *bBox,
    const TQ3RationalPoint4D *rationalPoints4D,
    TQ3Uns32 numPoints,
    TQ3Uns32 structSize
);

Discussion

Set a bounding box to just enclose a set of 4D rational points.

Parameter Descriptions

bBox

Address of bounding box to set.

rationalPoints4D

Array of 4D rational points.

numPoints

How many points are in the array.

structSize

Size of each array element, typically sizeof(TQ3RationalPoint4D).

function result

Convenience copy of bBox parameter.

( TQ3BoundingBox * ) Q3BoundingBox_Union (
    const TQ3BoundingBox *b1,
    const TQ3BoundingBox *b2,
    TQ3BoundingBox *result
);

Discussion

Compute the minimum bounding box that encloses both 'b1' and 'b2'.

Parameter Descriptions

b1

Address of one bounding box.

b2

Address of another bounding box.

result

Address of bounding box to set (may be the same as b1 and/or b2).

function result

Convenience copy of result parameter.

( TQ3BoundingBox * ) Q3BoundingBox_UnionPoint3D (
    const TQ3BoundingBox *bBox,
    const TQ3Point3D *point3D,
    TQ3BoundingBox *result
);

Discussion

Return the minimum bounding box that encloses both 'bBox' and 'point3D'.

Parameter Descriptions

bBox

Address of initial bounding box.

point3D

Address of a point to enclose.

result

Address of bounding box to set (may be the same as bBox).

function result

Convenience copy of result parameter.

( TQ3BoundingBox * ) Q3BoundingBox_UnionRationalPoint4D (
    const TQ3BoundingBox *bBox,
    const TQ3RationalPoint4D *rationalPoint4D,
    TQ3BoundingBox *result
);

Discussion

Return the minimum bounding box that encloses both 'bBox' and 'rationalPoint4D'.

Parameter Descriptions

bBox

Address of initial bounding box.

rationalPoint4D

Address of a point to enclose.

result

Address of bounding box to set (may be the same as bBox).

function result

Convenience copy of result parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_Copy (
    const TQ3BoundingSphere *bSphere,
    TQ3BoundingSphere *result
);

Discussion

Copy a bounding sphere.

Available in inline form as Q3FastBoundingSphere_Copy.

Parameter Descriptions

bSphere

Address of source bounding sphere.

result

Address of bounding sphere to set (may be the same as bSphere).

function result

Convenience copy of result parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_Reset (
    TQ3BoundingSphere *bSphere
);

Discussion

Reset (set to empty) a bounding sphere.

Available in inline form as Q3FastBoundingSphere_Reset.

Parameter Descriptions

bSphere

Address of bounding sphere to reset.

function result

Convenience copy of bSphere parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_Set (
    TQ3BoundingSphere *bSphere,
    const TQ3Point3D *origin,
    float radius,
    TQ3Boolean isEmpty
);

Discussion

Set a bounding sphere.

Available in inline form as Q3FastBoundingSphere_Set.

Parameter Descriptions

bSphere

Address of bounding sphere to set.

origin

Address of point indicating sphere origin.

radius

Sphere radius.

isEmpty

True if the bounding sphere is empty, false otherwise.

function result

Convenience copy of bSphere parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_SetFromPoints3D (
    TQ3BoundingSphere *bSphere,
    const TQ3Point3D *points3D,
    TQ3Uns32 numPoints,
    TQ3Uns32 structSize
);

Discussion

Set a bounding sphere to just enclose a set of 3D points.

Parameter Descriptions

bSphere

The bounding sphere to update.

points3D

Array of 3D points.

numPoints

How many points are in the array.

structSize

Size of each array element, typically sizeof(TQ3Point3D).

function result

Convenience copy of bSphere parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_SetFromRationalPoints4D (
    TQ3BoundingSphere *bSphere,
    const TQ3RationalPoint4D *rationalPoints4D,
    TQ3Uns32 numPoints,
    TQ3Uns32 structSize
);

Discussion

Set a bounding sphere to just enclose a set of 4D rational points.

Parameter Descriptions

bSphere

Address of bounding sphere to set.

rationalPoints4D

Array of 4D rational points.

numPoints

How many points are in the array.

structSize

Size of each array element, typically sizeof(TQ3RationalPoint4D).

function result

Convenience copy of bSphere parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_Union (
    const TQ3BoundingSphere *s1,
    const TQ3BoundingSphere *s2,
    TQ3BoundingSphere *result
);

Discussion

Compute the minimum bounding sphere that encloses both 's1' and 's2'.

Parameter Descriptions

s1

Address of one bounding sphere.

s2

Address of another bounding sphere.

result

Address of bounding sphere to set (may be the same as s1 and/or s2).

function result

Convenience copy of result parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_UnionPoint3D (
    const TQ3BoundingSphere *bSphere,
    const TQ3Point3D *point3D,
    TQ3BoundingSphere *result
);

Discussion

Return the minimum bounding sphere that encloses both 'bSphere' and 'point3D'.

Parameter Descriptions

bSphere

Address of initial bounding sphere.

point3D

Address of a point to enclose.

result

Address of bounding sphere to set (may be the same as bSphere).

function result

Convenience copy of result parameter.

( TQ3BoundingSphere * ) Q3BoundingSphere_UnionRationalPoint4D (
    const TQ3BoundingSphere *bSphere,
    const TQ3RationalPoint4D *rationalPoint4D,
    TQ3BoundingSphere *result
);

Discussion

Return the minimum bounding sphere that encloses both 'bSphere' and 'rationalPoint4D'.

Parameter Descriptions

bSphere

Address of initial bounding sphere.

rationalPoint4D

Address of a point to enclose.

result

Address of bounding sphere to set (may be the same as bSphere).

function result

Convenience copy of result parameter.

( float ) Q3Math_InvSquareRoot (
    float x
);

Discussion

Obtain a fast, but possibly inaccurate, inverse square root.

The available precision depends on the current architecture, but will suffice for most non-accumulating 3D operations. If a reliable degree of precision is required, 1.0/sqrt() should be used instead.

Parameter Descriptions

x

The number whose inverse square root should be returned.

function result

Approximate inverse square root of x.

( float ) Q3Math_SquareRoot (
    float x
);

Discussion

Obtain a fast, but possibly inaccurate, square root.

The available precision depends on the current architecture, but will suffice for most non-accumulating 3D operations. If a reliable degree of precision is required, sqrt() should be used instead.

Parameter Descriptions

x

The number whose square root should be returned.

function result

Approximate square root of x.

( TQ3Matrix3x3 * ) Q3Matrix3x3_Adjoint (
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Matrix3x3 *result
);

Discussion

Calculate adjoint of 3x3 matrix.

The adjoint of a matrix is a scalar multiple of the inverse of the matrix. For some applications, the adjoint can be used in place of the inverse. In particular:

adjoint(A) = determinant(A) * inverse(A)

Parameter Descriptions

matrix3x3

Address of a matrix to calculate the adjoint of.

result

Address of matrix to set (may be the same as matrix3x3).

function result

Convenience copy of result parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_Copy (
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Matrix3x3 *result
);

Discussion

Copy a 3x3 matrix.

Parameter Descriptions

matrix3x3

Address of source matrix.

result

Address of destination matrix (may be the same as matrix3x3).

function result

Convenience copy of result parameter.

( float ) Q3Matrix3x3_Determinant (
    const TQ3Matrix3x3 *matrix3x3
);

Discussion

Return the determinant of 3x3 matrix.

Parameter Descriptions

matrix3x3

Address of a matrix.

function result

Determinant of that matrix.

( TQ3Matrix3x3 * ) Q3Matrix3x3_Invert (
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Matrix3x3 *result
);

Discussion

Calculate the inverse of a 3x3 non-singular matrix.

Parameter Descriptions

matrix3x3

Address of non-singular matrix to invert.

result

Address of matrix to set (may be the same as matrix3x3).

function result

Convenience copy of result parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_Multiply (
    const TQ3Matrix3x3 *m1,
    const TQ3Matrix3x3 *m2,
    TQ3Matrix3x3 *result
);

Discussion

Multiply two 3x3 matrices.

Parameter Descriptions

m1

Address of first matrix.

m2

Address of second matrix.

result

Address of matrix to set with m1*m2 (may be the same as m1 and/or m2).

function result

Convenience copy of result parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_SetIdentity (
    TQ3Matrix3x3 *matrix3x3
);

Discussion

Set a 3x3 matrix to the identity matrix.

Parameter Descriptions

matrix3x3

Address of matrix to set.

function result

Convenience copy of matrix3x3 parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_SetRotate (
    TQ3Matrix3x3 *matrix3x3,
    float angle
);

Discussion

Set a 3x3 matrix to rotate about the origin.

Parameter Descriptions

matrix3x3

Address of matrix to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix3x3 parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_SetRotateAboutPoint (
    TQ3Matrix3x3 *matrix3x3,
    const TQ3Point2D *origin,
    float angle
);

Discussion

Set a 3x3 matrix to rotate about a point.

This is equivalent to translating the point to the origin, doing a rotation about the origin, and translating back.

Parameter Descriptions

matrix3x3

Address of matrix to set.

origin

Address of a 2D point about which to rotate.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix3x3 parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_SetScale (
    TQ3Matrix3x3 *matrix3x3,
    float xScale,
    float yScale
);

Discussion

Set 3x3 matrix to scale in x, y.

Parameter Descriptions

matrix3x3

Address of matrix to set.

xScale

Amount to scale in x.

yScale

Amount to scale in y.

function result

Convenience copy of matrix3x3 parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_SetTranslate (
    TQ3Matrix3x3 *matrix3x3,
    float xTrans,
    float yTrans
);

Discussion

Set a 3x3 matrix to translate in x, y.

Parameter Descriptions

matrix3x3

Address of matrix to set.

xTrans

Amount to translate in x.

yTrans

Amount to translate in y.

function result

Convenience copy of matrix3x3 parameter.

( TQ3Matrix3x3 * ) Q3Matrix3x3_Transpose (
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Matrix3x3 *result
);

Discussion

Transpose a 3x3 matrix.

Parameter Descriptions

matrix3x3

Address of a matrix to transpose.

result

Address of matrix to set (may be the same as matrix3x3).

function result

Convenience copy of result parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_Copy (
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Matrix4x4 *result
);

Discussion

Copy a 4x4 matrix.

Parameter Descriptions

matrix4x4

Address of source matrix.

result

Address of destination matrix (may be the same as matrix4x4).

function result

Convenience copy of result parameter.

( float ) Q3Matrix4x4_Determinant (
    const TQ3Matrix4x4 *matrix4x4
);

Discussion

Return the determinant of 4x4 matrix.

Parameter Descriptions

matrix4x4

Address of a matrix.

function result

Determinant of that matrix.

( TQ3Matrix4x4 * ) Q3Matrix4x4_Invert (
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Matrix4x4 *result
);

Discussion

Calculate the inverse of a 4x4 non-singular matrix.

Parameter Descriptions

matrix4x4

Address of non-singular matrix to invert.

result

Address of matrix to set (may be the same as matrix4x4).

function result

Convenience copy of result parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_Multiply (
    const TQ3Matrix4x4 *m1,
    const TQ3Matrix4x4 *m2,
    TQ3Matrix4x4 *result
);

Discussion

Multiply two 4x4 matrices.

Parameter Descriptions

m1

Address of first matrix.

m2

Address of second matrix.

result

Address of matrix to set with m1*m2 (may be the same as m1 and/or m2).

function result

Convenience copy of result parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetIdentity (
    TQ3Matrix4x4 *matrix4x4
);

Discussion

Set a 4x4 matrix to the identity matrix.

Parameter Descriptions

matrix4x4

Address of matrix to set.

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetQuaternion (
    TQ3Matrix4x4 *matrix4x4,
    const TQ3Quaternion *quaternion
);

Discussion

Set a 4x4 matrix from to the rotation represented by a quaternion.

Parameter Descriptions

matrix4x4

Address of matrix to set.

quaternion

Address of the quaternion to imitate.

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotateAboutAxis (
    TQ3Matrix4x4 *matrix4x4,
    const TQ3Point3D *origin,
    const TQ3Vector3D *axis,
    float angle
);

Discussion

Set 4x4 matrix to rotate about an arbitrary origin and axis.

Note that for correct results, the axis should be normalized (i.e. have length = 1).

Parameter Descriptions

matrix4x4

Address of matrix to set.

origin

Address of a 2D point about which to rotate.

axis

Address of a 3D vector to use as the rotation axis.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotateAboutPoint (
    TQ3Matrix4x4 *matrix4x4,
    const TQ3Point3D *origin,
    float xAngle,
    float yAngle,
    float zAngle
);

Discussion

Set a 4x4 matrix to rotate about axes through a point and parallel to the X, Y, and Z axes (in that order).

This order of rotations is rarely useful, but it's kept for backwards compatibility with QD3D.

Parameter Descriptions

matrix4x4

Address of matrix to set.

origin

Address of a 3D point about which to rotate.

xAngle

Angle to rotate about the translated X axis (in radians).

yAngle

Angle to rotate about the translated Y axis (in radians).

zAngle

Angle to rotate about the translated Z axis (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotateVectorToVector (
    TQ3Matrix4x4 *matrix4x4,
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2
);

Discussion

Set a 4x4 matrix to rotate vector 'v1' to 'v2'.

Note that for correct results, both vectors should be normalized (i.e. have length = 1).

Parameter Descriptions

matrix4x4

Address of matrix to set.

v1

Address of "starting" vector.

v2

Address of "ending" vector.

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotate_X (
    TQ3Matrix4x4 *matrix4x4,
    float angle
);

Discussion

Set a 4x4 matrix to rotate about the X axis.

Parameter Descriptions

matrix4x4

Address of matrix to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotate_XYZ (
    TQ3Matrix4x4 *matrix4x4,
    float xAngle,
    float yAngle,
    float zAngle
);

Discussion

Set a 4x4 matrix to rotate about the X, Y, Z axes (in that order).

This order of rotations is rarely useful, but it's kept for backwards compatibility with QD3D.

Parameter Descriptions

matrix4x4

Address of matrix to set.

xAngle

Angle to rotate about the X axis (in radians).

yAngle

Angle to rotate about the Y axis (in radians).

zAngle

Angle to rotate about the Z axis (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotate_Y (
    TQ3Matrix4x4 *matrix4x4,
    float angle
);

Discussion

Set a 4x4 matrix to rotate about the Y axis.

Parameter Descriptions

matrix4x4

Address of matrix to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetRotate_Z (
    TQ3Matrix4x4 *matrix4x4,
    float angle
);

Discussion

Set a 4x4 matrix to rotate about the Z axis.

Parameter Descriptions

matrix4x4

Address of matrix to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetScale (
    TQ3Matrix4x4 *matrix4x4,
    float xScale,
    float yScale,
    float zScale
);

Discussion

Set a 4x4 matrix to scale in x, y, z.

Parameter Descriptions

matrix4x4

Address of matrix to set.

xScale

Amount to scale in x.

yScale

Amount to scale in y.

zScale

Amount to scale in z.

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_SetTranslate (
    TQ3Matrix4x4 *matrix4x4,
    float xTrans,
    float yTrans,
    float zTrans
);

Discussion

Set a 4x4 matrix to translate in x, y, z.

Parameter Descriptions

matrix4x4

Address of matrix to set.

xTrans

Amount to translate in x.

yTrans

Amount to translate in y.

zTrans

Amount to translate in z.

function result

Convenience copy of matrix4x4 parameter.

( TQ3Matrix4x4 * ) Q3Matrix4x4_Transpose (
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Matrix4x4 *result
);

Discussion

Transpose a 4x4 matrix.

Parameter Descriptions

matrix4x4

Address of a matrix to transpose.

result

Address of matrix to set (may be the same as matrix4x4).

function result

Convenience copy of result parameter.

( TQ3Param2D * ) Q3Param2D_AffineComb (
    const TQ3Param2D *params2D,
    const float *weights,
    TQ3Uns32 numPoints,
    TQ3Param2D *result
);

Discussion

Return weighted combination of several 2D parameter points.

Provide an array of points and a parallel array of weights, and this function will compute the weighted combination.

Although the mathematical definition of an affine combination requires that the weights sum to 1, this function does not. It divides by the sum of the weights, so it only requires that the sum is nonzero.

If you have only two points, use Q3Param2D_RRatio instead.

Parameter Descriptions

params2D

Array of 2D parameter points.

weights

Array of weights.

numPoints

How many elements there are in each array.

result

Address of point to set with the weighted combination.

function result

Convenience copy of result parameter.

( float ) Q3Param2D_Distance (
    const TQ3Param2D *p1,
    const TQ3Param2D *p2
);

Discussion

Return Euclidean distance between two UV parameter points.

Available in inline form as Q3FastParam2D_Distance.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Distance between the given points.

( float ) Q3Param2D_DistanceSquared (
    const TQ3Param2D *p1,
    const TQ3Param2D *p2
);

Discussion

Return the squared Euclidean distance between two UV parameter points.

Available in inline form as Q3FastParam2D_DistanceSquared.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Square of the distance between the given points.

( TQ3Param2D * ) Q3Param2D_RRatio (
    const TQ3Param2D *p1,
    const TQ3Param2D *p2,
    float r1,
    float r2,
    TQ3Param2D *result
);

Discussion

Return the point at ratio r2/(r1+r2) along the line segment is parameter (UV) space from p1 to p2.

Put another way, this function gives you the weighted average of points p1 and p2, with the weights given by r1 and r2. (Note that r1+r2 must be nonzero.)

Available in inline form as Q3FastParam2D_RRatio.

Parameter Descriptions

p1

Address of one end of a line segment.

p2

Address of the other end of a line segment.

r1

Weight given to point p1.

r2

Weight given to point p2.

result

Address of point to set (may be the same as p1 and/or p2).

function result

Convenience copy of result parameter.

( TQ3Param2D * ) Q3Param2D_Set (
    TQ3Param2D *param2D,
    float u,
    float v
);

Discussion

Set a 2D parameterization value (i.e., a UV coordinate).

Available in inline form as Q3FastParam2D_Set.

Parameter Descriptions

param2D

Address of param2D to set (may be NULL).

u

U coordinate to set into param2D.

v

V coordinate to set into param2D.

function result

Convenience copy of param2D parameter.

( TQ3Vector2D * ) Q3Param2D_Subtract (
    const TQ3Param2D *p1,
    const TQ3Param2D *p2,
    TQ3Vector2D *result
);

Discussion

Subtract 2D parametric point p2 from p1.

Available in inline form as Q3FastParam2D_Subtract.

Parameter Descriptions

p1

Address of a point.

p2

Address of point to subtract.

result

Address of a vector to set with (p1-p2).

function result

Convenience copy of result parameter.

( TQ3Param2D * ) Q3Param2D_Transform (
    const TQ3Param2D *param2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Param2D *result
);

Discussion

Transform a 2D parametric point by a 3x3 matrix.

Parameter Descriptions

point2D

Address of a point to transform.

matrix3x3

Address of a 3x3 transformation matrix.

result

Address of point to set (may be the same as point2D).

function result

Convenience copy of result parameter.

( TQ3Param2D * ) Q3Param2D_Vector2D_Add (
    const TQ3Param2D *param2D,
    const TQ3Vector2D *vector2D,
    TQ3Param2D *result
);

Discussion

Add a 2D vector to a parametric (UV) point.

Available in inline form as Q3FastParam2D_Vector2D_Add.

Parameter Descriptions

param2D

Address of a 2D parametric point.

vector2D

Address of a vector to add.

result

Address of point to set (may be the same as param2D).

function result

Convenience copy of result parameter.

( TQ3Param2D * ) Q3Param2D_Vector2D_Subtract (
    const TQ3Param2D *param2D,
    const TQ3Vector2D *vector2D,
    TQ3Param2D *result
);

Discussion

Subtract a 2D vector from a parametric (UV) point.

Available in inline form as Q3FastParam2D_Vector2D_Subtract.

Parameter Descriptions

param2D

Address of a 2D parametric point.

vector2D

Address of a vector to subtract.

result

Address of point to set (may be the same as param2D).

function result

Convenience copy of result parameter.

( TQ3Point2D * ) Q3Point2D_AffineComb (
    const TQ3Point2D *points2D,
    const float *weights,
    TQ3Uns32 numPoints,
    TQ3Point2D *result
);

Discussion

Return weighted combination of several 2D points.

Provide an array of points and a parallel array of weights, and this function will compute the weighted combination.

Although the mathematical definition of an affine combination requires that the weights sum to 1, this function does not. It divides by the sum of the weights, so it only requires that the sum is nonzero.

If you have only two points, use Q3Point2D_RRatio instead.

Parameter Descriptions

points2D

Array of 2D points.

weights

Array of weights.

numPoints

How many elements there are in each array.

result

Address of point to set with the weighted combination.

function result

Convenience copy of result parameter.

( float ) Q3Point2D_CrossProductTri (
    const TQ3Point2D *p1,
    const TQ3Point2D *p2,
    const TQ3Point2D *p3
);

Discussion

Return the length of the cross product of a triangle specified by three 2D points, that is, of the vectors p2-p1 and p3-p2.

Available in inline form as Q3FastPoint2D_CrossProductTri.

Parameter Descriptions

p1

Address of one point in the triangle.

p2

Address of a second point in the triangle.

p3

Address of a third point in the triangle.

function result

Length of (p2-p1) x (p3-p2).

( float ) Q3Point2D_Distance (
    const TQ3Point2D *p1,
    const TQ3Point2D *p2
);

Discussion

Return Euclidean distance between two 2D points.

Available in inline form as Q3FastPoint2D_Distance.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Distance between the given points.

( float ) Q3Point2D_DistanceSquared (
    const TQ3Point2D *p1,
    const TQ3Point2D *p2
);

Discussion

Return the squared Euclidean distance between two 2D points.

Available in inline form as Q3FastPoint2D_DistanceSquared.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Square of the distance between the given points.

( TQ3Point2D * ) Q3Point2D_RRatio (
    const TQ3Point2D *p1,
    const TQ3Point2D *p2,
    float r1,
    float r2,
    TQ3Point2D *result
);

Discussion

Return the point at ratio r2/(r1+r2) along the line segment from p1 to p2.

Put another way, this function gives you the weighted average of points p1 and p2, with the weights given by r1 and r2. (Note that r1+r2 must be nonzero.)

NOTE: The QD3D docs claim that the ratio used is r1/(r1+r2), but it was found by direct experimentation that the QD3D library (1.6) in fact uses r2/(r1+r2) instead. This is as it should be, if r1 is the weight of p1, and r2 is the weight of p2.

As usual, we do as QD3D does, not as the docs say.

Available in inline form as Q3FastPoint2D_RRatio.

Parameter Descriptions

p1

Address of one end of a line segment.

p2

Address of the other end of a line segment.

r1

Weight given to point p1.

r2

Weight given to point p2.

result

Address of point to set (may be the same as p1 and/or p2).

function result

Convenience copy of result parameter.

( TQ3Point2D * ) Q3Point2D_Set (
    TQ3Point2D *point2D,
    float x,
    float y
);

Discussion

Set a 2D point.

Available in inline form as Q3FastPoint2D_Set.

Parameter Descriptions

point2D

Address of point to set (may be NULL).

x

X coordinate to set into vector2D.

y

Y coordinate to set into vector2D.

function result

Convenience copy of point2D parameter.

( TQ3Vector2D * ) Q3Point2D_Subtract (
    const TQ3Point2D *p1,
    const TQ3Point2D *p2,
    TQ3Vector2D *result
);

Discussion

Subtract the 2D point p2 from p1.

Available in inline form as Q3FastPoint2D_Subtract.

Parameter Descriptions

p1

Address of a point.

p2

Address of point to subtract.

result

Address of a vector to set with (p1-p2).

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Point2D_To2DTransformArray (
    const TQ3Point2D *inPoints2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Point2D *outPoints2D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 2D points by a 3x3 matrix.

When you have many points to transform, this is a more efficient alternative to calling Q3Point2D_Transform repeatedly.

Parameter Descriptions

inPoints2D

Array of 2D points to transform.

matrix3x3

Transformation matrix.

outPoints2D

Array of points to receive output (may be the same as inPoints2D).

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Point2D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3Point2D).

function result

kQ3Success or some error code.

( TQ3RationalPoint3D * ) Q3Point2D_To3D (
    const TQ3Point2D *point2D,
    TQ3RationalPoint3D *result
);

Discussion

Convert 2D point to rational 3D, setting w to 1.

The Apple version incorrectly declares the type of 'result' to be TQ3Point3D rather than TQ3RationalPoint3D. At a binary level there is no difference, but at the source code level the Apple version forces the use of the incorrect type or type casting.

Available in inline form as Q3FastPoint2D_To3D.

Parameter Descriptions

point2D

Address of 2D point to convert.

result

Address of 3D rational point to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Point2D_To3DTransformArray (
    const TQ3Point2D *inPoints2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3RationalPoint3D *outRationalPoints3D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 2D points by a 3x3 matrix into 3D rational points.

When you have many vectors to transform, this is a more efficient alternative to calling Q3Point2D_To3D and Q3RationalPoint3D_Transform repeatedly.

Parameter Descriptions

inPoints2D

Array of 2D points to transform.

matrix3x3

Transformation matrix.

outRationalPoints3D

Array of points to receive output.

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Point2D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3RationalPoint3D).

function result

kQ3Success or some error code.

( TQ3PolarPoint * ) Q3Point2D_ToPolar (
    const TQ3Point2D *point2D,
    TQ3PolarPoint *result
);

Discussion

Convert 2D cartesian point to polar coordinates.

The angle (theta) here is measured counter-clockwise from the +x axis.

Parameter Descriptions

point2D

Address of 2D point to convert.

result

Address of polar point to set.

function result

Convenience copy of result parameter.

( TQ3Point2D * ) Q3Point2D_Transform (
    const TQ3Point2D *point2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Point2D *result
);

Discussion

Transform a 2D point by a 3x3 matrix.

Parameter Descriptions

point2D

Address of a point to transform.

matrix3x3

Address of a 3x3 transformation matrix.

result

Address of point to set (may be the same as point2D).

function result

Convenience copy of result parameter.

( TQ3Point2D * ) Q3Point2D_Vector2D_Add (
    const TQ3Point2D *point2D,
    const TQ3Vector2D *vector2D,
    TQ3Point2D *result
);

Discussion

Add a 2D vector to a point.

Available in inline form as Q3FastPoint2D_Vector2D_Add.

Parameter Descriptions

point2D

Address of a point.

vector2D

Address of a vector to add.

result

Address of point to set (may be the same as point2D).

function result

Convenience copy of result parameter.

( TQ3Point2D * ) Q3Point2D_Vector2D_Subtract (
    const TQ3Point2D *point2D,
    const TQ3Vector2D *vector2D,
    TQ3Point2D *result
);

Discussion

Subtract a 2D vector from a point.

Available in inline form as Q3FastPoint2D_Vector2D_Subtract.

Parameter Descriptions

point2D

Address of a point.

vector2D

Address of a vector to subtract.

result

Address of point to set (may be the same as point2D).

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_AffineComb (
    const TQ3Point3D *points3D,
    const float *weights,
    TQ3Uns32 numPoints,
    TQ3Point3D *result
);

Discussion

Return weighted combination of several 3D points.

Provide an array of points and a parallel array of weights, and this function will compute the weighted combination.

Although the mathematical definition of an affine combination requires that the weights sum to 1, this function does not. It divides by the sum of the weights, so it only requires that the sum is nonzero.

If you have only two points, use Q3Point3D_RRatio instead.

Parameter Descriptions

points3D

Array of 3D points.

weights

Array of weights.

numPoints

How many elements there are in each array.

result

Address of point to set with the weighted combination.

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Point3D_CrossProductTri (
    const TQ3Point3D *p1,
    const TQ3Point3D *p2,
    const TQ3Point3D *p3,
    TQ3Vector3D *result
);

Discussion

Return the cross product of triangle triangle defined by three 3D points, that is, of the vectors p2-p1 and p3-p2.

Available in inline form as Q3FastPoint3D_CrossProductTri.

Parameter Descriptions

p1

Address of one point in the triangle.

p2

Address of a second point in the triangle.

p3

Address of a third point in the triangle.

result

Address of vector to set with cross product (p2-p1) x (p3-p2).

function result

Convenience copy of result parameter.

( float ) Q3Point3D_Distance (
    const TQ3Point3D *p1,
    const TQ3Point3D *p2
);

Discussion

Return Euclidean distance between two 3D points.

Available in inline form as Q3FastPoint3D_Distance.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Distance between the given points.

( float ) Q3Point3D_DistanceSquared (
    const TQ3Point3D *p1,
    const TQ3Point3D *p2
);

Discussion

Return the squared Euclidean distance between two 3D points.

Available in inline form as Q3FastPoint3D_DistanceSquared.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Square of the distance between the given points.

( TQ3Point3D * ) Q3Point3D_RRatio (
    const TQ3Point3D *p1,
    const TQ3Point3D *p2,
    float r1,
    float r2,
    TQ3Point3D *result
);

Discussion

Return the point at ratio r2/(r1+r2) along the line segment from p1 to p2.

Put another way, this function gives you the weighted average of points p1 and p2, with the weights given by r1 and r2. (Note that r1+r2 must be nonzero.)

NOTE: The QD3D docs claim that the ratio used is r1/(r1+r2), but it was found by direct experimentation that the QD3D library (1.6) in fact uses r2/(r1+r2) instead. This is as it should be, if r1 is the weight of p1, and r2 is the weight of p2.

As usual, we do as QD3D does, not as the docs say.

Available in inline form as Q3FastPoint3D_RRatio.

Parameter Descriptions

p1

Address of one end of a line segment.

p2

Address of the other end of a line segment.

r1

Weight given to point p1.

r2

Weight given to point p2.

result

Address of point to set (may be the same as p1 and/or p2).

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_Set (
    TQ3Point3D *point3D,
    float x,
    float y,
    float z
);

Discussion

Set a 3D point.

Available in inline form as Q3FastPoint3D_Set.

Parameter Descriptions

point3D

Address of point to set (may be NULL).

x

X coordinate to set into point3D.

y

Y coordinate to set into point3D.

z

Z coordinate to set into point3D.

function result

Convenience copy of point3D parameter.

( TQ3Vector3D * ) Q3Point3D_Subtract (
    const TQ3Point3D *p1,
    const TQ3Point3D *p2,
    TQ3Vector3D *result
);

Discussion

Subtract 3D point p2 from p1.

Available in inline form as Q3FastPoint3D_Subtract.

Parameter Descriptions

p1

Address of a point.

p2

Address of a point to subtract.

result

Address of point to set (may be the same as p1 and/or p2).

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Point3D_To3DTransformArray (
    const TQ3Point3D *inPoints3D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Point3D *outPoints3D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 3D points by a 4x4 matrix.

When you have many points to transform, this is a more efficient alternative to calling Q3Point3D_Transform repeatedly.

Parameter Descriptions

inPoints3D

Array of 3D points to transform.

matrix4x4

Transformation matrix.

outPoints3D

Array of points to receive output (may be the same as inPoints3D).

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Point3D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3Point3D).

function result

kQ3Success or some error code.

( TQ3RationalPoint4D * ) Q3Point3D_To4D (
    const TQ3Point3D *point3D,
    TQ3RationalPoint4D *result
);

Discussion

Convert 3D point to rational 4D, setting w to 1.

Available in inline form as Q3FastPoint3D_To4D.

Parameter Descriptions

point3D

Address of 3D point to convert.

result

Address of rational 4D point to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Point3D_To4DTransformArray (
    const TQ3Point3D *inPoints3D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3RationalPoint4D *outRationalPoints4D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 3D points by a 4x4 matrix into 4D rational points.

When you have many vectors to transform, this is a more efficient alternative to calling Q3Point3D_To4D and Q3RationalPoint4D_Transform repeatedly.

Parameter Descriptions

inPoints3D

Array of 3D points to transform.

matrix4x4

Transformation matrix.

outRationalPoints4D

Array of points to receive output.

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Point3D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3RationalPoint4D).

function result

kQ3Success or some error code.

( TQ3SphericalPoint * ) Q3Point3D_ToSpherical (
    const TQ3Point3D *point3D,
    TQ3SphericalPoint *result
);

Discussion

Convert 3D cartesian point to spherical coordinates.

Parameter Descriptions

point3D

Address of 3D cartesian point to convert.

result

Address of spherical-coordinates point to set.

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_Transform (
    const TQ3Point3D *point3D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Point3D *result
);

Discussion

Transform a 3D point by a 4x4 matrix.

Parameter Descriptions

point3D

Address of a point to transform.

matrix4x4

Address of a 4x4 transformation matrix.

result

Address of point to set (may be the same as point3D).

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_TransformQuaternion (
    const TQ3Point3D *point3D,
    const TQ3Quaternion *quaternion,
    TQ3Point3D *result
);

Discussion

Transform a 3D point by a quaternion.

Note that for correct results, the quaternion should be normalized.

Parameter Descriptions

point3D

Address of a point to transform.

quaternion

Address of a quaternion to transform by.

result

Address of a point to set (may be the same as point3D).

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_Vector3D_Add (
    const TQ3Point3D *point3D,
    const TQ3Vector3D *vector3D,
    TQ3Point3D *result
);

Discussion

Add a 3D vector to a point.

Available in inline form as Q3FastPoint3D_Vector3D_Add.

Parameter Descriptions

point3D

Address of a point.

vector3D

Address of a vector to add.

result

Address of point to set (may be the same as point3D).

function result

Convenience copy of result parameter.

( TQ3Point3D * ) Q3Point3D_Vector3D_Subtract (
    const TQ3Point3D *point3D,
    const TQ3Vector3D *vector3D,
    TQ3Point3D *result
);

Discussion

Subtract 3D vector from point.

Available in inline form as Q3FastPoint3D_Vector3D_Subtract.

Parameter Descriptions

point3D

Address of a point.

vector3D

Address of a vector to subtract.

result

Address of point to set (may be the same as point3D).

function result

Convenience copy of result parameter.

( TQ3PolarPoint * ) Q3PolarPoint_Set (
    TQ3PolarPoint *polarPoint,
    float r,
    float theta
);

Discussion

Set a 2D polar-coordinates point.

Available in inline form as Q3FastPolarPoint_Set.

Parameter Descriptions

polarPoint

Address of point to set (may be NULL).

r

Radius coordinate to set into polarPoint.

theta

Angle coordinate (in radians) to set into polarPoint.

function result

Convenience copy of polarPoint parameter.

( TQ3Point2D * ) Q3PolarPoint_ToPoint2D (
    const TQ3PolarPoint *polarPoint,
    TQ3Point2D *result
);

Discussion

Convert 2D polar point to cartesian coordinates.

The angle (theta) here is measured counter-clockwise from the +x axis.

Available in inline form as Q3FastPolarPoint_ToPoint2D.

Parameter Descriptions

polarPoint

Address of polar point to convert.

result

Address of 2D cartesian point to set.

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_Copy (
    const TQ3Quaternion *quaternion,
    TQ3Quaternion *result
);

Discussion

Copy a quaternion.

Available in inline form as Q3FastQuaternion_Copy.

Parameter Descriptions

quaternion

Address of source quaternion.

result

Address of destination quaternion (may be the same as the first parameter).

function result

Convenience copy of result parameter.

( float ) Q3Quaternion_Dot (
    const TQ3Quaternion *q1,
    const TQ3Quaternion *q2
);

Discussion

Return the dot product of q1 and q2.

Available in inline form as Q3FastQuaternion_Dot.

Parameter Descriptions

q1

Address of one quaternion.

q2

Address of another quaternion (may be the same as q1).

function result

Dot product of q1 and q2.

( TQ3Vector3D * ) Q3Quaternion_GetAxisAndAngle (
    const TQ3Quaternion *quaternion,
    TQ3Vector3D *outAxis,
    float *outAngle
);

Discussion

Get the rotation axis and/or angle represented by a quaternion.

Note that for correct results, the quaternion should be normalized.

If the quaternion represents a null rotation, then outAngle will be set to 0.0 and outAxis will be set to <0, 1, 0> (since in this case the rotation axis is undefined, but we want to always give you a valid axis).

The returned angle in radians will be in the range [0, 2*pi].

Either outAxis or outAngle may be null if you are not interested in that result. (You could even pass null for both, but that would be rather pointless.)

Parameter Descriptions

quaternion

Address of a quaternion to inspect.

outAxis

Address of a vector to set to the rotation axis (may be null).

outAngle

Address of a float to set to the rotation angle (may be null).

function result

Convenience copy of outAxis parameter.

( TQ3Quaternion * ) Q3Quaternion_InterpolateFast (
    const TQ3Quaternion *q1,
    const TQ3Quaternion *q2,
    float t,
    TQ3Quaternion *result
);

Discussion

Compute a straight linear interpolation between two quaternions.

This does a true linear, not spherical, interpolation between q1 and q2. It's fast, but not very proper for most uses.

The result is automatically normalized, so there is no need to do so yourself.

Parameter Descriptions

q1

Address of first quaternion.

q2

Address of second quaternion.

t

Fraction (0-1) of the way from q1 to q2.

result

Address of quaternion to set (may be the same as q1 and/or q2).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_InterpolateLinear (
    const TQ3Quaternion *q1,
    const TQ3Quaternion *q2,
    float t,
    TQ3Quaternion *result
);

Discussion

Compute a spherical linear interpolation between two quaternions.

Despite the name, this function does a SLERP (spherical linear interpolation) from q1 to q2. It falls back on a straight linear interpolation only when the cosine of the angle between them is less than 0.01.

The cut-off point was chosen arbitrarily, and may not match that of QD3D.

Parameter Descriptions

q1

Address of first quaternion.

q2

Address of second quaternion.

t

Fraction (0-1) of the way from q1 to q2.

result

Address of quaternion to set (may be the same as q1 and/or q2).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_Invert (
    const TQ3Quaternion *quaternion,
    TQ3Quaternion *result
);

Discussion

Invert a quaternion.

For correct results, the quaternion should be normalized before inverting.

Available in inline form as Q3FastQuaternion_Invert.

Parameter Descriptions

quaternion

Address of a quaternion to invert.

result

Address of quaternion to set (may be the same as the first parameter).

function result

Convenience copy of result parameter.

( TQ3Boolean ) Q3Quaternion_IsIdentity (
    const TQ3Quaternion *quaternion
);

Discussion

Return whether a quaternion is (roughly) the identity, i.e., (1,0,0,0).

Values for x, y, and z are considered close enough to 0 if they are within FLT_EPSILON (a small number).

For correct results, the quaternion should first be normalized.

Parameter Descriptions

quaternion

Address of quaternion to test.

function result

True if quaternion is the identity.

( TQ3Quaternion * ) Q3Quaternion_MatchReflection (
    const TQ3Quaternion *q1,
    const TQ3Quaternion *q2,
    TQ3Quaternion *result
);

Discussion

Set result to either q1 or -q1, whichever produces a positive dot product with q2 (i.e., whichever is "closer" to q2 in orientation).

Parameter Descriptions

q1

Address of source quaternion.

q2

Address of quaternion to match.

result

Address of quaternion to set (may be the same as q1 and/or q2).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_Multiply (
    const TQ3Quaternion *q1,
    const TQ3Quaternion *q2,
    TQ3Quaternion *result
);

Discussion

Compute the product of two quaternions.

This is a very useful operation, since the rotation represented by q1*q2 is exactly the same as rotating by q1 and then by q2.

Parameter Descriptions

q1

Address of first quaternion.

q2

Address of second quaternion.

result

Address of quaternion to set (may be the same as q1 and/or q2).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_Normalize (
    const TQ3Quaternion *quaternion,
    TQ3Quaternion *result
);

Discussion

Scale a quaternion to length 1.

This is often needed when combining or interpolating between quaternions, to keep accumulated error from causing your quaternion values to "blow up".

Available in inline form as Q3FastQuaternion_Normalize.

Parameter Descriptions

quaternion

Address of a quaternion to normalize.

result

Address of quaternion to set (may be the same as the first parameter).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_Set (
    TQ3Quaternion *quaternion,
    float w,
    float x,
    float y,
    float z
);

Discussion

Set a quaternion with its individual w, x, y, and z components.

Available in inline form as Q3FastQuaternion_Set.

Parameter Descriptions

quaternion

Address of a quaternion to set.

w

Value for w component.

x

Value for x component.

y

Value for y component.

z

Value for z component.

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetIdentity (
    TQ3Quaternion *quaternion
);

Discussion

Set a quaternion to the identity value (1,0,0,0).

Available in inline form as Q3FastQuaternion_SetIdentity.

Parameter Descriptions

quaternion

Address of a quaternion to set.

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_SetMatrix (
    TQ3Quaternion *quaternion,
    const TQ3Matrix4x4 *matrix4x4
);

Discussion

Set a quaternion from a 4x4 rotation matrix.

Note: The QD3D implementation of this function appears to be buggy. This can be demonstrated by starting with an arbitrary quaternion, converting to a matrix, then converting back (with this function).

QD3D's result is something ridiculous; in Quesa, this function returns the original quaternion (or something equivalent).

Parameter Descriptions

quaternion

Address of a quaternion to set.

matrix4x4

Address of a rotation matrix to imitate.

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotateAboutAxis (
    TQ3Quaternion *quaternion,
    const TQ3Vector3D *axis,
    float angle
);

Discussion

Set quaternion to rotate about arbitrary axis.

Note that for correct results, the axis should be normalized (i.e. have length = 1).

Parameter Descriptions

quaternion

Address of a quaternion to set.

axis

Address of a 3D vector to use as the rotation axis.

angle

Angle to rotate (in radians).

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotateVectorToVector (
    TQ3Quaternion *quaternion,
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2
);

Discussion

Set a quaternion to rotate vector 'v1' to 'v2'.

Note that for correct results, both vectors should be normalized (i.e. have length = 1).

Parameter Descriptions

quaternion

Address of a quaternion to set.

v1

Address of "starting" vector.

v2

Address of "ending" vector.

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotate_X (
    TQ3Quaternion *quaternion,
    float angle
);

Discussion

Set a quaternion to rotate about the X axis.

Parameter Descriptions

quaternion

Address of a quaternion to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of result parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotate_XYZ (
    TQ3Quaternion *quaternion,
    float xAngle,
    float yAngle,
    float zAngle
);

Discussion

Set a quaternion to rotate about the X, Y, and Z axes (in that order).

This order of rotations is rarely useful, but it's kept for backwards compatibility with QD3D.

Parameter Descriptions

quaternion

Address of a quaternion to set.

xAngle

Angle to rotate about the X axis (in radians).

yAngle

Angle to rotate about the Y axis (in radians).

zAngle

Angle to rotate about the Z axis (in radians).

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotate_Y (
    TQ3Quaternion *quaternion,
    float angle
);

Discussion

Set a quaternion to rotate about the Y axis.

Parameter Descriptions

quaternion

Address of a quaternion to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of quaternion parameter.

( TQ3Quaternion * ) Q3Quaternion_SetRotate_Z (
    TQ3Quaternion *quaternion,
    float angle
);

Discussion

Set a quaternion to rotate about the Z axis.

Parameter Descriptions

quaternion

Address of a quaternion to set.

angle

Angle to rotate (in radians).

function result

Convenience copy of quaternion parameter.

( TQ3RationalPoint3D * ) Q3RationalPoint3D_AffineComb (
    const TQ3RationalPoint3D *rationalPoints3D,
    const float *weights,
    TQ3Uns32 numPoints,
    TQ3RationalPoint3D *result
);

Discussion

Compute the weighted combination of several 3D rational points.

Although the mathematical definition of an affine combination requires that the weights sum to 1, this function does not. It divides by the sum of the weights, so it only requires that the sum is nonzero.

Parameter Descriptions

rationalPoints3D

Array of 3D rational points.

weights

Array of weights.

numPoints

How many elements there are in each array.

result

Address of point to set with the weighted combination.

function result

Convenience copy of result parameter.

( float ) Q3RationalPoint3D_Distance (
    const TQ3RationalPoint3D *p1,
    const TQ3RationalPoint3D *p2
);

Discussion

Returns the Euclidian distance between two rational 3D points.

This operation makes no sense mathematically, but is included for backwards compatibility with QD3D.

Available in inline form as Q3FastRationalPoint3D_Distance.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Distance between the given points, treating w as a spatial coordinate.

( float ) Q3RationalPoint3D_DistanceSquared (
    const TQ3RationalPoint3D *p1,
    const TQ3RationalPoint3D *p2
);

Discussion

Returns the squared Euclidian distance between two rational 3D points.

This operation makes no sense mathematically, but is included for backwards compatibility with QD3D.

Available in inline form as Q3FastRationalPoint3D_DistanceSquared.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Square of the distance between the given points, treating w as a spatial coordinate.

( TQ3RationalPoint3D * ) Q3RationalPoint3D_Set (
    TQ3RationalPoint3D *rationalPoint3D,
    float x,
    float y,
    float w
);

Discussion

Set a 3D rational point (x,y,w).

Available in inline form as Q3FastRationalPoint3D_Set.

Parameter Descriptions

rationalPoint3D

Address of rational point to set (may be NULL).

x

X coordinate to set into rationalPoint3D.

y

Y coordinate to set into rationalPoint3D.

w

W coordinate to set into rationalPoint3D.

function result

Convenience copy of rationalPoint3D parameter.

( TQ3Point2D * ) Q3RationalPoint3D_To2D (
    const TQ3RationalPoint3D *rationalPoint3D,
    TQ3Point2D *result
);

Discussion

Convert rational 3D point to 2D, dividing by w.

Available in inline form as Q3FastRationalPoint3D_To2D.

Parameter Descriptions

rationalPoint3D

Address of rational 3D point to convert.

result

Address of 2D point to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3RationalPoint3D_To3DTransformArray (
    const TQ3RationalPoint3D *inRationalPoints3D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3RationalPoint3D *outRationalPoints3D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 3D rational points by a 3x3 matrix.

When you have many points to transform, this is a more efficient alternative to calling Q3RationalPoint3D_Transform repeatedly.

Parameter Descriptions

inRationalPoints3D

Array of 3D rational points to transform.

matrix3x3

Transformation matrix.

outRationalPoints3D

Array of points to receive output (may be the same as inRationalPoints3D).

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3RationalPoint3D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3RationalPoint3D).

function result

kQ3Success or some error code.

( TQ3Vector2D * ) Q3RationalPoint3D_ToVector2D (
    const TQ3RationalPoint3D *rationalPoint3D,
    TQ3Vector2D *result
);

Discussion

Convert 3D rational point to 2D vector, discarding w.

Available in inline form as Q3FastRationalPoint3D_ToVector2D.

Parameter Descriptions

rationalPoint3D

Address of 3D rational point to convert.

result

Address of 2D vector to set.

function result

Convenience copy of result parameter.

( TQ3RationalPoint3D * ) Q3RationalPoint3D_Transform (
    const TQ3RationalPoint3D *rationalPoint3D,
    const TQ3Matrix3x3 *matri3x3,
    TQ3RationalPoint3D *result
);

Discussion

Transform a 3D rational point by 3x3 matrix.

Parameter Descriptions

rationalPoint3D

Address of a point to transform.

matrix3x3

Address of a 3x3 transformation matrix.

result

Address of point to set (may be the same as rationalPoint3D).

function result

Convenience copy of result parameter.

( TQ3RationalPoint4D * ) Q3RationalPoint4D_AffineComb (
    const TQ3RationalPoint4D *rationalPoints4D,
    const float *weights,
    TQ3Uns32 numPoints,
    TQ3RationalPoint4D *result
);

Discussion

Compute the weighted combination of several 4D rational points.

Although the mathematical definition of an affine combination requires that the weights sum to 1, this function does not. It divides by the sum of the weights, so it only requires that the sum is nonzero.

Parameter Descriptions

rationalPoints4D

Array of 4D rational points.

weights

Array of weights.

numPoints

How many elements there are in each array.

result

Address of point to set with the weighted combination.

function result

Convenience copy of result parameter.

( float ) Q3RationalPoint4D_Distance (
    const TQ3RationalPoint4D *p1,
    const TQ3RationalPoint4D *p2
);

Discussion

Returns the Euclidian distance between two rational 4D points.

This operation makes no sense mathematically, but is included for backwards compatibility with QD3D.

Available in inline form as Q3FastRationalPoint4D_Distance.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Distance between the given points, treating w as a spatial coordinate.

( float ) Q3RationalPoint4D_DistanceSquared (
    const TQ3RationalPoint4D *p1,
    const TQ3RationalPoint4D *p2
);

Discussion

Returns the squared Euclidian distance between two rational 4D points.

This operation makes no sense mathematically, but is included for backwards compatibility with QD3D.

Available in inline form as Q3FastRationalPoint4D_DistanceSquared.

Parameter Descriptions

p1

Address of first point of interest.

p2

Address of second point of interest.

function result

Square of the distance between the given points, treating w as a spatial coordinate.

( TQ3RationalPoint4D * ) Q3RationalPoint4D_RRatio (
    const TQ3RationalPoint4D *p1,
    const TQ3RationalPoint4D *p2,
    float r1,
    float r2,
    TQ3RationalPoint4D *result
);

Discussion

Return the point at ratio r2/(r1+r2) along the line segment from p1 to p2.

Put another way, this function gives you the weighted average of points p1 and p2, with the weights given by r1 and r2. (Note that r1+r2 must be nonzero.)

NOTE: The QD3D docs claim that the ratio used is r1/(r1+r2), but it was found by direct experimentation that the QD3D library (1.6) in fact uses r2/(r1+r2) instead. This is as it should be, if r1 is the weight of p1, and r2 is the weight of p2.

As usual, we do as QD3D does, not as the docs say.

Available in inline form as Q3FastRationalPoint4D_RRatio.

Parameter Descriptions

p1

Address of one end of a line segment.

p2

Address of the other end of a line segment.

r1

Weight given to point p1.

r2

Weight given to point p2.

result

Address of point to set (may be the same as p1 and/or p2).

function result

Convenience copy of result parameter.

( TQ3RationalPoint4D * ) Q3RationalPoint4D_Set (
    TQ3RationalPoint4D *rationalPoint4D,
    float x,
    float y,
    float z,
    float w
);

Discussion

Set a 4D rational point (x,y,z,w).

Available in inline form as Q3FastRationalPoint4D_Set.

Parameter Descriptions

rationalPoint4D

Address of rational point to set.

x

X coordinate to set into rationalPoint4D.

y

Y coordinate to set into rationalPoint4D.

z

Z coordinate to set into rationalPoint4D.

function result

Convenience copy of rationalPoint4D parameter.

( TQ3Point3D * ) Q3RationalPoint4D_To3D (
    const TQ3RationalPoint4D *rationalPoint4D,
    TQ3Point3D *result
);

Discussion

Convert rational 4D point to 3D, dividing by w.

Available in inline form as Q3FastRationalPoint4D_To3D.

Parameter Descriptions

rationalPoint4D

Address of rational 4D point to convert.

result

Address of 3D point to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3RationalPoint4D_To4DTransformArray (
    const TQ3RationalPoint4D *inRationalPoints4D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3RationalPoint4D *outRationalPoints4D,
    TQ3Uns32 numPoints,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 4D points by a 4x4 matrix.

When you have many points to transform, this is a more efficient alternative to calling Q3RationalPoint4D_Transform repeatedly.

Parameter Descriptions

inRationalPoints4D

Array of 4D points to transform.

matrix4x4

Transformation matrix.

outRationalPoints4D

Array of points to receive output (may be the same as inRationalPoints4D).

numPoints

How many points are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3RationalPoint4D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3RationalPoint4D).

function result

kQ3Success or some error code.

( TQ3Vector3D * ) Q3RationalPoint4D_ToVector3D (
    const TQ3RationalPoint4D *rationalPoint4D,
    TQ3Vector3D *result
);

Discussion

Convert 4D rational point to 3D vector, discarding w.

Available in inline form as Q3FastRationalPoint4D_ToVector3D.

Parameter Descriptions

rationalPoint4D

Address of 4D rational point to convert.

result

Address of 3D vector to set.

function result

Convenience copy of result parameter.

( TQ3RationalPoint4D * ) Q3RationalPoint4D_Transform (
    const TQ3RationalPoint4D *rationalPoint4D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3RationalPoint4D *result
);

Discussion

Transform a 4D rational point by a 4x4 matrix.

Parameter Descriptions

rationalPoint4D

Address of a point to transform.

matrix4x4

Address of a 4x4 transformation matrix.

result

Address of point to set (may be the same as rationalPoint4D).

function result

Convenience copy of result parameter.

( TQ3Boolean ) Q3Ray3D_IntersectBoundingBox (
    const TQ3Ray3D *theRay,
    const TQ3BoundingBox *theBounds,
    TQ3Point3D *hitPoint
);

Discussion

Test a ray for intersection against a bounding box. If an intersection occurs, the point of intersection is returned.

The direction vector of the ray must be normalised.

Parameter Descriptions

theRay

The ray to test.

theBounds

The bounding box to test against.

hitPoint

Receives the intersection point, if found.

function result

Indicates if the ray intersects the bounding box.

( TQ3Boolean ) Q3Ray3D_IntersectSphere (
    const TQ3Ray3D *theRay,
    const TQ3Sphere *theSphere,
    TQ3Point3D *hitPoint
);

Discussion

Test a ray for intersection against a sphere, and return the point of intersection if found.

The direction vector of the ray must be normalised.

Parameter Descriptions

theRay

The ray to test.

theSphere

The sphere to test against.

hitPoint

Receives the intersection point, if found.

function result

Indicates if the ray intersects the sphere.

( TQ3Boolean ) Q3Ray3D_IntersectTriangle (
    const TQ3Ray3D *theRay,
    const TQ3Point3D *point1,
    const TQ3Point3D *point2,
    const TQ3Point3D *point3,
    TQ3Boolean cullBackfacing,
    TQ3Param3D *hitPoint
);

Discussion

Test a ray for intersection against a triangle formed by three points. If an intersection occurs, returns the barycentric coordinates of the point of intersection and the parameter along the ray.

Triangles may optionally be subject to backface culling, in which case a hit on the reverse side of the triangle will fail to result in an intersection.

The u and v members of hitPoint can be used to express the point of intersection in terms of the vertices of the triangles, using barycentric coordinates, as follows:

t = (1.0f - hitPoint.u - hitPoint.v);
x = (point1.x * t) + (point2.x * hitPoint.u) + (point3.x * hitPoint.v);
y = (point1.y * t) + (point2.y * hitPoint.u) + (point3.y * hitPoint.v);
z = (point1.z * t) + (point2.z * hitPoint.u) + (point3.z * hitPoint.v);

Parameter Descriptions

theRay

The ray to test.

point1

The first triangle vertex.

point2

The second triangle vertex.

point3

The third triangle vertex.

cullBackfacing

Controls if back-facing triangles should be skipped.

hitPoint

Receives the barycentric coordinates of the intersection, and the multiple of the direction vector that reaches the intersection.

function result

Indicates if the ray intersects the triangle.

( TQ3SphericalPoint * ) Q3SphericalPoint_Set (
    TQ3SphericalPoint *sphericalPoint,
    float rho,
    float theta,
    float phi
);

Discussion

Set a 3D spherical-coordinates point.

Available in inline form as Q3FastSphericalPoint_Set.

Parameter Descriptions

sphericalPoint

Address of point to set (may be NULL).

rho

Rho coordinate to set into sphericalPoint.

theta

Theta coordinate to set into sphericalPoint.

phi

Phi coordinate to set into sphericalPoint.

function result

Convenience copy of polarPoint parameter.

( TQ3Point3D * ) Q3SphericalPoint_ToPoint3D (
    const TQ3SphericalPoint *sphericalPoint,
    TQ3Point3D *result
);

Discussion

Convert 3D spherical point to cartesian coordinates.

Parameter Descriptions

sphericalPoint

Address of spherical-coordinates point to convert.

result

Address of 3D cartesian point to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Triangle_CrossProductArray (
    TQ3Uns32 numTriangles,
    const TQ3Uns8 *usageFlags,
    const TQ3Uns32 *theIndices,
    const TQ3Point3D *thePoints,
    TQ3Vector3D *theNormals
);

Discussion

Calculate an array of triangle normals.

Triangles are specified as a contiguous array of triangle indices, and a contiguous array of points. The result is a contiguous array of triangle normals.

Triangles may be omitted from processing with the usageFlags parameter, which should point to an array of TQ3Uns8 flags. If usageFlags is not NULL, only triangles whose corresponding entry in this array is 0 will be processed.

The returning vectors are normalized.

Parameter Descriptions

numTriangles

The number of triangles to process.

usageFlags

The optional usage flags, indicating the triangles to process.

theIndices

The triangle indices.

thePoints

The triangle points.

theNormals

Receives the triangle normals.

function result

Success or failure of the operation.

( TQ3Vector2D * ) Q3Vector2D_Add (
    const TQ3Vector2D *v1,
    const TQ3Vector2D *v2,
    TQ3Vector2D *result
);

Discussion

Add two 2D vectors.

Available in inline form as Q3FastVector2D_Add.

Parameter Descriptions

v1

Address of first vector to add.

v2

Address of second vector to add.

result

Address of vector to set (may be the same as v1 and/or v2).

function result

Convenience copy of result parameter.

( float ) Q3Vector2D_Cross (
    const TQ3Vector2D *v1,
    const TQ3Vector2D *v2
);

Discussion

Return the length of the cross product of two 2D vectors.

Equivalently, we assume that the 2D vectors are really 3D vectors with z=0, then return the z coordinate of the cross product (0,0,z).

Available in inline form as Q3FastVector2D_Cross.

Parameter Descriptions

v1

Address of first vector.

v2

Address of second vector.

function result

Length of the 2D cross product.

( float ) Q3Vector2D_Dot (
    const TQ3Vector2D *v1,
    const TQ3Vector2D *v2
);

Discussion

Return the dot product of two 2D vectors.

Available in inline form as Q3FastVector2D_Dot.

Parameter Descriptions

v1

Address of first vector.

v2

Address of second vector.

function result

Dot product of the two vectors.

( float ) Q3Vector2D_Length (
    const TQ3Vector2D *vector2D
);

Discussion

Return length of 2D vector.

Available in inline form as Q3FastVector2D_Length.

Parameter Descriptions

vector2D

Address of vector to get length of.

function result

Length of the given vector.

( float ) Q3Vector2D_LengthSquared (
    const TQ3Vector2D *vector2D
);

Discussion

Return squared length of 2D vector.

For many operations, knowing the squared length of a vector is just as good as knowing the actual length (e.g., when sorting a set of vectors by length, or comparing a vector to a cut-off length). But finding the squared length is much faster, since it avoids a costly square root computation.

Available in inline form as Q3FastVector2D_LengthSquared.

Parameter Descriptions

vector2D

Address of vector to get length of.

function result

Squared length of the given vector.

( TQ3Vector2D * ) Q3Vector2D_Negate (
    const TQ3Vector2D *vector2D,
    TQ3Vector2D *result
);

Discussion

Scale a 2D vector by a factor of -1.

Available in inline form as Q3FastVector2D_Negate.

Parameter Descriptions

vector2D

Address of vector to negate.

result

Address of vector to set (may be the same as vector2D).

function result

Convenience copy of result parameter.

( TQ3Vector2D * ) Q3Vector2D_Normalize (
    const TQ3Vector2D *vector2D,
    TQ3Vector2D *result
);

Discussion

Scale a 2D vector to length 1.

To obtain valid results, the length of vector2D must not be 0.

Available in inline form as Q3FastVector2D_Normalize.

Parameter Descriptions

vector2D

Address of vector to normalize.

result

Address of vector to set (may be the same as vector2D).

function result

Convenience copy of result parameter.

( TQ3Vector2D * ) Q3Vector2D_Scale (
    const TQ3Vector2D *vector2D,
    float scalar,
    TQ3Vector2D *result
);

Discussion

Scale a 2D vector by the given factor.

Available in inline form as Q3FastVector2D_Scale.

Parameter Descriptions

vector2D

Address of vector to scale.

scalar

Scaling factor.

result

Address of vector to set (may be the same as vector2D).

function result

Convenience copy of result parameter.

( TQ3Vector2D * ) Q3Vector2D_Set (
    TQ3Vector2D *vector2D,
    float x,
    float y
);

Discussion

Set a 2D vector.

Available in inline form as Q3FastVector2D_Set.

Parameter Descriptions

vector2D

Address of vector to set (may be NULL).

x

X coordinate to set into vector2D.

y

Y coordinate to set into vector2D.

function result

Convenience copy of vector2D parameter.

( TQ3Vector2D * ) Q3Vector2D_Subtract (
    const TQ3Vector2D *v1,
    const TQ3Vector2D *v2,
    TQ3Vector2D *result
);

Discussion

Subtract 2D vector v2 from v1.

Available in inline form as Q3FastVector2D_Subtract.

Parameter Descriptions

v1

Address of first vector.

v2

Address of vector to subtract from v1.

result

Address of vector to set (may be the same as v1 and/or v2).

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Vector2D_To2DTransformArray (
    const TQ3Vector2D *inVectors2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Vector2D *outVectors2D,
    TQ3Uns32 numVectors,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 2D vectors by a 3x3 matrix.

When you have many vectors to transform, this is a more efficient alternative to calling Q3Vector2D_Transform repeatedly.

Parameter Descriptions

inVectors2D

Array of 2D vectors to transform.

matrix3x3

Transformation matrix.

outVectors2D

Array of vectors to receive output (may be the same as inVectors2D).

numVectors

How many vectors are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Vector2D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3Vector2D).

function result

kQ3Success or some error code.

( TQ3Vector3D * ) Q3Vector2D_To3D (
    const TQ3Vector2D *vector2D,
    TQ3Vector3D *result
);

Discussion

Convert 2D vector to 3D, by setting z to 1.

Note: this operation makes no sense mathematically, but is included for backward-compatibility with QD3D. Perhaps the QD3D implementation was really intended to convert a 2D vector into a 3D rational point -- see QDPoint2D_To3D, which does exactly that.

Available in inline form as Q3FastVector2D_To3D.

Parameter Descriptions

vector2D

Address of 2D vector to convert.

result

Address of 3D vector to set.

function result

Convenience copy of result parameter.

( TQ3RationalPoint3D * ) Q3Vector2D_ToRationalPoint3D (
    const TQ3Vector2D *vector2D,
    TQ3RationalPoint3D *result
);

Discussion

Convert 2D vector to 3D rational point, setting w to 0.

Available in inline form as Q3FastVector2D_ToRationalPoint3D.

Parameter Descriptions

vector2D

Address of 2D vector to convert.

result

Address of 3D rational point to set.

function result

Convenience copy of result parameter.

( TQ3Vector2D * ) Q3Vector2D_Transform (
    const TQ3Vector2D *vector2D,
    const TQ3Matrix3x3 *matrix3x3,
    TQ3Vector2D *result
);

Discussion

Transform a 2D vector by a 3x3 matrix.

Note that the translation and perspective components of the matrix is ignored (as if it were really a 2x2 matrix).

Contrast with Q3Point2D_Transform, which does the full 3x3 transformation.

Parameter Descriptions

vector2D

Address of a vector to transform.

matrix3x3

Address of a 3x3 transformation matrix.

result

Address of vector to set (may be the same as vector2D).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Add (
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2,
    TQ3Vector3D *result
);

Discussion

Add two 3D vectors.

Available in inline form as Q3FastVector3D_Add.

Parameter Descriptions

v1

Address of first vector to add.

v2

Address of second vector to add.

result

Address of vector to set (may be the same as v1 and/or v2).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Cross (
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2,
    TQ3Vector3D *result
);

Discussion

Return 3D cross product of two 3D vectors.

Available in inline form as Q3FastVector3D_Cross.

Parameter Descriptions

v1

Address of first vector.

v2

Address of second vector.

result

Address of vector to set with the result; may be the same address as v1 and/or v2.

function result

Convenience copy of result parameter.

( float ) Q3Vector3D_Dot (
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2
);

Discussion

Return the dot product of two 3D vectors.

Available in inline form as Q3FastVector3D_Dot.

Parameter Descriptions

v1

Address of first vector.

v2

Address of second vector.

function result

Dot product of the two vectors.

( TQ3Status ) Q3Vector3D_DotArray (
    const TQ3Vector3D *inFirstVectors3D,
    const TQ3Vector3D *inSecondVectors3D,
    float *outDotProducts,
    TQ3Boolean *outDotLessThanZeros,
    TQ3Uns32 numVectors,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outDotProductStructSize,
    TQ3Uns32 outDotLessThanZeroStructSize
);

Discussion

Calculate an array of dot products.

Given two arrays of vectors, an array of dot products is returned along with an array of TQ3Booleans indicating which dot products are less than zero.

At least one of dotProducts or dotLessThanZero must be non-NULL, however one parameter may be set to NULL if that information is not required.

Parameter Descriptions

inFirstVectors3D

First array of 3D vectors to dot.

inSecondVectors3D

Second array of 3D vectors to dot.

outDotProducts

Array of scalars to receive the dot products.

outDotLessThanZeros

Array of booleans to receive the "< 0.0" status of the dot products.

numVectors

How many elements are in each array.

inStructSize

Size of one element of input arrays, typically sizeof(TQ3Vector3D).

outDotProductStructSize

Size of one element of the outDotProducts array, typically sizeof(float).

outDotLessThanZeroStructSize

Size of one element of the outDotLessThanZeros array, typically sizeof(TQ3Boolean).

function result

kQ3Success or some error code.

( float ) Q3Vector3D_Length (
    const TQ3Vector3D *vector3D
);

Discussion

Return length of 2D vector.

Available in inline form as Q3FastVector3D_Length.

Parameter Descriptions

vector3D

Address of vector to get length of.

function result

Length of the given vector.

( float ) Q3Vector3D_LengthSquared (
    const TQ3Vector3D *vector3D
);

Discussion

Return squared length of 2D vector.

For many operations, knowing the squared length of a vector is just as good as knowing the actual length (e.g., when sorting a set of vectors by length, or comparing a vector to a cut-off length). But finding the squared length is much faster, since it avoids a costly square root computation.

Available in inline form as Q3FastVector3D_LengthSquared.

Parameter Descriptions

vector3D

Address of vector to get length of.

function result

Squared length of the given vector.

( TQ3Vector3D * ) Q3Vector3D_Negate (
    const TQ3Vector3D *vector3D,
    TQ3Vector3D *result
);

Discussion

Scale a 3D vector by a factor of -1.

Available in inline form as Q3FastVector3D_Negate.

Parameter Descriptions

vector3D

Address of vector to negate.

result

Address of vector to set (may be the same as vector3D).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Normalize (
    const TQ3Vector3D *vector3D,
    TQ3Vector3D *result
);

Discussion

Scale a 3D vector to length 1.

To obtain valid results, the length of vector3D must not be 0.

Available in inline form as Q3FastVector3D_Normalize.

Parameter Descriptions

vector3D

Address of vector to normalize.

result

Address of vector to set (may be the same as vector3D).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Scale (
    const TQ3Vector3D *vector3D,
    float scalar,
    TQ3Vector3D *result
);

Discussion

Scale a 3D vector by the given factor.

Available in inline form as Q3FastVector3D_Scale.

Parameter Descriptions

vector3D

Address of vector to scale.

scalar

Scaling factor.

result

Address of vector to set (may be the same as vector3D).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Set (
    TQ3Vector3D *vector3D,
    float x,
    float y,
    float z
);

Discussion

Set a 3D vector.

Available in inline form as Q3FastVector3D_Set.

Parameter Descriptions

vector3D

Address of vector to set (may be NULL).

x

X coordinate to set into vector3D.

y

Y coordinate to set into vector3D.

z

Z coordinate to set into vector3D.

function result

Convenience copy of vector3D parameter.

( TQ3Vector3D * ) Q3Vector3D_Subtract (
    const TQ3Vector3D *v1,
    const TQ3Vector3D *v2,
    TQ3Vector3D *result
);

Discussion

Subtract 3D vector v2 from v1.

Available in inline form as Q3FastVector3D_Subtract.

Parameter Descriptions

v1

Address of first vector.

v2

Address of vector to subtract from v1.

result

Address of vector to set (may be the same as v1 and/or v2).

function result

Convenience copy of result parameter.

( TQ3Vector2D * ) Q3Vector3D_To2D (
    const TQ3Vector3D *vector3D,
    TQ3Vector2D *result
);

Discussion

Convert 3D vector to 2D, dividing by z.

Note: this operation makes no sense mathematically, but is included for backward-compatibility with QD3D. It's possible that the QD3D function was really intended to convert a 3D rational point to a 2D vector -- see E3RationalPoint3D_To2D, which does the same thing for a 2D point.

Available in inline form as Q3FastVector3D_To2D.

Parameter Descriptions

vector3D

Address of 3D vector to convert.

result

Address of 2D vector to set.

function result

Convenience copy of result parameter.

( TQ3Status ) Q3Vector3D_To3DTransformArray (
    const TQ3Vector3D *inVectors3D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Vector3D *outVectors3D,
    TQ3Uns32 numVectors,
    TQ3Uns32 inStructSize,
    TQ3Uns32 outStructSize
);

Discussion

Transform an array of 3D vectors by a 4x4 matrix.

When you have many vectors to transform, this is a more efficient alternative to calling Q3Vector3D_Transform repeatedly.

Parameter Descriptions

inVectors3D

Array of 3D vectors to transform.

matrix4x4

Transformation matrix.

outVectors3D

Array of vectors to receive output (may be the same as inVectors3D).

numVectors

How many vectors are in each array.

inStructSize

Size of one element of the input array, typically sizeof(TQ3Vector3D).

outStructSize

Size of one element of the output array, typically sizeof(TQ3Vector3D).

function result

kQ3Success or some error code.

( TQ3RationalPoint4D * ) Q3Vector3D_ToRationalPoint4D (
    const TQ3Vector3D *vector3D,
    TQ3RationalPoint4D *result
);

Discussion

Convert 3D vector to 4D rational point, setting w to 0.

Available in inline form as Q3FastVector3D_ToRationalPoint4D.

Parameter Descriptions

vector3D

Address of 3D vector to convert.

result

Address of 4D rational point to set.

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_Transform (
    const TQ3Vector3D *vector3D,
    const TQ3Matrix4x4 *matrix4x4,
    TQ3Vector3D *result
);

Discussion

Transform a 3D vector by a 4x4 matrix.

Note that the translation and perspective components of the matrix is ignored (as if it were really a 3x3 matrix).

Contrast with Q3Point3D_Transform, which does the full 4x4 transformation.

Parameter Descriptions

vector3D

Address of a vector to transform.

matrix4x4

Address of a 4x4 transformation matrix.

result

Address of vector to set (may be the same as vector3D).

function result

Convenience copy of result parameter.

( TQ3Vector3D * ) Q3Vector3D_TransformQuaternion (
    const TQ3Vector3D *vector3D,
    const TQ3Quaternion *quaternion,
    TQ3Vector3D *result
);

Discussion

Transform a 3D vector by a quaternion.

Note that for correct results, the quaternion should be normalized.

Parameter Descriptions

vector3D

Address of a vector to transform.

quaternion

Address of a quaternion to transform by.

result

Address of a vector to set (may be the same as vector3D).

function result

Convenience copy of result parameter.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)