1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
.\"##
.\" $XConsortium: p009,v 5.1 91/02/16 09:36:53 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
|
