BUILD TRANSFORMATION MATRIX 3(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

BUILD TRANSFORMATION MATRIX 3 − generate a 3D transformation matrix to perform a transformation specified by a shift vector, rotation angles, and scale factors relative to a specified fixed point

SYNOPSIS

C Syntax

void
pbuild_tran_matrix3 ( pt, shift, x_angle, y_angle, z_angle, scale, error_ind, matrix )
Ppoint3∗pt;fixed point
Pvec3∗shift;shift vector
Pfloatx_angle;rotation angle X
Pfloaty_angle;rotation angle Y
Pfloatz_angle;rotation angle Z
Pvec3∗scale;scale vector
Pint∗error_ind;OUT error indicator
Pmatrix3matrix;OUT transformation matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use BUILD TRANSFORMATION MATRIX 3 to build a 3D homogeneous (4 × 4) transformation matrix that performs the transformation specified by the input parameters.

The returned matrix may be passed as an argument to SET LOCAL TRANSFORMATION 3 or SET GLOBAL TRANSFORMATION 3 to modify the modelling transformation applied to output primitives during traversal.

C Input Parameters

ptA pointer to a Ppoint3 structure containing the x, y, and z coordinates of a fixed point in Modelling Coordinates. Scaling and rotation are performed relative to this fixed point. The Ppoint3 structure is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x coordinate ∗/
Pfloaty;/∗ y coordinate ∗/
Pfloatz;/∗ z coordinate ∗/
} Ppoint3;

shiftA pointer to a Pvec3 structure containing x, y, and z coordinates defining the shift (translation) to be applied by the transformation. A Pvec3 structure is defined in phigs.h as follows:

typedef struct {
Pfloatdelta_x;/∗ x magnitude ∗/
Pfloatdelta_y;/∗ y magnitude ∗/
Pfloatdelta_z;/∗ z magnitude ∗/
} Pvec3;

x_angle, y_angle, z_angle
The angles, in radians, of rotation around the x, y, and z axes to be applied by the transformation. Positive angles specify counter-clockwise rotations; negative angles specify clockwise rotations.

scaleA pointer to a Pvec3 structure containing x, y, and z values defining the scale factors to be applied by the transformation.

C Output Parameters

error_ind
The error number of any error detected by this function.

matrixA 4 × 4 homogeneous transformation matrix that performs the transformation defined by the input parameters. The matrix is returned in a Pmatrix array defined in phigs.h as follows:

typedef Pfloat Pmatrix3[4][4];

Execution

BUILD TRANSFORMATION MATRIX 3 returns a 3D homogeneous (4 × 4) transformation matrix which performs the transformation specified by the values of the input parameters.

The transformation is performed in the following order:

• scale
• rotate
• shift

Scaling and rotation are done in relation to the fixed point defined by pt.

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

Museum