PEXEndPickOne(3) — Subroutines

Name

PEXEndPickOne - End Pick One

Synopsis

PEXPickPath ∗PEXEndPickOne(Display ∗display, PEXRenderer renderer, int ∗status_return, int ∗undetectable_return)

Arguments

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

rendererThe resource identifier of the renderer.

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 terminates an immediate-mode pick, returns the hierarchical pick path to the closest or last hit primitive, and sets the renderer state to PEXIdle.

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 renderer state is currently PEXIdle when this function is called, (i.e., no picking is in progress or the rendering was aborted due to a resize), the function is ignored and no error is generated. If the renderer state is currently PEXRendering or if the pick operation in progress is a "pick all", then 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 struct {
    unsigned long       count;
    PEXPickElementRef   ∗elements;
} PEXPickPath;
typedef struct {
    PEXStructure        sid;
    unsigned long       offset;
    unsigned long       pick_id;
} PEXPickElementRef;
typedef XID             PEXStructure;

Errors

BadPEXRenderer
The specified renderer resource identifier is invalid.

BadPEXRendererState
The specified renderer was in an invalid state.

Museum