PEXPickOne(3) — Subroutines

Name

PEXPickOne - Pick One Traversal

Synopsis

PEXPickPath ∗PEXPickOne(Display ∗display, Drawable drawable, PEXRenderer renderer, PEXStructure structure, int method, int pick_device_type, PEXPickRecord ∗pick_record, int ∗status_return, int ∗undetectable_return)

Arguments

displayA pointer to a display structure returned by a successful XOpenDisplay call.

drawableThe resource identifier of a drawable.

rendererThe resource identifier of the renderer.

structureThe resource identifier for the root structure of the structure network.

methodThe pick one method (PEXPickLast, PEXPickClosestZ, PEXPickVisibleAny PEXPickVisibleClosest).

pick_device_type
The pick device type (PEXPickDeviceDCHitBox or PEXPickDeviceNPCHitVolume).

pick_recordA pointer to the pick data record.

status_return
Returns the status of the pick operation.

undetectable_return
Returns True or False indicating whether another pick better satisfied the pick criteria with the exception that it did not pass the pick filter test.

Returns

A pointer to the pick path; a null pointer if unsuccessful or no pick (see also status_return).

Description

This function traverses the specified structure network.

Standard "pick one" methods are PEXPickLast, PEXPickClosestZ, PEXPickVisibleAny and PEXPickVisibleClosest. The supported pick device types are inquirable via PEXGetEnumTypeInfo.

If a primitive was picked, the returned pick status is PEXPick. If no primitive was picked, the returned pick status is 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 PEXAbortedPick and the returned pick path is a null pointer.

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 True. Otherwise, it will be False.

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 PEXMatchRenderingTargets, a Match error will be generated. If the renderer state is set to PEXRendering or PEXPicking when this function is called, then the operation in progress is aborted, the PEXPickOne function is completed, and a BadPEXRendererState error is sent.

PEXlib allocates memory for the return value. PEXFreePickPaths should be called to deallocate the memory.

Data Structures

typedef XID             PEXRenderer;
typedef union {
    PEXPDNPCHitVolume       volume;
    PEXPDDCHitBox           box;
    PEXPickDataRecord       data;
} PEXPickRecord;
typedef PEXNPCSubVolume PEXPDNPCHitVolume;
typedef struct {
    PEXCoord            min;
    PEXCoord            max;
} PEXNPCSubVolume;
typedef struct {
    float               x;
    float               y;
    float               z;
} PEXCoord;
typedef struct {
    PEXDeviceCoord2D    position;
    float               distance;
} PEXPDDCHitBox;
typedef struct {
    short               x;
    short               y;
} PEXDeviceCoord2D;
typedef struct {
    unsigned short      length;
    char                ∗record;
} PEXPickDataRecord;
typedef struct {
    unsigned long       count;
    PEXPickElementRef   ∗elements;
} PEXPickPath;
typedef struct {
    PEXStructure        sid;
    unsigned long       offset;
    unsigned long       pick_id;
} PEXPickElementRef;
typedef XID             PEXStructure;

Errors

BadAllocThe server failed to allocate resources necessary to complete request.

BadDrawableThe specified drawable resource identifier is invalid.

BadMatchThe specified drawable is unsupported, or the specified renderer resource was not created with a compatible drawable.

BadPEXRenderer
The specified renderer resource identifier is invalid.

BadPEXRendererState
The specified renderer was in an invalid state.

BadPEXStructure
The specified structure resource identifier is invalid.

BadValueThe pick record contains invalid data, or the pick device type is invalid.

Museum