PEXPickOne - Pick One Traversal (5.1)

Synopsis

 
    PEXPickPath *PEXPickOne(
          Display *display,
          Drawable drawable,
          PEXRenderer renderer,
          PEXStructure structure,
          int method,
          int pick_device_type,
          PEXPickRecord *pick_record,
          int *status_return,
          int *undetectable_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.
structure: The resource identifier for the root structure of the structure network.
method: The pick one method (PEXPickLast, PEXPickClosestZ, PEXPickVisibleAny or PEXPickVisibleClosest).
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).
undetectable_return: Returns True if another primitive better satisfies 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

Invoke PEXPickOne to traverse the specified structure network.

PEXlib defines the following pick one methods:

PEXPickLast -: Returns the last "hit" primitive which satisfies the pick filter test.
PEXPickClosestZ -: Returns the "hit" primitive which has a z value closest to the front clipping plane and satisfies the pick filter test. If multiple primitives satisfy this criteria, any of them may be returned.
PEXPickVisibleAny -: Returns some "hit" primitive which is visible (taking the current HLHSR mode into account) and satisfies the pick filter test.
PEXPickVisibleClosest -: All "hit" primitives which are visible are selected. Of those selected, the one which is closest to the pick position and satisfies the pick filter test is returned. If you specify an NPC pick volume, then the pick position is the center of the volume.

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

If a primitive was picked, then the returned pick status is PEXPick. If no primitive was picked, then 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, then 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 is True. Otherwise, it is False.

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, 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 PEXPickOne function is completed, and the implementation issues a BadPEXRendererState error.

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

Errors