PEXMapXCToNPC Utility


Synopsis

 
   int PEXMapXCToNPC(
       int point_count,
       PEXDeviceCoord2D *points,
       unsigned int window_height,
       double z_dc,
       PEXDeviceCoord *viewport,
       PEXNPCSubVolume *npc_sub_volume,
       int view_count,
       PEXViewEntry *views,
       int *view_return,
       int *count_return,
       PEXCoord *points_return
   )
 

Arguments

point_count
The number of points to transform.

points
A pointer to an array of points to transform. The x and y coordinates of these points are in drawable coordinates (XC).

window_height
The height of the drawable.

z_dc
The z DC coordinate to assign the drawable points when converting them to DC.

viewport
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.

npc_sub_volume
A pointer to an NPC subvolume, typically that of a renderer resource.

view_count
The number of views to search

views
The view entries to search for inclusion of the transformed points.

view_return
Returns the view found to contain the most points.

count_return
Returns the number of points contained in the returned view, or the number of points transformed if no views are specified.

points_return
A pointer to an array in which to store the returned transformed points.

Returns

Zero if successful; otherwise, one of the following:

PEXBadViewport
xmin >= xmax, or ymin >= ymax, or zmin > zmax
PEXBadSubVolume
xmin >= xmax, or ymin >= ymax, or zmin > zmax

Description

Invoke PEXMapXCToNPC to map a list of drawable coordinates (XC) to NPC and search a specified list of view entries to determine the view containing the computed NPC points.

The XC points are first transformed to DC, using the specified window height and assigning them the specified z DC value. They are then transformed to 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 in points_return.

When determining the containing view, only the clipping limits of the view are considered, with no consideration given to the clipping flags or the viewing transforms.

If no views are specified, then the XC points are simply transformed to NPC points and returned. The value of the returned view is undefined in this case.

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.

When specifying NPC and DC, the x, y and z limits must be as follows:

  xmin < xmax, ymin < ymax, zmin <= zmax

Errors

None.

See Also

For a list of miscellaneous transformation utilities, see Miscellaneous Transformation Utilities. For a list of related topics, see PEXlib Utilities.