QuesaTransform.h

Discussion

Functions

( TQ3Status ) Q3CameraTransform_Get (
    TQ3TransformObject theTransform,
    TQ3CameraTransformData *theData
);

Discussion

Get the data of a camera transform object.

This function is not available in QD3D.

Parameter Descriptions

theTransform

The camera transform object to query.

theData

Receives thedata for the transform object.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3CameraTransform_New (
    const TQ3CameraTransformData *theData
);

Discussion

Create a new camera transform object.

This function is not available in QD3D.

Parameter Descriptions

theData

The data for the camera transform object.

function result

A new camera transform object, or NULL on failure.

( TQ3Status ) Q3CameraTransform_Set (
    TQ3TransformObject theTransform,
    const TQ3CameraTransformData *theData
);

Discussion

Set the data of a camera transform object.

This function is not available in QD3D.

Parameter Descriptions

theTransform

The camera transform object to update.

theData

The new data for the transform object.

function result

Success or failure of the operation.

( TQ3Status ) Q3CameraTransform_Submit (
    const TQ3CameraTransformData *theData,
    TQ3ViewObject theView
);

Discussion

Submit a camera transform in immediate mode. Should only be called within a submitting loop.

This function is not available in QD3D.

Parameter Descriptions

theData

The data for the camera transform.

theView

The view currently being submitted to.

function result

Success or failure of the operation.

( TQ3Status ) Q3MatrixTransform_Get (
    TQ3TransformObject transform,
    TQ3Matrix4x4 *matrix
);

Discussion

Get the matrix of a matrix transform.

Parameter Descriptions

transform

The matrix transform object.

matrix

Receives the matrix of the transform.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3MatrixTransform_New (
    const TQ3Matrix4x4 *matrix
);

Discussion

Create a new matrix transform.

Parameter Descriptions

matrix

Initial matrix of the transform.

function result

A new transform object, or NULL on failure.

( TQ3Status ) Q3MatrixTransform_Set (
    TQ3TransformObject transform,
    const TQ3Matrix4x4 *matrix
);

Discussion

Change the matrix of a matrix transform.

Parameter Descriptions

transform

The matrix transform object.

matrix

The new matrix.

function result

Success or failure of the operation.

( TQ3Status ) Q3MatrixTransform_Submit (
    const TQ3Matrix4x4 *matrix,
    TQ3ViewObject view
);

Discussion

Submit a matrix transform in immediate mode. Should only be used within a submitting loop.

Parameter Descriptions

matrix

Matrix of the desired transform.

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3QuaternionTransform_Get (
    TQ3TransformObject transform,
    TQ3Quaternion *quaternion
);

Discussion

Get the quaternion data of a quaternion transform object.

Parameter Descriptions

transform

A quaternion transform object.

quaternion

Receives the quaternion data specifying the transform.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3QuaternionTransform_New (
    const TQ3Quaternion *quaternion
);

Discussion

Create a new quaternion transform object.

Parameter Descriptions

quaternion

Quaternion data specifying the transform.

function result

A new quaternion transform object, or NULL on failure.

( TQ3Status ) Q3QuaternionTransform_Set (
    TQ3TransformObject transform,
    const TQ3Quaternion *quaternion
);

Discussion

Change the quaternion data of a quaternion transform object.

Parameter Descriptions

transform

A quaternion transform object.

quaternion

Quaternion data specifying the transform.

function result

Success or failure of the operation.

( TQ3Status ) Q3QuaternionTransform_Submit (
    const TQ3Quaternion *quaternion,
    TQ3ViewObject view
);

Discussion

Submit a quaternion transform in immediate mode. Should only be called within a submitting loop.

Parameter Descriptions

quaternion

Quaternion data specifying the transform.

view

A view object.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3RasterizeCameraTransform_New (void);

Discussion

Create a new rasterize camera transform object.

A rasterize camera object is a camera transform object which adjusts the camera to allow rasterizing to a draw context.

When this type of transform is active, x and y vertex coordinates reflect pixel (or sub-pixel) coordinates. The z coordinate ranges from 0.0 to 1.0 (where 0.0 is the front of the scene, and 1.0 is the back).

The x/y coordinate system matches that of the draw context being rendered to when the transform is submitted. The origin is placed at the top left of the draw context, while the dimensions of the draw context provide the coordinates of the bottom right "pixel".

Any geometry type or rendering state may be submitted while this transform is active, however some renderers may require transparent objects to be sorted manually to their correct position within the scene.

This function is not available in QD3D.

function result

A new camera transform object, or NULL on failure.

( TQ3Status ) Q3RasterizeCameraTransform_Submit (
    TQ3ViewObject theView
);

Discussion

Submit a rasterize camera transform in immediate mode. Should only be called within a submitting loop.

This function is not available in QD3D.

Parameter Descriptions

theView

The view currently being submitted to.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3ResetTransform_New (void);

Discussion

Create a new reset transform.

When transforms are submitted, they normally concatenate together, as modified by groups or push and pop operations. Submitting a reset transform is a shortcut which sets the current transform to the identity.

function result

A new reset transform, or NULL on failure.

( TQ3Status ) Q3ResetTransform_Submit (
    TQ3ViewObject view
);

Discussion

Submit a reset transform in immediate mode. This should only be called within a submitting loop.

Parameter Descriptions

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_GetAngle (
    TQ3TransformObject transform,
    float *radians
);

Discussion

Get the angle of rotation of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

radians

Receives the angle of rotation, in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_GetData (
    TQ3TransformObject transform,
    TQ3RotateAboutAxisTransformData *data
);

Discussion

Get the state of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

data

Receives the state of the transform.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_GetOrientation (
    TQ3TransformObject transform,
    TQ3Vector3D *axis
);

Discussion

Get the axis direction of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

axis

Receives the axis direction vector.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_GetOrigin (
    TQ3TransformObject transform,
    TQ3Point3D *origin
);

Discussion

Get a point lying on the axis of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

origin

Receives a point on the desired axis of rotation.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3RotateAboutAxisTransform_New (
    const TQ3RotateAboutAxisTransformData *data
);

Discussion

Create a new transform object for rotation about an arbitrary axis. Note that the orientation vector must be normalized.

Parameter Descriptions

data

Structure specifying the initial state of the transform.

function result

A new rotate-about-axis transform object, or NULL on failure.

( TQ3Status ) Q3RotateAboutAxisTransform_SetAngle (
    TQ3TransformObject transform,
    float radians
);

Discussion

Change the angle of rotation of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

radians

New angle of rotation, in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_SetData (
    TQ3TransformObject transform,
    const TQ3RotateAboutAxisTransformData *data
);

Discussion

Set the state of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

data

Structure specifying the new state of the transform.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_SetOrientation (
    TQ3TransformObject transform,
    const TQ3Vector3D *axis
);

Discussion

Set the axis direction of a rotate-about-axis transform object. You must provide a normalized vector.

Parameter Descriptions

transform

A rotate-about-axis transform object.

axis

New axis direction vector (normalized).

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_SetOrigin (
    TQ3TransformObject transform,
    const TQ3Point3D *origin
);

Discussion

Specify a new point lying on the axis of a rotate-about-axis transform object.

Parameter Descriptions

transform

A rotate-about-axis transform object.

origin

A point on the desired axis of rotation.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutAxisTransform_Submit (
    const TQ3RotateAboutAxisTransformData *data,
    TQ3ViewObject view
);

Discussion

Submit a rotate-about-axis transform in immediate mode. Should only be called within a submitting loop.

Parameter Descriptions

data

Structure specifying the state of the transform.

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_GetAboutPoint (
    TQ3TransformObject transform,
    TQ3Point3D *about
);

Discussion

Get a point on the axis of rotation of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

about

Receives a point on the axis of rotation.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_GetAngle (
    TQ3TransformObject transform,
    float *radians
);

Discussion

Get the angle of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

radians

Receives the angle in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_GetAxis (
    TQ3TransformObject transform,
    TQ3Axis *axis
);

Discussion

Get the axis of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

axis

Receives the enumerated value specifying the axis.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_GetData (
    TQ3TransformObject transform,
    TQ3RotateAboutPointTransformData *data
);

Discussion

Get the state of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

data

Receives the state of the transform.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3RotateAboutPointTransform_New (
    const TQ3RotateAboutPointTransformData *data
);

Discussion

Create a new transform for rotation about an axis that is parallel to the x, y, or z axis.

Parameter Descriptions

data

Structure containing the initial state of the transform.

function result

A new rotate-about-point transform, or NULL on failure.

( TQ3Status ) Q3RotateAboutPointTransform_SetAboutPoint (
    TQ3TransformObject transform,
    const TQ3Point3D *about
);

Discussion

Change the point on the axis of rotation of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

about

A point on the desired axis.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_SetAngle (
    TQ3TransformObject transform,
    float radians
);

Discussion

Change the angle of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

radians

The new angle in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_SetAxis (
    TQ3TransformObject transform,
    TQ3Axis axis
);

Discussion

Change the axis of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

axis

The new axis.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_SetData (
    TQ3TransformObject transform,
    const TQ3RotateAboutPointTransformData *data
);

Discussion

Change the state of a rotate-about-point transform.

Parameter Descriptions

transform

A rotate-about-point transform object.

data

Structure containing the new state of the transform.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateAboutPointTransform_Submit (
    const TQ3RotateAboutPointTransformData *data,
    TQ3ViewObject view
);

Discussion

Submit a rotate-about-point transform in immediate mode. Should only be used within a submitting loop.

Parameter Descriptions

data

Structure containing the state of the transform.

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_GetAngle (
    TQ3TransformObject transform,
    float *radians
);

Discussion

Get the angle of rotation of a rotate transform.

Parameter Descriptions

transform

The rotate transform object.

radians

Receives the angle in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_GetAxis (
    TQ3TransformObject renderable,
    TQ3Axis *axis
);

Discussion

Get the axis of a rotate transform.

Parameter Descriptions

renderable

The rotate transform object.

axis

Receives the enumerated value specifying the axis.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_GetData (
    TQ3TransformObject transform,
    TQ3RotateTransformData *data
);

Discussion

Get the state of a rotate transform object.

Parameter Descriptions

transform

The rotate transform object.

data

Receives the data specifying the state of the transform.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3RotateTransform_New (
    const TQ3RotateTransformData *data
);

Discussion

Create a transform object for rotation about the x, y, or z axis.

Parameter Descriptions

data

Data specifying the initial state of the transform.

function result

The new transform object, or NULL on failure.

( TQ3Status ) Q3RotateTransform_SetAngle (
    TQ3TransformObject transform,
    float radians
);

Discussion

Change the angle of a rotate transform.

Parameter Descriptions

transform

The rotate transform object.

radians

New angle of rotation in radians.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_SetAxis (
    TQ3TransformObject transform,
    TQ3Axis axis
);

Discussion

Change the axis of a rotate transform.

Parameter Descriptions

transform

The rotate transform object.

axis

New axis of rotation.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_SetData (
    TQ3TransformObject transform,
    const TQ3RotateTransformData *data
);

Discussion

Change the data of a rotate transform.

Parameter Descriptions

transform

The rotate transform object.

data

Data specifying the new state of the transform.

function result

Success or failure of the operation.

( TQ3Status ) Q3RotateTransform_Submit (
    const TQ3RotateTransformData *data,
    TQ3ViewObject view
);

Discussion

Submit a rotate transform in immediate mode. Should only be used within a submitting loop.

Parameter Descriptions

data

Data specifying the transform.

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3ScaleTransform_Get (
    TQ3TransformObject transform,
    TQ3Vector3D *scale
);

Discussion

Get the scale factors of a scale transform.

Parameter Descriptions

transform

A scale transform object.

scale

Receives the vector containing the 3 scale factors.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3ScaleTransform_New (
    const TQ3Vector3D *scale
);

Discussion

Create a new scale transform. It multiplies the x, y, and z coordinates by the components of a given vector. Most commonly, the 3 scale factors are identical positive numbers.

Parameter Descriptions

scale

Vector specifying scale factors for each coordinate.

function result

A new scale transform object, or NULL on failure.

( TQ3Status ) Q3ScaleTransform_Set (
    TQ3TransformObject transform,
    const TQ3Vector3D *scale
);

Discussion

Change the scale factors of a scale transform.

Parameter Descriptions

transform

A scale transform object.

scale

Vector containing the 3 scale factors.

function result

Success or failure of the operation.

( TQ3Status ) Q3ScaleTransform_Submit (
    const TQ3Vector3D *scale,
    TQ3ViewObject view
);

Discussion

Submit a scale transform in immediate mode. This should only be called within a submitting loop.

Parameter Descriptions

scale

Vector containing the 3 scale factors.

view

A view object.

function result

Success or failure of the operation.

( TQ3Matrix4x4 * ) Q3Transform_GetMatrix (
    TQ3TransformObject transform,
    TQ3Matrix4x4 *matrix
);

Discussion

Get the 4×4 matrix of a transform object.

Non-geometrical transform objects (e.g., camera transforms) can not be expressed as a single 4×4 matrix. These transforms will return the identity matrix.

Parameter Descriptions

transform

A transform object.

matrix

Receives the matrix of the transform.

function result

Address of the resulting matrix, for convenience.

( TQ3ObjectType ) Q3Transform_GetType (
    TQ3TransformObject transform
);

Discussion

Get the subtype of a transform object. Returns kQ3TransformTypeMatrix, kQ3TransformTypeScale, kQ3TransformTypeTranslate, kQ3TransformTypeRotate, kQ3TransformTypeRotateAboutPoint, kQ3TransformTypeRotateAboutAxis, kQ3TransformTypeQuaternion, kQ3TransformTypeReset, or kQ3ObjectTypeInvalid.

Parameter Descriptions

transform

A transform object.

function result

A transform object type or kQ3ObjectTypeInvalid.

( TQ3Status ) Q3Transform_Submit (
    TQ3TransformObject transform,
    TQ3ViewObject view
);

Discussion

Submit a transform object. Should only be used within a submitting loop.

Parameter Descriptions

transform

A transform object.

view

A view object.

function result

Success or failure of the operation.

( TQ3Status ) Q3TranslateTransform_Get (
    TQ3TransformObject transform,
    TQ3Vector3D *translate
);

Discussion

Get the translation vector of a translate transform.

Parameter Descriptions

transform

A translate transform object.

translate

Receives the vector by which the transform translates.

function result

Success or failure of the operation.

( TQ3TransformObject ) Q3TranslateTransform_New (
    const TQ3Vector3D *translate
);

Discussion

Create a new translation transform.

Parameter Descriptions

translate

Vector by which to translate.

function result

A new transform object, or NULL on failure.

( TQ3Status ) Q3TranslateTransform_Set (
    TQ3TransformObject transform,
    const TQ3Vector3D *translate
);

Discussion

Change the translation vector of a translate transform.

Parameter Descriptions

transform

A translate transform object.

translate

New vector by which to translate.

function result

Success or failure of the operation.

( TQ3Status ) Q3TranslateTransform_Submit (
    const TQ3Vector3D *translate,
    TQ3ViewObject view
);

Discussion

Submit a translate transform in immediate mode. Should only be called within a submitting loop.

Parameter Descriptions

translate

Vector by which to translate.

view

A view object.

function result

Success or failure of the operation.

Structs

typedef struct TQ3CameraTransformData {
    TQ3Matrix4x4                                localToWorld;
    TQ3Matrix4x4                                worldToCamera;
    TQ3Matrix4x4                                cameraToFrustum;
} TQ3CameraTransformData;

Discussion

State data for a transform object that manipulates the camera matrix state.

Vertices are passed through three transforms to convert them from local coordinates to the canonical viewing frustum.

The localToWorld transform converts local coordinates to the world coordinate system.

The worldToCamera transform converts world coordinates to the camera's coordinate system, which places the camera at the origin and establishes the camera's view of the world.

The cameraToFrustum converts the camera's coordinate system to the canonical viewing frustum. This frustum is a box centered on the origin, ranging from -1 to +1 in x and y. In z the frustum ranges from 0 at the near clipping plane to -1 at the far clipping plane.

Once vertices have been transformed to the canonical frustum, a portion of the frustum is then selected using the current camera's viewPort and that portion mapped to the draw context's pane. These two steps are controlled by the current camera and draw context, and are not affected by a camera transform object.

Field Descriptions

localToWorld

The local-to-world matrix.

worldToCamera

The world-to-camera matrix.

cameraToFrustum

The camera-to-frustum matrix.

typedef struct TQ3RotateAboutAxisTransformData {
    TQ3Point3D                                  origin;
    TQ3Vector3D                                 orientation;
    TQ3Float32                                  radians;
} TQ3RotateAboutAxisTransformData;

Discussion

State data for a transform object that rotates about an arbitrary axis. Note that the orientation vector must be normalized.

Field Descriptions

origin

A point on the axis of rotation.

orientation

A normal vector determining the direction of the axis.

radians

Number of radians to rotate about the axis.

typedef struct TQ3RotateAboutPointTransformData {
    TQ3Axis                                     axis;
    TQ3Float32                                  radians;
    TQ3Point3D                                  about;
} TQ3RotateAboutPointTransformData;

Discussion

State data for a rotate-about-point transform.

Field Descriptions

axis

Enumerated value specifying the x, y, or z axis.

radians

Number of radians to rotate about the axis.

about

A point on the desired axis of rotation.

typedef struct TQ3RotateTransformData {
    TQ3Axis                                     axis;
    TQ3Float32                                  radians;
} TQ3RotateTransformData;

Discussion

State data for a rotate transform.

Field Descriptions

axis

Enumerated value specifying the x, y, or z axis.

radians

Number of radians to rotate about the axis.

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