.\" @(#)PEXPickOne.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXPickOne 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXPickOne - Pick One Traversal
.SH SYNTAX
.HP
PEXPickPath *PEXPickOne\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\fP\^, PEXStructure \fIstructure\fP\^, int \fImethod\fP\^, int \fIpick_device_type\fP\^, PEXPickRecord *\fIpick_record\fP\^, int *\fIstatus_return\fP\^, int *\fIundetectable_return\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIdrawable\fP 1i
The resource identifier of a drawable.
.IP \fIrenderer\fP 1i
The resource identifier of the renderer.
.IP \fIstructure\fP 1i
The resource identifier for the root structure of the structure network.
.IP \fImethod\fP 1i
The pick one method (
.B PEXPickLast,
.B PEXPickClosestZ,
.B PEXPickVisibleAny,
.B PEXPickVisibleClosest
).
.IP \fIpick_device_type\fP 1i
The pick device type (
.B PEXPickDeviceDCHitBox
or
.B PEXPickDeviceNPCHitVolume
).
.IP \fIpick_record\fP 1i
A pointer to the pick data record.
.IP \fIstatus_return\fP 1i
Returns the status of the pick operation.
.IP \fIundetectable_return\fP 1i
Returns
.SB True
or
.SB False
indicating whether another pick better satisfied the pick criteria with the exception that it did not pass the pick filter test.
.SH RETURNS
.LP
A pointer to the pick path; a null pointer if unsuccessful or no pick
(see also
.I status_return).
.SH DESCRIPTION
.\" indexing
.IX PEXPickOne
.IX "Picking" "PEXPickOne"
.LP
This function traverses the specified structure network.
.LP
Standard pick one methods are
.B PEXPickLast,
.B PEXPickClosestZ,
.B PEXPickVisibleAny
and
.B PEXPickVisibleClosest.
The supported pick device types are inquirable via
.BR PEXGetEnumTypeInfo (3) .
.LP
If a primitive was picked, the returned pick status is
.B PEXPick.
If no primitive was picked, the returned pick status is
.B PEXNoPick,
and the returned pick path is a null pointer.
If the renderer's
.I drawable
was destroyed or resized during the pick operation, the returned pick status
is
.B PEXAbortedPick
and the returned pick path is a null pointer.
.LP
If there was a primitive which more closely satisfied the pick criteria, but
did not pass the pick filter test, then the undetectable pick return status
will be
.SB True.
Otherwise, it will be
.SB False.
.LP
If the specified drawable does not have the same root and depth as
the drawable that was used to create the renderer, or, if the
specified drawable is not one of the supported drawables returned by
.BR PEXMatchRenderingTargets (3) ,
a Match error will be generated.
If the renderer state is set to
.B PEXRendering
or
.B PEXPicking
when this function is called,
then the operation in progress is aborted, the
.B PEXPickOne
function is completed, and a
.SB BadPEXRendererState
error is sent.
.LP
PEXlib allocates memory for the return value.
.BR PEXFreePickPaths (3)
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXRenderer;
.sp
typedef union {
	PEXPDNPCHitVolume	volume;
	PEXPDDCHitBox	box;
	PEXPickDataRecord	data;
.br
} PEXPickRecord;
.sp
typedef  PEXNPCSubVolume	PEXPDNPCHitVolume;
.sp
typedef struct {
	PEXCoord	min;
	PEXCoord	max;
.br
} PEXNPCSubVolume;
.sp
typedef struct {
	float	x;
	float	y;
	float	z;
.br
} PEXCoord;
.sp
typedef struct {
	PEXDeviceCoord2D	position;
	float			distance;
.br
} PEXPDDCHitBox;
.sp
typedef struct {
	short	x;
	short	y;
.br
} PEXDeviceCoord2D;
.sp
typedef struct {
	unsigned short		length;	/* number of bytes in record */
	char			*record;
.br
} PEXPickDataRecord;
.sp
typedef struct {
	unsigned long		count;	/* number of elements */
	PEXPickElementRef	*elements;
.br
} PEXPickPath;
.sp
typedef struct {
	PEXStructure	sid;
	unsigned long	offset;
	unsigned long	pick_id;
.br
} PEXPickElementRef;
.sp
typedef  XID	PEXStructure;
.fi
.SH ERRORS
.TP
.SB BadAlloc
The server failed to allocate resources necessary to complete request.
.TP
.SB BadDrawable
The specified drawable resource identifier is invalid.
.TP
.SB BadMatch
The specified drawable is unsupported, or the specified renderer resource was
not created with a compatible drawable.
.TP
.SB BadPEXRenderer
The specified renderer resource identifier is invalid.
.TP
.SB BadPEXRendererState
The specified renderer was in an invalid state.
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.TP
.SB BadValue
The pick record contains invalid data, or the pick device type is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXBeginPickOne (3)
.BR PEXEndPickOne (3)
.fi