.\"##
.\" $XConsortium: p024,v 5.2 94/04/17 20:54:28 rws Exp $
.\"##
.\"## 
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc. 
.\"## 
.\"##                         All Rights Reserved
.\"## 
.\"## Permission to use, copy, modify, and distribute this software and its 
.\"## documentation for any purpose and without fee is hereby granted, 
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in 
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity 
.\"## pertaining to distribution of the software without specific, written 
.\"## prior permission.  
.\"## 
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "COMPOSE TRANSFORMATION MATRIX 3" 3P "29 February 1991"
.SH NAME
COMPOSE TRANSFORMATION MATRIX 3 \- compose a \s-2\&3D\s+2 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
.IX "Transformation Matrix" "COMPOSE TRANSFORMATION MATRIX 3"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pcompose_tran_matrix3 ( m, pt, shift, x_ang, y_ang, z_ang, scale, error_ind, result )
Pmatrix3	m;	\fItransformation matrix\fP
Ppoint3	*pt;	\fIfixed point\fP
Pvec3	*shift;	\fIshift vector\fP
Pfloat	x_ang;	\fIrotation angle \s-2X\s+2\fP
Pfloat	y_ang;	\fIrotation angle \s-2Y\s+2\fP
Pfloat	z_ang;	\fIrotation angle \s-2Z\s+2\fP
Pvec3	*scale;	\fIscale vector\fP
Pint	*error_ind;	\fI\s-2OUT\s+2 error indicator\fP
Pmatrix3	result;	\fI\s-2OUT\s+2 transformation matrix\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2COMPOSE TRANSFORMATION MATRIX 3\s+2 to generate a \s-2\&3D\s+2 (4\ \(mu\ 4)
matrix that composes an existing 4\ \(mu\ 4 matrix with a transformation
specified by \s-2\&3D\s+2 values for scaling, rotation, and translation about
a fixed point.
.LP
The returned matrix may be passed as an argument to
\s-2SET LOCAL TRANSFORMATION 3\s+2 or \s-2SET GLOBAL TRANSFORMATION 3\s+2
to modify the modelling transformation applied to output primitives during
traversal.
.SS C Input Parameters
.IP \fIm\fP
The \s-2\&3D\s+2 (4\ \(mu\ 4) homogeneous transformation matrix to use in the
composition.
This matrix is a Pmatrix3 type, defined in phigs.h as follows:
.sp .4
typedef  Pfloat  Pmatrix3[4][4];
.IP \fIpt\fP
A pointer to a Ppoint3 structure containing the \fIx\fP, \fIy\fP, and \fIz\fP 
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:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'x;     'u
.nf
typedef struct  {
.sp .2
	Pfloat	x;	/* x coordinate */
	Pfloat	y;	/* y coordinate */
	Pfloat	z;	/* z coordinate */
.sp .2
} Ppoint3;
.fi
.IP \fIshift\fP
A pointer to a Pvec3 structure containing  \fIx\fP, \fIy\fP, and \fIz\fP
coordinates
defining the shift (translation) to be added to the transformation.
Pvec3 is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pfloat     'u +\w'delta_x;     'u
.nf
typedef struct {
.sp .2
	Pfloat	delta_x;	/* x magnitude */
	Pfloat	delta_y;	/* y magnitude */
	Pfloat	delta_z;	/* z magnitude */
.sp .2
} Pvec3;
.fi
.IP "\fIx_ang\fP, \fIy_ang\fP, \fIz_ang\fP"
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.
.IP \fIscale\fP
A pointer to a Pvec3 structure containing \fIx\fP, \fIy\fP, and \fIz\fP 
values
defining the scale factors to be applied to the transformation.
.SS C Output Parameters
.IP \fIerror_ind\fP
A pointer to the location to store the error number of any error detected
by this function.
.IP \fIresult\fP
The resulting \s-2\&3D\s+2 (4\ \(mu\ 4) transformation matrix.
.SS Execution
\s-2COMPOSE TRANSFORMATION MATRIX 3\s+2 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.
.LP
The composition is performed as:
.sp .4
	\fIresult\fP = \fIa\fP \s-2x\s+2 \fIb\fP
.LP
Where \fIb\fP is the input matrix and \fIa\fP is the matrix built from
the other input parameters.
.LP
The order of operations used to build the transformation matrix \fIb\fP is:
.sp .4
.nf
	\(bu  scale
	\(bu  rotate
	\(bu  shift (translate)
.fi
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP, *, *, *\s+2)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "COMPOSE TRANSFORMATION MATRIX (3P)"
.SM "BUILD TRANSFORMATION MATRIX 3 (3P)"
.SM "COMPOSE MATRIX 3 (3P)"
.SM "SET LOCAL TRANSFORMATION 3 (3P)"
.SM "SET GLOBAL TRANSFORMATION 3 (3P)"
.fi