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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
.\"##
.\" $XConsortium: p052,v 5.3 94/04/17 20:54:51 hersh 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 "EVALUATE VIEW MAPPING MATRIX 3" 3P "16 August 1991"
.SH NAME
EVALUATE VIEW MAPPING MATRIX 3 \- generate a transformation matrix to
map a \s-2\&3D\s+2 \s-2VRC\s+2 window to a \s-2\&3D\s+2 \s-2NPC\s+2 viewport
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.25i 3i
.nf
void
peval_view_map_matrix3 ( map, error_ind, m )
Pview_map3 *map; \fIview mapping\fP
Pint *error_ind; \fI\s-2OUT\s+2 error indicator\fP
Pmatrix3 m; \fI\s-2OUT\s+2 view mapping matrix\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, *)
.SH DESCRIPTION
.SS Purpose
Use \s-2EVALUATE VIEW MAPPING MATRIX 3\s+2
to calculate the viewing transformation matrix that transforms
a specified \s-2\&3D\s+2 window in View Reference Coordinates (\s-2VRC\s+2)
to a specified \s-2\&3D\s+2 viewport in Normalized
Projection Coordinates (\s-2NPC\s+2).
The viewing transformation may be either a parallel or perspective
transformation.
.LP
The view mapping matrix returned by this function may be used as an
argument to the \s-2SET VIEW REPRESENTATION 3\s+2 function.
See the descriptions of the functions \s-2SET VIEW REPRESENTATION 3\s+2 and
\s-2EVALUATE VIEW ORIENTATION MATRIX 3\s+2 for more information.
.SS C Input Parameters
.IP \fImap\fP
A pointer to a Pview_map3 structure defining the view mapping.
This structure is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pproj_type 'u +\w'proj_ref_point; 'u
.nf
typedef struct {
.sp .2
Plimit win; /* window limits */
Plimit3 proj_vp; /* viewport limits */
Pproj_type proj_type; /* projection type */
Ppoint3 proj_ref_point; /* projection reference point */
Pfloat view_plane; /* view plane distance */
Pfloat back_plane; /* back plane distance */
Pfloat front_plane; /* front plane distance */
.sp .2
} Pview_map3;
.fi
.IP
\fIwin\fP is a Plimit structure containing \fIu\fP and \fIv\fP
\s-2VRC\s+2 values defining the window limits.
Plimit is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pfloat 'u +\w'x_min; 'u
.nf
typedef struct {
.sp .2
Pfloat x_min; /* x minimum */
Pfloat x_max; /* x maximum */
Pfloat y_min; /* y minimum */
Pfloat y_max; /* y maximum */
.sp .2
} Plimit;
.fi
.IP
The fields in Plimit define the \s-2VRC\s+2 window as follows:
.sp
.nf
Plimit.x_min \(eq minimum \fIu\fP coordinate value
Plimit.x_max \(eq maximum \fIu\fP coordinate value
Plimit.y_min \(eq minimum \fIv\fP coordinate value
Plimit.y_max \(eq maximum \fIv\fP coordinate value
.fi
.sp
.IP
\fIproj_vp\fP is a Plimit3 structure containing the \s-2NPC\s+2 viewport limits.
\fImin\fP and \fImax\fP correspond to the back lower left and front upper
right coordinates of the viewport volume, respectively.
Plimit3 is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pfloat 'u +\w'x_min; 'u
.nf
typedef struct {
.sp .2
Pfloat x_min; /* x minimum */
Pfloat x_max; /* x maximum */
Pfloat y_min; /* y minimum */
Pfloat y_max; /* y maximum */
Pfloat z_min; /* z minimum */
Pfloat z_max; /* z maximum */
.sp .2
} Plimit3;
.fi
.IP
\fIproj_type\fP is an enumerated type that may take the following values:
.sp
.nf
\(bu PTYPE_PARAL
\(bu PTYPE_PERSPECT
.fi
.IP
\fIproj_ref_point\fP
is the Projection Reference Point, defined in \s-2VRC\s+2.
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
\fIview_plane\fP
is the \s-2VRC\s+2 location of the view plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.IP
\fIback_plane\fP
is the \s-2VRC\s+2 location of the back plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.IP
\fIfront_plane\fP
is the \s-2VRC\s+2 location of the front plane on the \fIn\fP axis
of the \s-2VRC\s+2 coordinate system.
.SS C Output Parameters
.IP \fIerr_ind\fP
A pointer to the location to store the error number of any error detected
by this function.
.IP \fIm\fP
A Pmatrix3 structure containing the \s-2\&3D\s+2 (4\ \(mu\ 4) transformation matrix
that performs the specified mapping.
Pmatrix3 is defined in phigs.h as follows:
.IP
typedef Pfloat Pmatrix3[4][4];
.SS Execution
If the input parameters are properly defined,
\s-2EVALUATE VIEW MAPPING MATRIX 3\s+2 returns a \s-2\&3D\s+2 (4\ \(mu\ 4)
transformation matrix in the output parameter view mapping matrix.
This transformation matrix performs the specified mapping from the \s-2VRC\s+2
window to the \s-2NPC\s+2 \fIviewport\fP.
.LP
The \fIfront plane\fP, \fIback plane\fP, and \fIview plane\fP all
define planes in \s-2VRC\s+2 space parallel to the \fIuv\fP plane
of the \s-2VRC\s+2 system. The
location of front and back along the \fIn\fP axis of \s-2VRC\s+2
defines the front and back of the volume of \s-2VRC\s+2
that will be mapped to \s-2NPC\s+2.
The view plane locates the view window on the \s-2VRC\s+2 \fIn\fP axis, and
window defines the size of the view window by specifying maximum and
minimum \fIu\fP and \fIv\fP values that establish the edges of the window.
These values taken together establish the volume of \s-2VRC\s+2 space that is
mapped into the \s-2NPC\s+2 viewport.
.LP
The type of projection may be parallel or perspective.
The \fIprojection reference point\fP orients the projectors defining the
surfaces of the view volume.
If the projection type is parallel, the projectors are all parallel to the
vector joining the projection reference point and the center of the
view window (located on the view plane).
If the projection type is perspective, the projectors all converge at the
projection reference point.
Thus, the view volume is a parallelpiped for parallel views, and a portion of
a double rectangular cone for perspective views.
.SH ERRORS
.IP 002
Ignoring function, function requires state (\s-2PHOP, *, *, *\s+2)
.IP 151
Ignoring function, invalid window;
\s-2XMIN \(>= XMAX\s+2 or \s-2YMIN \(>= YMAX\s+2
.IP 152
Ignoring function, invalid viewport;
\s-2XMIN \(>= XMAX, YMIN \(>= YMAX, or ZMIN > ZMAX\s+2
.IP 158
Ignoring function, front plane and back plane distances are
equal when \fIz\fP-extent of the projection viewport is zero
.IP 162
Ignoring function, the projection reference point is between the front
and back planes
.IP 163
Ignoring function, the projection reference point cannot be positioned
on the view plane
.IP 164
Ignoring function, the back plane is in front of the front plane
.IP 155
Ignoring function, the projection viewport limits are not
within \s-2NPC\s+2 range
|
