PEXBeginPickOne(3) — Subroutines

Name

PEXBeginPickOne - Begin Renderer Pick One

Synopsis

void PEXBeginPickOne(Display ∗display, Drawable drawable, PEXRenderer renderer, long structure_id, int method, int pick_device_type, PEXPickRecord ∗pick_record)

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.

structure_idA value to be used as the structure identifier for the root 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.

Returns

None

Description

This functions starts an immediate-mode pick, setting the renderer’s renderer state to PEXPicking. When the renderer state is PEXPicking, primitives will be hit tested instead of converted to pixels. For "pick one", a hierarchical path to the picked primitive will be maintained.

Standard "pick one" methods are PEXPickLast, PEXPickClosestZ, PEXPickVisibleAny and PEXPickVisibleClosest. The supported pick device types are inquirable via PEXGetEnumTypeInfo. The specified structure identifier will be inserted as the first structure component in the returned pick path.

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 PEXBeginPickOne function is completed, and a BadPEXRendererState error is sent.

All functions which process output commands or manipulate attributes (i.e. all output command functions, PEXBeginStructure, PEXEndStructure, PEXRenderElements, and PEXAccumulateState) can be called when the renderer state is PEXPicking. They will have the same semantics except that primitives are hit tested instead of converted to pixels.

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;

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.

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

Museum