PEXEndPickAll(3) — Subroutines

Name

PEXEndPickAll - End Pick All

Synopsis

PEXPickPath ∗PEXEndPickAll(Display ∗display, PEXRenderer renderer, int ∗status_return, int ∗more_return, unsigned long ∗count_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.

more_returnReturns the status of remaining picks.

count_returnReturns the number of pick paths.

Returns

An array of pick paths; a null pointer if unsuccessful or no pick (see also status_return).

Description

This function terminates an immediate-mode pick, returns the hierarchical pick paths of any hit primitives, and sets the renderer state to PEXIdle.

If one or more primitives were picked, a pick status of PEXPick is returned along with the pick paths. The hierarchical pick path is equivalent to the renderer’s current path at the time the picked primitive was processed. If no primitives were picked, the returned pick status is PEXNoPick, and the returned pick paths 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 paths is a null pointer.

If all hits were recorded then PEXNoMoreHits is returned and the renderer’s pick start path will be empty. If the maximum number of hits was reached and additional hits were detected, then PEXMoreHits is returned and the renderer’s pick start path will be set to the last recorded hit primitive. If, after reaching the maximum number of hits, subsequent output commands were ignored, then PEXMayBeMoreHits is returned and the renderer’s pick start path is set to the last element processed by the renderer before it started ignoring primitives.

If the renderer state is 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 one", 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