.\" @(#)PEXViewMappingMatrix.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXViewMappingMatrix 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXViewMappingMatrix - utility function
.SH SYNTAX
.HP
int PEXViewMappingMatrix\^(\^PEXCoord2D *\fIframe\fP, PEXNPCSubVolume *\fIviewport\fP, int \fIperspective\fP, PEXCoord *\fIprp\fP, double \fIview_plane\fP, double \fIback_plane\fP, double \fIfront_plane\fP, PEXMatrix \fImatrix_return\fP\^)
.SH PARAMETERS
.IP \fIframe\fP 1i
Array of 2 2D VRC locations which mark a rectangle in the view plane.
.IP \fIviewport\fP 1i
NPC viewport into which the frame gets mapped.
.IP \fIperspective\fP 1i
Flag to indicate whether a perspective view is desired, a value of
.B True.
Requests that perspective be applied.
.IP \fIprp\fP 1i
Projection reference point.
.IP \fIview_plane\fP 1i
VRC position of view plane w.r.t. the VRP.
.IP \fIback_plane\fP 1i
VRC position of the back plane w.r.t. the VRP.
.IP \fIfront_plane\fP 1i
VRC position of the front plane w.r.t. the VRP.
.IP \fImatrix_return\fP 1i
Matrix into which result is stored.
.SH RETURNS
.LP
Zero if successful; otherwise, one of the following:
.LP
.RS
.nf
\fBPEXBadLimits\fP
\fBPEXBadViewport\fP
\fBPEXBadPlanes\fP
\fBPEXBadPRP\fP
.RE
.fi
.SH DESCRIPTION
.\" indexing
.IX PEXViewMappingMatrix
.LP
This function creates a view mapping matrix that transforms
a volume specified in view reference coordinates (VRC) to a
volume in normalized projection coordinates (NPC).  This
matrix is used in conjunction with a view orientation matrix
as the viewing matrices for a designated view.
.LP
The axes of VRC form a right-handed coordinate system.
The z axis is along the VPN (view plane normal, see
.PN PEXViewOrientation ),
The Y axis is fixed by VUP, and
the X axis is determined so that the three axes form a right-handed
coordinate system.
.LP
The front plane, back plane, and view plane all define
planes in VRC parallel to the VRC x-y plane. The location of
.I front_plane
and
.I back_plane
along the z axis of VRC defines
the front and back of the volume of VRC that will be mapped
to the specified NPC viewport.  The view plane locates the
view frame or "window" on the VRC z axis. The two points in
frame determine the size of the view window by specifying
lower left (frame[0]) and upper right (frame[1]) x and y VRC
points of the window on the view plane. These values taken
together establish the volume of VRC space that is mapped
into the NPC viewport.
.LP
The type of projection may be parallel or perspective.  The
projection reference point (PRP) orients the projectors
defining the surfaces of the view volume.  If perspective
indicator is
.B False,
then the projection type is parallel and
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 perspective is
.B True,
then
the projectors all converge at the projection reference
point.  Thus, the view volume is a parallelpiped for
parallel views, and a truncated pyramid for perspective views.
.LP
When specifying NPC, the X, Y and Z limits must be as follows:
.LP
.RS
xmin < xmax ,  ymin < ymax ,  zmin <= zmax
.RE
.SH DATA STRUCTURES
.LP
.nf
typedef struct {
	PEXCoord	min;
	PEXCoord	max;
.br
} PEXNPCSubVolume;
.fi
.sp .5
See
.B PEXlib.h.
.SH ERRORS
.LP
None
.SH SEE ALSO
.LP
.nf
.BR PEXViewMappingMatrix2D (3)
.BR PEXViewOrientationMatrix (3)
.BR PEXViewOrientationMatrix2D (3)
.fi