.\" @(#)PEXMapDCToWC.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXMapDCToWC 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXMapDCToWC - Map Device Coordinate Points to World Coordinate Points
.SH SYNTAX
.HP
Status PEXMapDCToWC\^(\^Display *\fIdisplay\fP\^, PEXWorkstation \fIworkstation\fP\^, unsigned long \fIdc_count\fP\^, PEXDeviceCoord *\fIdc_points\fP\^, unsigned int *\fIview_index_return\fP\^, unsigned long *\fIwc_count_return\fP\^, PEXCoord **\fIwc_points_return\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIworkstation\fP 1i
The resource identifier of the workstation.
.IP \fIdc_count\fP 1i
The number of device coordinate points.
.IP \fIdc_points\fP 1i
An array of device coordinates.
.IP \fIview_index_return\fP 1i
Returns the view index of the view containing most or all of the points.
.IP \fIwc_count_return\fP 1i
Returns the number of world coordinate points.
.IP \fIwc_points_return\fP 1i
Returns an array of world coordinate points.
.SH RETURNS
.LP
Zero if unsuccessful, non-zero otherwise.
.SH DESCRIPTION
.\" indexing
.IX PEXMapDCToWC
.IX "Coordinates" "PEXMapDCToWC"
.LP
This function maps the device coordinate points to world coordinate points
using the specified workstation.  Each view in the workstation's current
view table, which has an inverse, is checked to see if it contains all the
specified device coordinate points.
(If the view transform has no inverse, it is not considered.)
The index of the view with the highest view transformation input
priority that contains all of the points is returned.  If no view contains all
the points, the index of the view containing the most points is returned.  The
points are transformed to world coordinates by passing them through the inverse
of the view transform associated with the view index.
Points that are clipped
(outside the viewport) will not be transformed and returned, so the number
of points returned may be less than the number sent.
.LP
PEXlib allocates memory for the return value.
.B XFree
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXWorkstation;
.sp
typedef struct {
	short	x;
	short	y;
	float	z;
.br
} PEXDeviceCoord;
.sp
typedef struct {
	float	x;
	float	y;
	float	z;
.br
} PEXCoord;
.fi
.SH ERRORS
.TP
.SB BadPEXWorkstation
The specified
.I workstation
resource identifier is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXMapWCToDC (3)
.BR PEXSetWorkstationViewPriority (3)
.fi