BUILD TRANSFORMATION MATRIX 3(3P) — SUNPHIGS LIBRARY

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
pbuildtran3 ( pt, shift, x_angle, y_angle, z_angle, scale, error_ind, matrix )
Ppoint3∗pt;fixed point
Pvector3∗shift;shift vector
Pfloatx_angle;rotation angle X
Pfloaty_angle;rotation angle Y
Pfloatz_angle;rotation angle Z
Pvector3∗scale;scale vector
Pint∗error_ind;OUT error indicator
Pmatrix3matrix;OUT transformation matrix

FORTRAN Syntax

SUBROUTINE pbltm3 ( X0, Y0, Z0, DX, DY, DZ, PHIX, PHIY, PHIZ, FX, FY, FZ,
ERRIND, XFRMT )
REALX0, Y0, Z0fixed point
REALDX, DY, DZshift vector
REALPHIX, PHIY, PHIZrotation angles (radians)
REALFX, FY, FZscale factor vector
INTEGERERRINDOUT error indicator
REALXFRMT(4, 4)OUT transformation matrix

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use BUILD TRANSFORMATION MATRIX 3 to build a 3D homogeneous (4 x 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 Pvector3 structure containing x, y, and z coordinates defining the shift (translation) to be applied by the transformation. A Pvector3 structure is defined in phigs.h as follows:

typedef struct {
Pfloatx;/∗ x magnitude ∗/
Pfloaty;/∗ y magnitude ∗/
Pfloatz;/∗ z magnitude ∗/
} Pvector3;

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 Pvector3 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 x 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];

FORTRAN Input Parameters

X0, Y0, Z0
The x, y, and z coordinates of a fixed point in Modelling Coordinates. Scaling and rotation are performed relative to this fixed point.

DX, DY, DZ
The x, y, and z coordinates defining the shift (translation) to be applied by the transformation.

PHIX, PHIY, PHIZ
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.

FX, FY, FZ
The x, y, and z values defining the scale factors to be applied by the transformation.

FORTRAN Output Parameters

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

XFRMT
A 4 x 4 homogeneous transformation matrix that performs the transformation defined by the input parameters.

Execution

BUILD TRANSFORMATION MATRIX 3 returns a 3D homogeneous (4 x 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