PEXPickAll - Pick All Traversal (5.1)

Synopsis

 
   PEXPickPath *PEXPickAll(
         Display *display,
         Drawable drawable,
         PEXRenderer renderer,
         int method,
         int max_hits,
         int pick_device_type,
         PEXPickRecord *pick_record,
         int *status_return,
         int *more_return,
         unsigned long *count_return
   )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
drawable: The resource identifier of a drawable.
renderer: The resource identifier of the renderer
method: The pick all method (PEXPickAllAll or PEXPickAllVisible).
max_hits: The maximum number of hits to be returned.
pick_device_type: The pick device type (PEXPickDeviceDCHitBox or PEXPickDeviceNPCHitVolume).
pick_record: A pointer to the pick data record.
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 PEXPickAll to traverse the structure network specified by the renderer's current pick start path.

Hit testing begins after the last element specified in the renderer's current pick start path and continues until one of two conditions is met: the specified maximum number of hits is reached, or the last element of the first structure in the pick start path is processed. If the pick start path does not define a valid hierarchical path, then the implementation issues a BadPEXPath error and returns a null pick path. Invoke PEXCreateRendererWithExtAttributes or PEXChangeRendererExtAttributes to initialize the renderer's current pick start path.

PEXlib defines the following pick all methods:

PEXPickAllAll -: Returns the primitives, up the maximum number of hits, which lie within or intersect the hit box.
PEXPickAllVisible -: Returns the primitives visible (taking into account the current HLHSR mode), up to the maximum number of hits, and that lie within or intersect the hit box.

Inquire the supported pick device types by invoking the PEXGetEnumTypeInfo function.

If one or more primitives were picked, then 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, 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.

The paths of all hit primitives are recorded until reaching the maximum number of hits or until the implementation maximum number of recordable hits is reached. Once the maximum number of paths is recorded, the implementation may ignore subsequent primitives and return the results.

If all possible 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 in 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 specified drawable does not have the same root and depth as the drawable used to create the renderer, or, if the specified drawable is not one of the supported drawables, then the implementation issues a BadMatch error. To determine the supported drawables, invoke the PEXMatchRenderingTargets function. If the renderer state is set to PEXRendering or PEXPicking when you invoke this function, then the operation in progress is aborted, the PEXPickAll function is completed, and the implementation issues a BadPEXRendererState error.

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

Errors