.\" @(#)PEXGetPickDevice.3 1.5 95/03/24 SMI;
.so man3/pex.macs
.TH PEXGetPickDevice 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXGetPickDevice - Get Pick Device Attributes
.SH SYNTAX
.HP
PEXPDAttributes *PEXGetPickDevice\^(\^Display *\fIdisplay\fP\^, PEXWorkstation \fIworkstation\fP\^, int \fIpick_device_type\fP\^, unsigned long \fIvalue_mask\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 \fIpick_device_type\fP 1i
The pick device type (
.B PEXPickDeviceDCHitBox
or
.B PEXPickDeviceNPCHitVolume
).
.IP \fIvalue_mask\fP 1i
A mask indicating which attributes to return.
.SH RETURNS
.LP
A pointer to the pick device attribute values; a null pointer if unsuccessful.
.SH DESCRIPTION
.\" indexing
.IX PEXGetPickDevice
.IX "Picking" "PEXGetPickDevice"
.LP
This function returns the attribute values of a pick descriptor for the
PHIGS
workstation resource specified.  The descriptor returned will be the
currently-defined descriptor for the pick device of the type specified.
Supported pick device types are inquirable via
.BR PEXGetEnumTypeInfo (3) .
The value mask indicates which attributes are to be returned.
The value mask is constructed by OR'ing together the following constants:
.LP
.RS
.nf
.B PEXPDEchoSwitch
.B PEXPDEchoVolume
.B PEXPDPickDataRec
.B PEXPDPickExcl
.B PEXPDPickIncl
.B PEXPDPickPath
.B PEXPDPickPathOrder
.B PEXPDPickStatus
.B PEXPDPromptEchoType
.RE
.fi
.LP
PEXlib allocates memory for the return value.
.BR PEXFreePDAttributes (3)
should be called to deallocate the memory.
.SH DATA STRUCTURES
.LP
.nf
typedef  XID	PEXWorkstation;
.sp
typedef struct {
	unsigned short		status;
	PEXPickPath		path;
	int			path_order;
	PEXNameSet		inclusion;
	PEXNameSet		exclusion;
	PEXPickRecord		pick_record;
	PEXEnumTypeIndex	prompt_echo_type;
	PEXViewport		echo_volume;
	int			echo_switch;
.br
} PEXPDAttributes;
.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;
.sp .5
typedef  XID	PEXNameSet;
.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;
.sp
typedef  short	PEXEnumTypeIndex;
.sp .5
typedef struct {
	PEXDeviceCoord		min;
	PEXDeviceCoord		max;
	PEXSwitch			use_drawable;
	unsigned char			reserved[3];
.br
} PEXViewport;
.sp
typedef struct {
	short	x;
	short	y;
	float	z;
.br
} PEXDeviceCoord;
.sp
typedef  unsigned char	PEXSwitch;
.fi
.SH ERRORS
.TP
.SB BadPEXWorkstation
The specified workstation resource identifier is invalid.
.TP
.SB BadValue
The specified pick device type is invalid, or an invalid bit set in the value
mask.
.SH SEE ALSO
.LP
.nf
.BR PEXChangePickDevice (3)
.BR PEXGetEnumTypeInfo (3)
.fi