geXForm3d is a transform object. It is used to specify orientations for objects in a coordinate system, and to transform world coordinates to screen coordinates for rendering.
geXForm3d is designed to encapsulate common 3d transform operations. Because of the common use of transforms as temporary objects, we have elected to fully define the geXForm3d structure in the header file, and forgo the Create/Destroy functions. You should resist the temptation to modify the structure elements directly, and instead work with the APIs to make modifications to the transforms.
Whereever angles are specified, the units are radians.
void geXForm3d_Copy(const geXForm3d *Src, geXForm3d *Dest)
Description: Copies the Src transform to the Dest transform.
Parameters:
| Src | Transform to copy from |
| Dest | Transform to copy to |
Returns: void
void geXForm3d_GetEulerAngles(const geXForm3d *XForm, geVec3d *Angles)
Description: Finds Euler angles from XForm.
Parameters:
| XForm | Transform to get angles from |
| Angles | Vector to store axis angles in. The X element gets the X rotation, the Y element gets the Y rotation, and the Z element gets the Z rotation. |
Returns: void
void geXForm3d_GetIn(const geXForm3d *XForm, geVec3d *In)
Description: Gets the vector which, if applied to the translation of the matrix, would move the matrix a distance of 1.0 'in' along the current orientation of the matrix. See the overview for a more detailed discussion of In/Up/Left vectors for matrices.
Parameters:
| XForm | Input transform |
| In | Vector to store the direction in |
Returns: void
void geXForm3d_GetLeft(const geXForm3d *XForm, geVec3d *Left)
Description: Gets the vector which, if applied to the translation of the matrix, would move the matrix a distance of 1.0 'left' along the current orientation of the matrix. See the overview for a more detailed discussion of In/Up/Left vectors for matrices.
Parameters:
| XForm | Input transform |
| Left | Vector to store the direction in |
Returns: void
void geXForm3d_GetTranspose(const geXForm3d *XForm, geXForm3d *Transpose)
Description: Gets the transpose of the matrix. This is a fast operation which swaps rows for columns. This is useful, because for orthonormal transforms, the transpose is equal to the inverse of the transform. Calculating the inverse for a non-orthonormal transform is an expensive operation.
Parameters:
| XForm | Transform to calculate the transpose for |
| Transpose | Transform to place the result in |
Returns: void
void geXForm3d_GetUp(const geXForm3d *XForm, geVec3d *Up)
Description: Gets the vector which, if applied to the translation of the matrix, would move the matrix a distance of 1.0 'up' along the current orientation of the matrix. See the overview for a more detailed discussion of In/Up/Left vectors for matrices.
Parameters:
| XForm | Input transform |
| Up | Vector to store the direction in |
Returns: void
geBoolean geXForm3d_IsOrthogonal(const geXForm3d *XForm)
Description: Determines if a transform is orthogonal (all basis vectors are perpendicular to each other).
Parameters:
| XForm | Transform to test |
Returns: GE_TRUE if the transform is orthogonal, GE_FALSE otherwise.
geBoolean geXForm3d_IsOrthonormal(const geXForm3d *XForm)
Description: Determines if a transform is orthogonal (all basis vectors are perpendicular to each other, and are of length 1.0).
Parameters:
| XForm | Transform to test |
Returns: GE_TRUE if the transform is orthonormal, GE_FALSE otherwise.
Remarks: This is a slow operation because of the need to calculate the length of the basis vectors, which requires 3 square root operations.
void geXForm3d_IsValid(const geXForm3d *XForm)
Description: Determines if the transform is valid. This is a debugging API, primarily. It was designed to test for transforms that contained NAN values on Intel machines, since it is easy to let NAN values slip into calculations. Since NANs do not generate hardware exceptions, it can be exceedingly difficult to determine when data has gone bad.
Parameters:
| XForm | Transform to test |
Returns: GE_TRUE if the transform is valid, GE_FALSE otherwise.
void geXForm3d_Mirror(const geXForm3d *XForm, const geVec3d *PlaneNormal, geFloat PlaneDistance, geXForm3d *MirroredTransform)
Description: Mirrors a transform about a plane.
Parameters:
| XForm | Transform to mirror |
| PlaneNormal | Normal vector of the plane |
| PlaneDistance | Distance from the origin to the plane |
| MirroredTransform | Result - XForm mirrored about the plane specified by PlaneNormal and PlaneDistance. |
Returns: void
Remarks: The plane distance parameter specifies that distance which is the shortest distance from the origin to the plane. This is, by definition, a perpendicular to the plane. The combination of the PlaneNormal and PlaneDistance are just another form of a plane equation. Note: See the overview for a more detailed discussion of left vs. right handed coordinate systems.
void geXForm3d_Multiply(const geXForm3d *M1, const geXForm3d *M2, geXForm3d *Product)
Description: Calculates the product of M1 and M2.
Parameters:
| M1 | Input transform |
| M2 | Input transform |
| Product | Result of M1 * M2 |
Returns: void
Remarks: The result is the concatentation of the transformat in M2 onto the transformation in M1.
void geXForm3d_Orthonormalize(geXForm3d *XForm)
Description: Ensures that a transform's basis vectors are perpendicular to each other, and of length 1.
Parameters:
| XForm | Transform to orthonormalize |
Returns: void
Remarks: This operation essentially removes scaling and other distortions from a matrix. Because floating point error tends to build through multiple matrix operations, it is normally a good idea for an application which stores transforms and accrues operations into them to orthonormalize those matrices from time to time. The matrix library does not do this for you automatically on every operation because the orthonormalization process is slow.
void geXForm3d_Rotate(const geXForm3d *XForm, const geVec3d *Vector, geVec3d *Result)
Description: Rotates a vector by a transform
Parameters:
| XForm | Rotation transform |
| Vector | Vector to be transformed |
| Result | Vector rotated by XForm (XForm * Vector) |
Returns: void
Remarks: Any translation component in the input transform is ignored.
void geXForm3d_RotateX(geXForm3d *XForm, geFloat Angle)
Description: Rotates a transform about the X axis.
Parameters:
| XForm | Transform to apply the rotation to |
| Angle | Angle, in radians, to rotate the transform |
Returns: void
Remarks: The rotation is applied to the existing contents of the transform.
void geXForm3d_RotateY(geXForm3d *XForm, geFloat Angle)
Description: Rotates a transform about the Y axis.
Parameters:
| XForm | Transform to apply the rotation to |
| Angle | Angle, in radians, to rotate the transform |
Returns: void
Remarks: The rotation is applied to the existing contents of the transform.
void geXForm3d_RotateZ(geXForm3d *XForm, geFloat Angle)
Description: Rotates a transform about the Z axis.
Parameters:
| XForm | Transform to apply the rotation to |
| Angle | Angle, in radians to rotate the transform |
Returns: void
Remarks: The rotation is applied to the existing contents of the transform.
void geXForm3d_Scale(geXForm3d *XForm, geFloat X, geFloat Y, geFloat Z)
Description: Scales a transform in all three axes.
Parameters:
| XForm | Transform to apply the scale factors to |
| X | Scale factor to apply to the X axis basis vector of the transform |
| Y | Scale factor to apply to the Y axis basis vector of the transform |
| Z | Scale factor to apply to the Z axis basis vector of the transform |
Returns: void
Remarks: The scaling is applied to the existing contents of the transform.
void geXForm3d_SetEulerAngles(geXForm3d *XForm, const geVec3d *Angles)
Description: Builds a transform from Euler angles.
Parameters:
| XForm | The transform to build |
| Angles | Euler angles. Each component corresponds to the angle to the axis to apply the rotation to. |
Returns: void
Remarks: The transform is built by applying the Z rotation to an identity matrix, then the Y rotation, then the X rotation. Any existing contents in XForm are discarded.
void geXForm3d_SetFromLeftUpIn(geXForm3d *XForm, const geVec3d *Left, const geVec3d *Up, const geVec3d *In)
Description: Builds a transform from 'left', 'up' and 'in' vectors.
Parameters:
| XForm | Transform to build |
| Left | Vector pointing to the 'left' |
| Up | Vector pointing 'up' |
| In | Vector pointing 'in' |
Returns: void
Remarks: See the overview for a discussion of what left, up and in mean for transforms. Any existing contents in XForm are discarded.
void geXForm3d_SetIdentity(geXForm3d *XForm)
Description: Builds the identity matrix
Parameters:
| XForm | Transform to build |
Returns: void
Remarks: The identity matrix is the transform, which when applied to another matrix or vector causes no change.
void geXForm3d_SetMaximalAssertionMode(geBoolean Enable)
Description: Enables or disables strict constraint testing on transforms at runtime.
Parameters:
| Enable | GE_TRUE to enable strict testing, GE_FALSE to disable strict testing. |
Returns: void
Remarks: In debug builds, the transform library performs a number of tests on transforms on many operations. These tests are for things such as NULL pointers, validity (NAN checking), orthonormal tests, orthogonality tests, etc. The sum of these tests imposes a very significant performance penalty on the basic operation of the whole engine, which tends to make debug builds untenable in the development environment. Consequently, we have made the running of the most expensive of these tests conditional to the enabling of maximal assertions in the transform library, and defaulted to not doing these tests. If you are experiencing trouble with your transforms becoming non-orthonormal, or are having other difficult to track down problems with your transforms, you may want to enable these tests. This API is not present in the release builds of the engine.
void geXForm3d_SetScaling(geXForm3d *XForm, geFloat X, geFloat Y, geFloat Z)
Description: Builds a transform that scales by X, Y and Z.
Parameters:
| XForm | Transform to build |
| X | X axis scaling value |
| Y | Y axis scaling value |
| Z | Z axis scaling value |
Returns: void
Remarks: Any existing contents in the transform are discarded.
void geXForm3d_SetTranslation(geXForm3d *XForm, geFloat X, geFloat Y, geFloat Z)
Description: Builds a transform that translates by X, Y and Z.
Parameters:
| XForm | Transform to build |
| X | X translation value |
| Y | Y translation value |
| Z | Z translation value |
Returns: void
Remarks: Any existing contents in the transform are discarded. The rotation component of the matrix is set to identity.
void geXForm3d_SetXRotation(geXForm3d *XForm, geFloat Angle)
Description: Builds a transform that rotates about the X axis.
Parameters:
| XForm | Transform to build |
| Angle | Angle to rotate |
Returns: void
Remarks: Any existing contents in the transform are discarded. The translation component of the matrix is set to zero.
void geXForm3d_SetYRotation(geXForm3d *XForm, geFloat Angle)
Description: Builds a transform that rotates about the Y axis.
Parameters:
| XForm | Transform to build |
| Angle | Angle to rotate |
Returns: void
Remarks: Any existing contents in the transform are discarded. The translation component of the matrix is set to zero.
void geXForm3d_SetZRotation(geXForm3d *XForm, geFloat Angle)
Description: Builds a transform that rotates about the Z axis.
Parameters:
| XForm | Transform to build |
| Angle | Angle to rotate |
Returns: void
Remarks: Any existing contents in the transform are discarded. The translation component of the matrix is set to zero.
void geXForm3d_Transform(const geXForm3d *XForm, const geVec3d *Vector, geVec3d *Result)
Description: Applies a transform to a vector.
Parameters:
| XForm | Transform to apply |
| Vector | Vector to apply the transform to |
| Result | Transformed result |
Returns: void
void geXForm3d_TransformArray(const geXForm3d *XForm, const geVec3d *VectorArray, geVec3d *ResultArray, int32 Count)
Description: Applies a transform to an array of vectors.
Parameters:
| XForm | Transform to apply |
| VectorArray | Array of vectors to apply the transform to |
| ResultArray | Transformed result array |
| Count | Number of vectors in the input array |
Returns: void
Remarks: It is assumed that there is enough space in the output array for the transformed results. This API is provided primarily for efficiency.
void geXForm3d_Translate(geXForm3d *XForm, geFloat X, geFloat Y, geFloat Z)
Description: Translates a transform by X, Y and Z.
Parameters:
| XForm | Transform to be translated |
| X | X displacement to apply to the translation of XForm. |
| Y | Y displacement to apply to the translation of XForm. |
| Z | Z displacement to apply to the translation of XForm. |
Returns: void
Remarks: The translation is applied to the existing contents of XForm, including the translation.
void geXForm3d_TransposeTransform(const geXForm3d *XForm, const geVec3d *Vector, geVec3d *Result)
Description: Applies the transpose transform of XForm to a vector.
Parameters:
| XForm | Input transform |
| Vector | Vector to transform |
| Result | Result vector |
Returns: void
Remarks: This API is provided for efficiency of parts of the engine. Since most spacial transforms are orthogonal, the transpose is equivalent to the inverse, this is a fast way of applying an inverse transform to a vector.