PEXMapXCToNPC(3) — Subroutines

Name

PEXMapXCToNPC

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_countThe number of points to transform

pointsA pointer to an array of points to transform. The X and Y coordinates of these points are in drawable coordinates (XC). The Z coordinate is in device coordinates (DC).

window_height
The height of the drawable

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

viewportAn 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_countThe number of views to search

viewsThe view entries to search for inclusion of the transformed points

view_returnReturns the view found to contain the most points

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

points_return
Returns a pointer to an array in which to store the transformed points.

Returns

Zero if successful; otherwise, one of the following:

PEXBadViewport
PEXBadSubVolume

Description

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.

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_ret."

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, 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

Museum