.\"##
.\" $XConsortium: p009,v 5.2 94/04/17 20:54:17 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 "BUILD TRANSFORMATION MATRIX" 3P "29 February 1991"
.SH NAME
BUILD TRANSFORMATION MATRIX  \- generate a \s-2\&2D\s+2
transformation matrix to perform a transformation specified by a shift vector,
rotation angle, and scale factors relative to a specified fixed point
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
pbuild_tran_matrix ( pt, shift, angle, scale, error_ind, matrix )
Ppoint	*pt;	\fIfixed point\fP
Pvec	*shift;	\fIshift vector\fP
Pfloat	angle;	\fIrotation angle\fP
Pvec	*scale;	\fIscale vector\fP
Pint	*error_ind;	\fI\s-2OUT\s+2 error indicator\fP
Pmatrix	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\s+2 to calculate the \s-2\&2D\s+2
homogeneous (3\ \(mu\ 3) 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\s+2 or \s-2SET GLOBAL TRANSFORMATION\s+2
to modify the modelling transformation that is
applied to output primitives during traversal.
.SS C Input Parameters
.IP \fIpt\fP
.I pt
points to the Ppoint structure containing the \fIx\f and \fIy\f coordinates of a fixed point in Modelling Coordinates.
Scaling and rotation are performed relative to this fixed point.
Ppoint 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 */
.sp .2
} Ppoint;
.fi
.IP \fIshift\fP
.I shift
points to a Pvec structure containing the \fIx\f and \fIy\f coordinates 
that define the shift (translation) applied by the transformation.
Pvec 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 */
.sp .2
} Pvec;
.fi
.IP \fIangle\fP
This is the angle of rotation, in radians, applied by the transformation.
A positive angle is a counter-clockwise rotation;
a negative angle is clockwise rotation.
.IP \fIscale\fP
.I scale 
points to a Pvec structure containing \fIx\f and \fIy\f values
defining the scale factors to be applied by
the transformation.
.SS C Output Parameters
.IP \fIerror_ind\fP
.I error_ind 
points to the location that stores the error number for any error 
detected by this function.
.IP \fImatrix\fP
A 3 \(mu 3 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  Pmatrix[3][3];
.SS Execution
\s-2BUILD TRANSFORMATION MATRIX\s+2 returns a \s-2\&2D\s+2
(3 \(mu 3) homogeneous transformation matrix that performs
the transformation specified by the input
parameters.
.LP
The transformation is performed in the following order:
.LP
.nf
	\(bu  scale
	\(bu  rotate
	\(bu  shift
.LP
.fi
Scaling and rotation are done in relation to the fixed point.
.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 (3P)"
.SM "SET GLOBAL TRANSFORMATION (3P)"
.SM "COMPOSE TRANSFORMATION MATRIX (3P)"
.SM "COMPOSE MATRIX (3P)"
.fi