NAME

pick_items - Pick a number of objects based on a screen-space coordinate.

SYNOPSIS

vidtbl:results
pick_items( number:x, number:y )
pick_items( number:x, number:y, number:limit=8 )
pick_items( number:x, number:y, number:limit=8 )
pick_items( number:x, number:y, number:limit=8<=64, bool:reverse=false )
pick_items( number:x, number:y, number:limit=8<=64, bool:reverse=false, vid:rtgt=WORLDID )

DESCRIPTION

pick_items is a low level function for building user-interface related picking tools. It takes a screen- or rendertarget- space coordinate and sweeps through the pipeline based on their render order (see order_image ). If reverse is provided it will sweep from high to low, otherwise from low to high. It will early out once limit objects have been found. It will always return an integer indexed table of zero to limit number of VID s. Limit is not allowed to exceed 64.

NOTES

1

All VID s start out as eligible for picking. This can be controlled by setting the MASK_UNPICKABLE mask, see image_mask_set . This mask value is not inherited by default through linking. This means it needs to be set for each new object regardless of how link_image is being used.

2

Clipping and alpha channel is ignored and will need to be considered manually by testing against any possible clipping parents.

3

This function can be very costly based on the complexity of the scene and some caching mechanism should be used if a high number of calls is expected, for instance when tied to a touch or mouse- input device event handler.

4

The cost progression is roughly (low to high) normal, rotated, linked, 3d object, rotated-linked, rotated-linked-3d object.

5

If an object is shader displayed or manually manipulated by skewing vertices through image_tesselation or a vertex stage shader, the picking operation result is undefined.

SEE ALSO:

image_hit(3)