.\" @(#)PEXBeginPickOne.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXBeginPickOne 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXBeginPickOne \- Begin Renderer Pick One
.SH SYNTAX
.HP
void PEXBeginPickOne\^(\^Display *\fIdisplay\fP\^, Drawable \fIdrawable\fP\^, PEXRenderer \fIrenderer\fP\^, long \fIstructure_id\fP\^, int \fImethod\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 one method (
.B PEXPickLast, 
.B PEXPickClosestZ,
.B PEXPickVisibleAny,
.B PEXPickVisibleClosest
).
.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 PEXBeginPickOne
.IX "Picking" "PEXBeginPickOne"
.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.
For pick one, a hierarchical path to the picked
primitive will be maintained.
.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) .
The specified structure identifier will be inserted as the first structure
component in the returned pick path.
.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 PEXBeginPickOne
function is completed, and a
.SB BadPEXRendererState
error is sent.
.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.
.bp
.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;
.fi
.SH ERRORS
.TP
.SB BadAlloc
The server failed to allocate resources necessary to complete request.
.TP
.SB BadDrawable
The specified
.I drawable
resource identifier is invalid.
.TP
.SB BadMatch
The specified
.I drawable
is unsupported, or the specified renderer resource was
not created with a compatible drawable.
.bp
.TP
.SB BadPEXRenderer
The specified
.I renderer
resource identifier is invalid.
.TP
.SB BadPEXRendererState
The specified
.I 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 PEXEndPickOne (3)
.BR PEXPickOne (3)
.fi