.\" @(#)PEXBeginPickAll.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXBeginPickAll 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXBeginPickAll \- Begin Renderer Pick All
.SH SYNTAX
.HP
void PEXBeginPickAll\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\fP\^, long \fIstructure_id\fP\^, int \fImethod\fP\^, int \fIsend_event\fP\^, int \fImax_hits\fP\^, int \fIpick_device_type\fP\^, PEXPickRecord *\fIpick_record\fP\^)
.SH PARAMETERS
.TP 1i
\fIdisplay\fP
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.TP
\fIdrawable\fP
The resource identifier of a drawable.
.TP
\fIrenderer\fP
The resource identifier of the renderer.
.TP
\fIstructure_id\fP
A value to be used as the structure identifier for the root of the
structure network.
.TP
\fImethod\fP
The pick all method (
.B PEXPickAllAll
or
.B PEXPickAllVisible
).
.TP
\fIsend_event\fP
.SB TRUE
or
.SB FALSE
\(em specifying whether the server should send an
event when the maximum number of hits is reached.
.TP
\fImax_hits\fP
The maximum number of hits to be returned.
.TP
\fIpick_device_type\fP
The pick device type (
.B PEXPickDeviceDCHitBox
or
.B PEXPickDeviceNPCHitVolume
).
.TP
\fIpick_record\fP
A pointer to the pick data record.
.SH RETURNS
None
.SH DESCRIPTION
.\" indexing
.IX PEXBeginPickAll
.IX "Picking" "PEXBeginPickAll"
.LP
This functions starts an immediate-mode pick, setting the renderer's renderer
state to
.B PEXPicking.
When the renderer state is
.B PEXPicking,
primitives are hit
tested instead of converted to pixels.
All picked primitives are
recorded until reaching the maximum hits specified is reached.
Additional picked primitives will not be recorded.  Once the
the maximum number of hits is reached, subsequent primitives may be
ignored.
.LP
The supported pick device types are inquirable via
.BR PEXGetEnumTypeInfo (3) .
The specified structure identifier will be inserted as the first structure
component in the returned pick path(s).
.LP
If the
.I send_event
flag is
.SB True,
and the pick
.I method
is
.B PEXPickAllAll,
then a
.B PEXMaxHitsReached
event is sent from the server to the client whenever the maximum number of
hits is reached by the server,
if the event is supported (see
.BR PEXGetImpDepConstants (3)
).  Upon receiving the event, the application should stop sending primitives
and process the recorded hits.
If the pick
.I method
is
.B PEXPickAllVisible,
a complete set of primitives must be sent to the server before determining
which primitives are picked.
.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
.BR PEXMatchRenderingTargets (3) ,
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 PEXBeginPickAll
function is completed, and a
.SB BadPEXRendererState
error returned.
.LP
All functions which process output commands or manipulate attributes (i.e. all
output command functions,
.BR PEXBeginStructure (3) ,
.BR PEXEndStructure (3) ,
.BR PEXRenderElements (3) ,
and
.BR PEXAccumulateState (3)
) can be called when the renderer state is
.B PEXPicking.
They will have the same semantics except that primitives are hit tested instead
of converted to pixels.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXRenderer;
.sp
typedef union {
	PEXPDNPCHitVolume		volume;
	PEXPDDCHitBox			box;
	PEXPickDataRecord		data;
.br
} PEXPickRecord;
.sp
typedef PEXNPCSubVolume	PEXPDNPCHitVolume;
.sp .5
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;
.bp
typedef struct {
	int				type;
	unsigned long		serial;		/* # of last request processed by server */
	Bool				send_event;	/* true if this came from a SendEvent request */
	Display			*display;		/* Display the event was read from */
	PEXRenderer		renderer;
.br
} PEXMaxHitsReachedEvent;
.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 BadValue
The pick record contains invalid data, or the pick device type is invalid.
.SH SEE ALSO
.nf
.BR PEXEndPickAll (3)
.BR PEXPickAll (3)
.BR PEXGetImpDepConstants (3)
.fi