Compute_Selection

Functions

int Compute_Selection (const char *display, const char *start_seg, const char *action, double x, double y)
 Forces the explicit computation and generation of selection events. More...
 
int Compute_Selection_By_Area (const char *display, const char *start_seg, const char *action, double left, double right, double bottom, double top)
 Similar to Compute_Selection(), but operates on a rectangular area. More...
 
int Compute_Selection_By_Polygon (const char *display, const char *start_seg, const char *action, int pcount, const HC_POINT *points)
 Similar to Compute_Selection(), but operates on a polygonal area. More...
 
int Compute_Selection_By_Polylin (const char *display, const char *start_seg, const char *action, int pcount, const HC_POINT *points)
 Similar to Compute_Selection(), but operates on polyline intersections. More...
 
int Compute_Selection_By_Volume (const char *display, const char *start_seg, const char *action, double left, double right, double bottom, double top, double hither, double yon)
 Similar to Compute_Selection(), but operates on a cuboid volume. More...
 

Detailed Description

Function Documentation

◆ Compute_Selection()

int Compute_Selection ( const char *  display,
const char *  start_seg,
const char *  action,
double  x,
double  y 
)

Forces the explicit computation and generation of selection events.

Parameters
display- Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections.
start_seg- A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action- One of "v", "^", "*", or "O", as well as "conditions", i.e., "v, conditions=my_condition". Action is compared against the Selectability attribute settings as testing proceeds. See details for a discussion on actions.
x- The nominal mouse x-position, measured in window coordinates: -1.0 to +1.0. If start-seg is non-blank, then the parameter is taken in terms of the window in effect on start-seg, otherwise in terms of display.
y- The nominal mouse y-position
Returns
count

DETAILS

Compute_Selection() allows access to the internal routines used for figuring selection events from mouse locations. Given the usual locater information, Compute_Selection() will observe the appropriate attributes and find out what lies at that position. If anything is found, a Selection Event is generated and is made the "current" event. Any previous current event is discarded. The various Show_Selection() routines can then be used to retrieve information about the selection.

If a value for start_seg is given, then testing begins there. Coordinates are measured in terms of that segment's effective window, and testing is restricted to that window.

The available values for actions are detailed in Set_Selectability(). You can also specify conditions for selections with the "conditions" option. For example, if you were viewing a model of a car, you could define a conditional attribute setting called "show_wheels" that makes all wheels in a scene visible, and activate it for only this selection using Compute_Selection("?Picture", ".", "v, conditions = show_wheels", 0, 0) .

Additionally, you can set Driver Options and Heuristics which pertain to selection. These values will override the settings on the segment for this selection event. Currently this is the selection proximity Driver Option and the selection level, visual selection, detail selection, selection sorting, related selection limit and internal selection limit which can be found in Set_Heuristics. See the documentation of Set_Driver_Options and Set_Heuristics for specific details on each of these options.

Compute_Selection_By_Area() lets you specify a rectangular region of the screen instead of a single point. Every item of geometry within or overlapping that region is identified and returned as part of the selection event. The "selection proximity" Driver Option is ignored in the case of testing "by area", since the geometry must be properly within or overlapping the specified region. Everything within the area has equal status.

A typical programming sequence that computes a selection and does something with every one of the selected items follows (in pseudo-C):

                if (Compute_Selection_By_Area (...) > 0) do {
                        Show_Selection_Element (...) 
                        /*... process item... */
                } while (Find_Related_Selection())
                

As with regular selection events, the "related" selections are returned in proximity order. If the proximities are zero (the position is within the item). The related sections are in front-to-back order. For "by area" selecting, the ordering is from the approximate center of the area.
Compute_Selection_By_Volume() lets you specify a volume of the screen. The meaning of "screen Z" coordinates is described in detail under Show_Selection_Position() . Hither must be less than or equal to yon. If display is given as blank or null, an "object space" test is done, as described below. Similar to Compute_Selection_By_Area() , Compute_Selection_By_Polylin() lets you specify a polyline. Any object intersected by the path of the polyline is selected. The points that define the polyline have their X and Y values defined in window coordinates. The Z values are ignored.

Compute_Selection_By_Polygon() lets you specify a polygon instead of a polyline. Every item of geometry, within or overlapping the region defined by the polygon, is identified and returned as part of the selection event. The points that define the polygon have their X and Y values defined in window coordinates. The Z values are ignored.

Compute_Selection_By_Volume() does its selection in "object space". The idea of an object-space test is to search a certain volume of space without reference to any screen display. In particular:

  • Only Compute_Selection_By_Volume() and Compute_Selection_By_Shell() permit this mode.
  • All input values (left, right, point etc.) must be in terms of start_seg's coordinate system—the coordinate system used for defining geometry within start_seg.
  • Returned values (see Show_Selection_Position() ) will be in that coordinate system. Windowed inner segments in start_seg are skipped over.
  • Cameras attached to inner segments are warned about (unless they are skipped because of the "windowed inner segment" rule).
  • The hidden-surface front-to-back ordering is not meaningful. Items are returned (see Show_Selection() and Find_Related_Selection() ) in the order they are encountered in the database.
  • Inner modelling matrices are respected. The values returned by Show_Selection_Position() remain in terms of start_seg's coordinate system.


NOTES

The status returned by Show_Selection_Source() will be a one if action was "v" or "*", otherwise zero.

Selectability and visibility are enforced during a Compute_Selection() just as they are during normal user input. An object must be both visible and selectable to be selected. The "attribute lock" rendering option might be useful for overriding these.

In the current implementation, display, if given, has to be a real driver segment. There are, however, ways to get around this. Selecting works if the window visibility for display itself is turned off. Alternatively, a debugging driver—"?driverprintf/null"—can be used for display (the "?driver/null" driver cannot do selection testing.) If you do use "printf/null", the "physical size" Driver Option might be useful to get the nominal shape of the screen right.

In the current implementation, if a blank or null start_seg is given to Compute_Selection_By_Area() (so that window-selecting is turned on), then at most one window selected—the window in effect for the center of the area. Geometry testing will be limited to that one window.

In the current implementation, the selection-testing code can include a geometry item even if the item is completely covered up by a polygon closer to the camera. For example—if the item doesn't know how to tell that the geometry is actually invisible. (Note the closer polygon will be returned first.) Likewise, once the testing code decides the action is within a particular window it becomes oblivious to extraneous windows that may overlap some of the geometry.

Compute_Selection() always makes its result the "current" event. To take advantage of having a queue of events, you could use Queue_Location_Event() to save the information. Then do Compute_Selection() when you see the Location event coming off the queue.

Compute_Selection_By_Area() typically requires first letting the user rubberband a bounding box into position. The bounding box is conveniently done in a subsegment that has a viewing camera such as

Set_Camera_By_Volume ("stretched", -1., 1., -1., 1.)

This makes the geometry coordinate system the same as the window coordinate system. (The "quick moves" Heuristic can also be useful for rubberbanding.)
Once you have called Compute_Selection(), you can iterate through the list of selected objects via Find_Related_Selection(). Note that the returned selected objects are sorted by z-order for direct hits (objects that were directly under the selection ray calculated from the position camera and the hit point) followed by objects that were not in the path of the ray but were within the "selection proximity" of the ray and that these are sorted by their proximity to the ray.

RESTRICTIONS

The start_seg parameter must not be an included segment.

See also
Begin_Shell_Selection, Compute_Coordinates, Get_Selection, Find_Related_Selection, Set_Selectability, Set_Visibility, Set_Driver_Options, Show_Selection_Pathname, Set_Heuristics.

◆ Compute_Selection_By_Area()

int Compute_Selection_By_Area ( const char *  display,
const char *  start_seg,
const char *  action,
double  left,
double  right,
double  bottom,
double  top 
)

Similar to Compute_Selection(), but operates on a rectangular area.

Parameters
display- Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections.
start_seg- A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action- One of "v", "^", "*", or "O", as well as "conditions", i.e., "v, conditions=my_condition". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
left- The -(x) boundary for a rectangular area of the screen, in window coordinates
right- The (x) boundary for a rectangular area of the screen, in window coordinates
bottom- The -(y) boundary for a rectangular area of the screen, in window coordinates
top- The (y) boundary for a rectangular area of the screen, in window coordinates
Returns
count

DETAILS

No additional details. See Compute_Selection()

RESTRICTIONS

The start_seg parameter must not be an included segment.

◆ Compute_Selection_By_Polygon()

int Compute_Selection_By_Polygon ( const char *  display,
const char *  start_seg,
const char *  action,
int  pcount,
const HC_POINT *  points 
)

Similar to Compute_Selection(), but operates on a polygonal area.

Parameters
display- Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections.
start_seg- A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action- One of "v", "^", "*", or "O", as well as "conditions", i.e., "v, conditions=my_condition". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
pcount- Number of points contained in the points list.
points- Set of points that comprise the polyline or polygon used to compute the selection.
Returns
count

DETAILS

No additional details. See Compute_Selection()

RESTRICTIONS

The start_seg parameter must not be an included segment.

◆ Compute_Selection_By_Polylin()

int Compute_Selection_By_Polylin ( const char *  display,
const char *  start_seg,
const char *  action,
int  pcount,
const HC_POINT *  points 
)

Similar to Compute_Selection(), but operates on polyline intersections.

Parameters
display- Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections.
start_seg- A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action- One of "v", "^", "*", or "O", as well as "conditions", i.e., "v, conditions=my_condition". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
pcount- Number of points contained in the points list.
points- Set of points that comprise the polyline or polygon used to compute the selection.
Returns
count

DETAILS

No additional details. See Compute_Selection()

RESTRICTIONS

The start_seg parameter must not be an included segment.

◆ Compute_Selection_By_Volume()

int Compute_Selection_By_Volume ( const char *  display,
const char *  start_seg,
const char *  action,
double  left,
double  right,
double  bottom,
double  top,
double  hither,
double  yon 
)

Similar to Compute_Selection(), but operates on a cuboid volume.

Parameters
display- Commonly "?Picture". In general, a segment with an attached device driver that knows how to test for selections. If blank or null, then an "object space selection" is made (see below.)
start_seg- A segment somewhere in the tree belonging to display, at which point it would be good to start selection testing. If blank or null, then testing begins at display.
action- One of "v", "^", "*", or "O", as well as "conditions", i.e., "v, conditions=my_condition". Action is compared against the Selectability attribute settings as testing proceeds. See Set_Selectability() for a detailed explanation of actions.
left- The -(x) boundary for a rectangular area of the screen, in window coordinates
right- The (x) boundary for a rectangular area of the screen, in window coordinates
bottom- The -(y) boundary for a rectangular area of the screen, in window coordinates
top- The (y) boundary for a rectangular area of the screen, in window coordinates
hither- The -(z) boundary, described in Show_Selection_Position() .
yon- The (z) boundary, described in Show_Selection_Position() .
Returns
found

DETAILS

No additional details. See Compute_Selection()

RESTRICTIONS