.\"
.\" $XConsortium: p010,v 5.2 94/04/17 20:54:18 rws Exp $
.\"
.\" 
$XMCOPY
.\" Copyright (c) 1990, 1991 by Sun Microsystems, Inc. and the X Consortium.
.\" 
.\"                         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 names of Sun Microsystems,
.\" and the X Consortium 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 "BUILD TRANSFORMATION MATRIX 3" 3P "29 February 1991"
.SH NAME
BUILD TRANSFORMATION MATRIX 3 \- generate a \s-2\&3D\s+2 transformation matrix
to perform a transformation specified by a shift vector, rotation angles,
and scale factors relative to a specified fixed point
.IX "Transformation Matrix" "BUILD TRANSFORMATION MATRIX 3"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pbuild_tran_matrix3 ( pt, shift, x_angle, y_angle, z_angle, scale, error_ind, matrix )
Ppoint3	*pt;	\fIfixed point\fP
Pvec3	*shift;	\fIshift vector\fP
Pfloat	x_angle;	\fIrotation angle X\fP
Pfloat	y_angle;	\fIrotation angle Y\fP
Pfloat	z_angle;	\fIrotation angle Z\fP
Pvec3	*scale;	\fIscale vector\fP
Pint	*error_ind;	\fI\s-2OUT\s+2 error indicator\fP
Pmatrix3	matrix;	\fI\s-2OUT\s+2 transformation matrix\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2BUILD TRANSFORMATION MATRIX 3\s+2 to build a \s-2\&3D\s+2 homogeneous
(4\ \(mu\ 4) transformation matrix that performs the transformation
specified by the input parameters.
.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 \fIpt\fP
A pointer to a Ppoint3 structure containing the
\fIx\fP, \fIy\fP, and \fIz\fP
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:
.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 applied by
the transformation. A Pvec3 structure 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
.sp
.IP "\fIx_angle\fP, \fIy_angle\fP, \fIz_angle\fP"
The angles, in radians, of rotation around the
\fIx\fP, \fIy\fP, and \fIz\fP axes to be applied by the transformation.
Positive angles specify counter-clockwise rotations;
negative angles specify clockwise rotations.
.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 by the transformation.
.SS C Output Parameters
.IP \fIerror_ind\fP
The error number of any error detected by this function.
.IP \fImatrix\fP
A 4 \(mu 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:
.IP
typedef  Pfloat  Pmatrix3[4][4];
.SS Execution
\s-2BUILD TRANSFORMATION MATRIX 3\s+2 returns a \s-2\&3D\s+2 homogeneous (4\ \(mu\ 4)
transformation matrix which performs the transformation specified by the
values of the input parameters.
.LP
The transformation is performed in the following order:
.sp .3
.nf
	\(bu  scale
	\(bu  rotate
	\(bu  shift
.fi
.LP
Scaling and rotation are done in relation to the fixed point defined by
\fIpt\fP.
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP\s+2, *, *, *)
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "SET LOCAL TRANSFORMATION 3 (3P)"
.SM "SET GLOBAL TRANSFORMATION 3 (3P)"
.SM "COMPOSE TRANSFORMATION MATRIX 3 (3P)"
.SM "COMPOSE MATRIX 3 (3P)"
.fi