PEXEndPickAll - End Pick All (5.1)

Synopsis

 
    PEXPickPath *PEXEndPickAll(
          Display *display,
          PEXRenderer renderer,
          int *status_return,
          int *more_return,
          unsigned long *count_return
   )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
renderer: The resource identifier of the renderer.
status_return: Returns the status of the pick operation (PEXPick, PEXNoPick or PEXAbortedPick).
more_return: Returns the status of remaining picks (PEXNoMoreHits, PEXMoreHits or PEXMayBeMoreHits).
count_return: Returns the number of pick paths.

Returns

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

Description

Invoke PEXEndPickAll to terminate an immediate-mode pick, get the hierarchical pick paths of any hit primitives, and set the renderer state to PEXIdle.

If one or more primitives were picked, then this function returns a pick status of PEXPick 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, then 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, then the returned pick status is PEXAbortedPick and the returned pick paths is a null pointer.

The element positions of picked primitives in locked structures are undefined.

If all hits were recorded, then PEXNoMoreHits is returned and the renderer's pick start path is 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 is 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 picked element is a locked structure, then the pick start path is set to the first structure referencing output command after the picked primitive, or to the output command referencing the locked structure if there are no subsequent structure referencing output commands in the locked structure.

If the renderer state is PEXIdle when you invoke this function (i.e., no picking is in progress or the rendering was aborted due to a resize), then the implementation ignores this function and does not issue any errors. If the renderer state is currently PEXRendering or PEXMultipassRendering, or if the pick operation in progress is a pick one, then the implementation issues a BadPEXRendererState error and does not change the renderer's renderer state.

PEXlib allocates memory for the return value. Invoke PEXFreePickPaths to deallocate the memory.

Errors