Brief Index      Full Index      Events Index      I.M. Reference

Begin_Buffered_Selection


Functions

int Begin_Buffered_Selection (const char *start_name, double left, double right, double bottom, double top, const char *options)

Function Documentation

int Begin_Buffered_Selection ( const char *  start_name,
double  left,
double  right,
double  bottom,
double  top,
const char *  options 
)

Prepares HOOPS for the buffered selection process and allows the valid selection area (typically, the entire window) to be specified.

Parameters:
start_name - The fully-qualified name of a window segment.
left - The left bound of the valid selection area, in window coordinates.
right - The left bound of the valid selection area, in window coordinates.
bottom - The left bound of the valid selection area, in window coordinates.
top - The left bound of the valid selection area, in window coordinates.
options - A quoted string or a string variable containing a list of desired options. Passed by reference always.
Returns:
This will currently always be 0, and is not currently used.

DETAILS

HOOPS supports a selection process called 'buffered selection' which instructs HOOPS to redraw the area of the scene specified by the left/right/bottom/top into an offscreen selection buffer, and is subsequently queried using Collect_Area_Samples. That buffer is left intact for query until End_Buffered_Selection is called. This selection approach allows the user to only select on what is current visible in the scene, and leverages the hardware-accelerated capabilities of specific 3D HOOPS drivers.

In addition to providing a way of only selecting on what's visible, buffered selection can provide a performance boost for situations where you need to perform multiple selections in a row. For example, perhaps you need to query or highlight/dehighlight multiple times on a scene which is not getting edited/redrawn between each selection.

A typical flow of buffered selection is as follows:

  • call Begin_Buffered_Selection (this performs a full update of the scene into the offscreen selection buffer)
  • call Collect_Area_Samples to determine the number of items that lie in the selection area specified by the user
  • call Find_Next_Sample to iterate through the list of samples and obtain information about each found item
  • call End_Buffered_Selection to complete the buffered selection process

During the process of redrawing the scene into the selection buffer:

  • all regular draw optimizations are active, such as honoring segment/shell/mesh bounding-volumes

NOTES

A call to Begin_Buffered_Selection must always be matched with a call to End_Buffered_Selection, and calls to Collect_Area_Samples and Find_Next_Sample should only be called in between. If Begin_Buffered_Selection is called and the scene is then edited in some way (the camera is moved, objects are deleted/edited, attributes are changed, etc...), and Collect_Area_Samples is then called to perform a selection query into the buffer, the buffer is 'out of date' and results would be unexpected/invalid.

Buffered selections is only supported when using the OpenGL2 and DX11 drivers.

See also:
End_Buffered_Selection, Collect_Area_Samples, Find_Next_Sample, Show_Sample_Max_Length

Brief Index      Full Index      Events Index      I.M. Reference