COMPOSE TRANSFORMATION MATRIX 3(3P) — SUNPHIGS LIBRARY

NAME

COMPOSE TRANSFORMATION MATRIX 3 − compose a 3D transformation matrix, which is the composition of a specified matrix and a transformation matrix defined by a fixed point, shift vector, rotation angle, and scale factors

SYNOPSIS

C Syntax

void
pcomposetran3 ( matrix, pt, shift, x_angle, y_angle, z_angle, scale, error_ind, result )
Pmatrix3matrix;transformation 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
Pmatrix3result;OUT transformation matrix

FORTRAN Syntax

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

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use COMPOSE TRANSFORMATION MATRIX 3 to generate a 3D (4 x 4) matrix that composes an existing 4 x 4 matrix with a transformation specified by 3D values for scaling, rotation, and translation about a fixed point.

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

matrixThe 3D (4 x 4) homogeneous transformation matrix to use in the composition. This matrix is a Pmatrix3 type, defined in phigs.h as follows: typedef Pfloat Pmatrix3[4][4]

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

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

shiftA pointer to a Pvector structure containing x, y, and z coordinates defining the shift (translation) to be added to the transformation. Pvector 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 of rotation about the indicated axes, in radians, to be added to the transformation. A positive angle is a counter-clockwise rotation. A negative angle is clockwise rotation.

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

C Output Parameters

error_ind
A pointer to the location to store the error number of any error detected by this function.

resultThe resulting 3D (4 x 4) transformation matrix.

FORTRAN Input Parameters

XFRMTI
The 3D (4 x 4) homogeneous transformation matrix to use in the composition.

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 added to the transformation.

PHIX, PHIY, PHIZ
The angles of rotation about the indicated axes, in radians, to be added to the transformation. A positive angle is a counter-clockwise rotation. A negative angle is clockwise rotation.

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

FORTRAN Output Parameters

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

XFRMTO
The resulting 3D (4 x 4) transformation matrix.

Execution

COMPOSE TRANSFORMATION MATRIX 3 returns the matrix that performs the transformation resulting from the composition of the input matrix and the matrix specified by the input parameters shift, angle, and scale. Rotation and scaling are calculated relative to the fixed point.

The composition is performed as: result = a x b

Where b is the input matrix and a is the matrix built from the other input parameters.

The order of operations used to build the transformation matrix b is:

• scale
• rotate
• shift (translate)

ERRORS

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

Museum