.\" @(#)PEXMapXCToNPC2D.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXMapXCToNPC2D 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXMapXCToNPC2D - utility function
.SH SYNTAX
.HP
int PEXMapXCToNPC2D\^(\^int \fIpoint_count\fP, PEXDeviceCoord2D *\fIpoints\fP, unsigned int \fIwindow_height\fP, PEXDeviceCoord2D *\fIviewport\fP, PEXNPCSubVolume *\fInpc_sub_volume\fP, int \fIview_count\fP, PEXViewEntry *\fIviews\fP, int *\fIview_return\fP, int *\fIcount_return\fP\^, PEXCoord2D *\fIpoints_return\fP\^)
.SH PARAMETERS
.IP \fIpoint_count\fP 1i
The number of points to transform.
.IP \fIpoints\fP 1i
A pointer to an array of drawable-coordinate (XC) points to transform.
.IP \fIwindow_height\fP 1i
The height of the drawable.
.IP \fIviewport\fP 1i
An array of two device coordinate points defining a viewport, typically that
of a renderer resource.  The first point in the array is the lower-left corner
of the viewport; the second point is the upper-right.
.IP \fInpc_sub_volume\fP 1i
A pointer to an NPC subvolume, typically that of a renderer resource.
.IP \fIview_count\fP 1i
The number of views to search.
.IP \fIviews\fP 1i
The view entries to search for inclusion of the transformed points.
.IP \fIview_return\fP 1i
The view found to contain the most points.
.IP \fIcount_return\fP 1i
Returns the number of points contained in the returned view, or the number of
points transformed if no views are specified.
.IP \fIpoints_return\fP 1i
A pointer to an array in which to store the transformed points.
.SH RETURNS
.LP
Zero if successful; otherwise, one of the following:
.LP
.RS
.nf
.B PEXBadViewport
.B PEXBadSubVolume
.RE
.fi
.SH DESCRIPTION
.\" indexing
.IX PEXMapXCToNPC2D
.IX "Coordinates" "PEXMapXCToNPC2D"
.IX "Utility Functions" PEXMapXCToNPC2D
.LP
This function maps a list of drawable coordinates (XC) to
NPC, and searches a specified list of view entries to
determine the view containing the computed NPC points.
.LP
The XC points are first transformed to 2D DC, using the
specified window height, then transformed to 2D NPC by the
viewport-to-subvolume transform implied by the specified viewport and
NPC subvolume.  The specified list of views is then searched,
in order from 0 to the number of views minus 1, and the index of the first
view containing all the NPC points is returned.  If no view
contains all the points, then the lowest-index view containing
the most points is returned.  In this case, only the points
within the view are returned.
.LP
When determining the containing view, only the x-y clipping
limits of the view are considered, with no consideration given
to the front and back clipping limits, the clipping flags, or
the viewing transforms.
.LP
If no views are specified, the XC points
are simply transformed to NPC points and returned.  The
value of the returned view is undefined in this case.
.LP
The viewport-to-subvolume transformation maps to NPC the largest
region of the specified viewport that has the same aspect ratio as
the NPC subvolume and is anchored at the back lower-left of the
viewport (the corner of the viewport with the minimum X, Y and
Z coordinates).  Points that lie outside this region of the
viewport are not transformed.
.LP
When specifying NPC and DC, the X, Y and Z limits must be as follows:
.IP
xmin < xmax ,  ymin < ymax ,  zmin <= zmax
.SH ERRORS
None
.SH SEE ALSO
.LP
.nf
.BR PEXMapXCToNPC (3)
.BR PEXNPCToXCTransform2D (3)
.BR PEXXCToNPCTransform2D (3)
.fi