.\" @(#)PEXPickAll.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXPickAll 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXPickAll - Pick All Traversal
.SH SYNTAX
.HP
PEXPickPath *PEXPickAll\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\fP\^, int \fImethod\fP\^, int \fImax_hits\fP\^, int \fIpick_device_type\fP\^, PEXPickRecord *\fIpick_record\fP\^, int *\fIstatus_return\fP\^, int *\fImore_return\fP\^, unsigned long *\fIcount_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 \fImethod\fP 1i
The pick all method (
.B PEXPickAllAll
or
.B PEXPickAllVisible
).
.IP \fImax_hits\fP 1i
The maximum number of hits to be returned.
.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 \fImore_return\fP 1i
Returns the status of remaining picks.
.IP \fIcount_return\fP 1i
Returns the number of pick paths.
.SH RETURNS
.LP
An array of pick paths; a null pointer if unsuccessful or no pick
(see also
.I status_return).
.SH DESCRIPTION
.\" indexing
.IX PEXPickAll
.IX "Picking" "PEXPickAll"
.LP
This function traverses the structure network specified
by the renderer's current pick start path.
Hit testing begins after the last element specified in the renderer's current
pick start path and continues until one of two conditions is met:  the maximum
number of hits is reached, or the last element of the first structure in the
pick start path is processed.
If the pick start path
does not define a valid hierarchical path, a
.SB BadPEXPath
error is sent and a null pick path is returned.
.LP
Standard pick all methods are
.B PEXPickAllAll
and
.B PEXPickAllVisible.
The supported pick device types are inquirable via
.BR PEXGetEnumTypeInfo (3).
.LP
If one or more primitives were picked, a pick status of
.B PEXPick
is returned along with the pick paths.  The hierarchical pick path is
equivalent to the renderer's current path at the time the picked primitive
was processed.
If no primitives were picked, the returned pick status is
.B PEXNoPick,
and the returned pick path is a null pointer.  If the renderer's 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
The paths of all hit primitives are recorded until reaching the maximum
number of hits or until the server maximum number of recordable hits is
reached.  Once the maximum number
of paths is recorded, subsequent primitives may be ignored and the results
returned.
.LP
If all possible hits were recorded, then
.B PEXNoMoreHits
is returned
and the renderer's pick start path will be empty.
If the maximum number of hits was reached and additional
hits were detected, then
.B PEXMoreHits
is returned and the renderer's pick start path will be set to the last
recorded hit primitive.
If, after reaching the maximum number of hits,
subsequent output commands were ignored,
then
.B PEXMayBeMoreHits
is returned and the renderer's pick start path
will be set to the last element processed by the renderer before
it started ignoring primitives.
.LP
If the specified drawable does not have the same root and depth as
the drawable used to create the renderer, or, if the
specified drawable is not one of the supported drawables returned
by
.B PEXMatchRenderingTargets ,
a match error is 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 PEXPickAll
function is completed, and a
.SB BadPEXRendererState
error returned.
.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 BadPEXPath
The renderer pick start path is invalid.
.TP
.SB BadValue
The pick record contains invalid data, or the pick device type is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXBeginPickAll (3)
.BR PEXEndPickAll (3)
.BR PEXFreePickPaths (3)
.fi