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)
 

Detailed Description

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.

RESTRICTIONS

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