com.openinventor.inventor.nodes

Class SoExtSelection

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.misc.SoBase

com.openinventor.inventor.fields.SoFieldContainer

com.openinventor.inventor.nodes.SoNode

com.openinventor.inventor.nodes.SoGroup

com.openinventor.inventor.nodes.SoSeparator

com.openinventor.inventor.nodes.SoSelection

com.openinventor.inventor.nodes.SoExtSelection

All Implemented Interfaces:

SafeDisposable

public class SoExtSelection
extends SoSelection

Selection node that supports lasso selection. This class extends the functionality of SoSelection to allow the user to select an object or multiple objects by drawing a lasso around the object(s) to be selected. The lasso can be represented as a rectangle between the mouse up and down positions or as a set of lines that the user draws around the objects, depending on the field lassoType. When lassoType is NOLASSO, or when the lasso is empty (the screen coordinates of the button down and button up event are the same), SoExtSelection behaves exactly like its parent class SoSelection.

Objects are selected if they are surrounded by the lasso or if the lasso intersects them, depending on the field lassoPolicy, as follows:

• FULL_BBOX: lasso selects objects whose bounding box is completely contained by the lasso
• PART_BBOX: lasso selects objects whose bounding box intersects the lasso (or is contained by the lasso)
• FULL: lasso selects objects whose geometry is completely contained by the lasso
• PART: lasso selects objects whose geometry intersects the lasso (or is contained by the lasso)

FULL and PART require more computation and are generally slower.

A lasso mode controls whether only visible shapes (front shapes) are selectable, by controlling the selection algorithm used, either geometry-based or pixel-based. A specific lasso mode may also be preferred for performance reasons depending on the scene.

Primitive details for selected parts of shapes can be obtained through dedicated callbacks that can be also used to filter the selection. These primitive filter callbacks can be called for each generated primitive.

When using SoExtSelection node, the callback set by setPickFilterCallback will be called only once per selected shape. Only SoPickedPoint.getPath() makes sense for the picked point passed to the pick filter callback in this case. Other SoPickedPoint methods may return undefined results.

Lasso selection can be also be controlled programmatically, without requiring user interaction.

NOTE: The features below which depend on overlay planes are supported only if the graphics board supports overlay planes.

NOTE: Using the FastEdit mode:

FastEdit mode provides the advantages of overlay mode without the overlay hardware support requirement. See SoSeparator for more information about the fast editing feature. FastEdit mode can allow the lasso geometry to be redrawn at interactive rates even when the underlying scene takes a long time to redraw. On Windows platforms, it also avoids using GDI to draw the lasso, which conflicts with the "Aero" user interface mode on Windows Vista.

When the application uses fast editing it must call the function useFastEdit(true) first. If it doesn't call this function, operations which require fast edit will output a warning in debug mode.

FastEdit mode also provides some powerful additional features including the option to provide custom (and dynamic) lasso geometry (see the setSelectionSceneGraph() method) and the option to set callbacks on mouse events during selection (see the methods setStartSelectionCallback(), setEndSelectionCallback(), and setMovingSelectionCallback()). The geometry in the selection scene graph can be dynamically updated by the application as the user moves the cursor, using these callbacks. This can useful to display dynamic feedback without actually doing selection. For example to display a "rubber band" line while positioning annotations or measurements. However note that the selection scene graph is always traversed, not just when the user is selecting. It is the application's responsibility to empty the selection scene graph (or hide its contents using an SoSwitch) when appropriate.

Note: The geometry in the selection scene graph is not automatically used for selection. (It may not be appropriate.) However the application can use the select() method, if desired, to do a selection using any set of 2D points defining a "lasso".

Finally note that since Open Inventor 8.6, SoScreenDrawer and its specialized sub-classes provide a more general mechanism for interactively drawing polylines, rectangles, ellipses, etc in screen space.

Clipping:
SoExtSelection avoids selecting shapes that are culled by active SoClipPlane(s) in both the ALL_SHAPES and VISIBLE Lasso modes. The user can disable this, and restore the legacy behavior of SoExtSelection before Open Inventor 9.4.0, by setting the environment variable OIV_SELECTION_USE_CLIPPLANES to 0 (see SoPreferences).

Instancing:
When instance nodes of a SoMultipleInstance or a SoMultipleCopy group are selected, the application can get the instance identifier using the SoPath method getInstanceIndex().

See SoSelection for additional information about the selection list and code example.

File format/default:

ExtSelection {

renderCaching	AUTO
boundingBoxCaching	AUTO
renderCulling	AUTO
pickCulling	AUTO
policy	SHIFT
lassoType	NOLASSO
lassoPolicy	FULL_BBOX
lassoMode	ALL_SHAPES
fastEditing	DISABLE

}

See also:

SoRayPickAction, SoSelection, SoWinRenderArea

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoExtSelection.LassoModes Lasso mode.
static class	SoExtSelection.LassoPolicies Lasso policy.
static class	SoExtSelection.LassoTypes Lasso type.
static class	SoExtSelection.PreFilterEventArg Structure given to callback when a PreFilter event is raised.
static class	SoExtSelection.ReturnTypes Return type.

Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoSelection

SoSelection.Policies

Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoSeparator

SoSeparator.Cachings, SoSeparator.FastEditings, SoSeparator.RenderUnitIds

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL_SHAPES Deprecated. Use SoExtSelection.LassoModes.ALL_SHAPES instead.
static int	ELLIPSE Deprecated. Use SoExtSelection.LassoTypes.ELLIPSE instead.
static int	FULL Deprecated. Use SoExtSelection.LassoPolicies.FULL instead.
static int	FULL_BBOX Deprecated. Use SoExtSelection.LassoPolicies.FULL_BBOX instead.
static int	LASSO Deprecated. Use SoExtSelection.LassoTypes.LASSO instead.
SoSFEnum<SoExtSelection.LassoModes>	lassoMode Specifies the lasso mode (whether ALL_SHAPES or only VISIBLE_SHAPES can be selected).
SoSFEnum<SoExtSelection.LassoPolicies>	lassoPolicy Specifies the lasso policy.
SoSFEnum<SoExtSelection.LassoTypes>	lassoType Specifies lasso type (none, lasso, or rectangle).
static int	NOLASSO Deprecated. Use SoExtSelection.LassoTypes.NOLASSO instead.
static int	NOSELECT_CONTINUE Deprecated. Use SoExtSelection.ReturnTypes.NOSELECT_CONTINUE instead.
static int	NOSELECT_RETURN Deprecated. Use SoExtSelection.ReturnTypes.NOSELECT_RETURN instead.
SbEventHandler<SoExtSelection.PreFilterEventArg>	onPreFilter The ExtSelection will traverse and test selection for each node of the scene graph.
static int	PART Deprecated. Use SoExtSelection.LassoPolicies.PART instead.
static int	PART_BBOX Deprecated. Use SoExtSelection.LassoPolicies.PART_BBOX instead.
static int	RECTANGLE Deprecated. Use SoExtSelection.LassoTypes.RECTANGLE instead.
static int	SELECT_CONTINUE Deprecated. Use SoExtSelection.ReturnTypes.SELECT_CONTINUE instead.
static int	SELECT_RETURN Deprecated. Use SoExtSelection.ReturnTypes.SELECT_RETURN instead.
static int	VISIBLE_SHAPES Deprecated. Use SoExtSelection.LassoModes.VISIBLE_SHAPES instead.

Fields inherited from class com.openinventor.inventor.nodes.SoSelection

DISABLE, policy, SHIFT, SINGLE, TOGGLE

Fields inherited from class com.openinventor.inventor.nodes.SoSeparator

AUTO, boundingBoxCaching, CLEAR_ZBUFFER, directVizCaching, fastEditing, KEEP_ZBUFFER, OFF, ON, pickCulling, renderCaching, renderCulling, renderUnitId

Fields inherited from class com.openinventor.inventor.nodes.SoGroup

boundingBoxIgnoring

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoExtSelection() Constructor.

Method Summary

Modifier and Type	Method and Description
void	animateOverlayLasso() Calls animateOverlayLasso(true).
void	animateOverlayLasso(boolean flg) Sets the the lasso animation flag.
java.nio.ShortBuffer	getDirectLassoCoordsDC() Returns the lasso coordinates in device coordinates.
java.nio.FloatBuffer	getDirectLassoCoordsWC() Returns the lasso coordinates in world coordinates.
SbColor	getLassoColor() Gets the lasso color.
SbVec2s[]	getLassoCoordsDC() Returns the lasso coordinates in device coordinates.
SbVec3f[]	getLassoCoordsWC() Returns the lasso coordinates in world coordinates.
float	getLassoWidth() Gets the lasso line width.
int	getOverlayLassoColorIndex() Gets the lasso color index.
short	getOverlayLassoPattern() Gets the lasso stipple pattern.
SoSeparator	getOverlaySceneGraph() Returns the scene graph that should be passed to the render area function setOverlaySceneGraph .
java.util.Vector<SoPath>	getSelectionPathList() Returns paths list of selected objects.
SoNode	getSelectionSceneGraph() Returns the scenegraph displayed as "lasso" in fast edit mode.
boolean	isOverlayLassoAnimated() Gets the the lasso animation flag.
boolean	isUsingFastEditing() Gets whether the lasso is drawn using fast editing.
boolean	isUsingOverlay() Deprecated. As of Open Inventor 9610 See documentation for more details
void	select(SoNode root, SbVec2f[] lassoCoord, SbViewportRegion viewport, boolean shiftPressed) Simulates interactive selection starting from the root node with the given lasso contour, updating the selection list and triggering any associated callback .
void	setLassoColor(SbColor c) Sets the lasso color.
void	setLassoWidth(float width) Sets the lasso line width.
void	setOverlayLassoColorIndex(int index) Sets the lasso color index.
void	setOverlayLassoPattern(short pattern) Sets the lasso stipple pattern.
void	setSelectionSceneGraph(SoNode sceneGraph) Sets the scenegraph to be displayed as "lasso" in fast edit mode.
void	useFastEditing() Calls useFastEditing(true).
void	useFastEditing(boolean flg) Sets whether the lasso should be drawn using fast editing.
void	useOverlay() Deprecated.
void	useOverlay(boolean flg) Deprecated. As of Open Inventor 9610 See documentation for more details

Methods inherited from class com.openinventor.inventor.nodes.SoSelection

addChangeCallback, addChangeCallback, addDeselectionCallback, addDeselectionCallback, addFinishCallback, addFinishCallback, addSelectionCallback, addSelectionCallback, addStartCallback, addStartCallback, deselect, deselect, deselect, deselectAll, getList, getNumSelected, getPath, getPickRadius, getValueAt, isPickMatching, isSelected, isSelected, removeChangeCallback, removeChangeCallback, removeDeselectionCallback, removeDeselectionCallback, removeFinishCallback, removeFinishCallback, removeSelectionCallback, removeSelectionCallback, removeStartCallback, removeStartCallback, select, select, setPickFilterCallback, setPickFilterCallback, setPickFilterCallback, setPickMatching, setPickRadius, toggle, toggle

Methods inherited from class com.openinventor.inventor.nodes.SoSeparator

getNumRenderCaches, setNumRenderCaches

Methods inherited from class com.openinventor.inventor.nodes.SoGroup

addChild, findChild, getChild, getNumChildren, insertChild, removeAllChildren, removeChild, removeChild, replaceChild, replaceChild

Methods inherited from class com.openinventor.inventor.nodes.SoNode

affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write

Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer

copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults

Methods inherited from class com.openinventor.inventor.misc.SoBase

dispose, getEXTERNPROTO, getName, getPROTO, isDisposable, isSynchronizable, setName, setSynchronizable

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NOLASSO

@Deprecated
public static final int NOLASSO

Deprecated. Use SoExtSelection.LassoTypes.NOLASSO instead.

LASSO

@Deprecated
public static final int LASSO

Deprecated. Use SoExtSelection.LassoTypes.LASSO instead.

RECTANGLE

@Deprecated
public static final int RECTANGLE

Deprecated. Use SoExtSelection.LassoTypes.RECTANGLE instead.

ELLIPSE

@Deprecated
public static final int ELLIPSE

Deprecated. Use SoExtSelection.LassoTypes.ELLIPSE instead.

FULL_BBOX

@Deprecated
public static final int FULL_BBOX

Deprecated. Use SoExtSelection.LassoPolicies.FULL_BBOX instead.

PART_BBOX

@Deprecated
public static final int PART_BBOX

Deprecated. Use SoExtSelection.LassoPolicies.PART_BBOX instead.

FULL

@Deprecated
public static final int FULL

Deprecated. Use SoExtSelection.LassoPolicies.FULL instead.

PART

@Deprecated
public static final int PART

Deprecated. Use SoExtSelection.LassoPolicies.PART instead.

VISIBLE_SHAPES

@Deprecated
public static final int VISIBLE_SHAPES

Deprecated. Use SoExtSelection.LassoModes.VISIBLE_SHAPES instead.

ALL_SHAPES

@Deprecated
public static final int ALL_SHAPES

Deprecated. Use SoExtSelection.LassoModes.ALL_SHAPES instead.

NOSELECT_CONTINUE

@Deprecated
public static final int NOSELECT_CONTINUE

Deprecated. Use SoExtSelection.ReturnTypes.NOSELECT_CONTINUE instead.

SELECT_RETURN

@Deprecated
public static final int SELECT_RETURN

Deprecated. Use SoExtSelection.ReturnTypes.SELECT_RETURN instead.

SELECT_CONTINUE

@Deprecated
public static final int SELECT_CONTINUE

Deprecated. Use SoExtSelection.ReturnTypes.SELECT_CONTINUE instead.

NOSELECT_RETURN

@Deprecated
public static final int NOSELECT_RETURN

Deprecated. Use SoExtSelection.ReturnTypes.NOSELECT_RETURN instead.

lassoType

public final SoSFEnum<SoExtSelection.LassoTypes> lassoType

Specifies lasso type (none, lasso, or rectangle). . Default is NOLASSO.

lassoPolicy

public final SoSFEnum<SoExtSelection.LassoPolicies> lassoPolicy

Specifies the lasso policy. See description above. . Default is FULL_BBOX.

lassoMode

public final SoSFEnum<SoExtSelection.LassoModes> lassoMode

Specifies the lasso mode (whether ALL_SHAPES or only VISIBLE_SHAPES can be selected). . Default is ALL_SHAPES. It applies only when the lasso policy is FULL or PART. When the lasso mode is VISIBLE_SHAPES, you will only select visible shapes. That is, if a shape is within (or partially within) the lasso volume, but is hidden by another shape, it will not be selected. VISIBLE_SHAPES mode provides faster performance than ALL_SHAPES (the default).

The algorithm for the ALL_SHAPES mode is based on geometry projection while the VISIBLE_SHAPES mode uses offscreen rendering.

When using VISIBLE_SHAPES, none of the primitive selection callback nodes can be called. This means that you cannot retrieve selection details using this mode.

Unlike the ALL_SHAPES mode or the picking action, the VISIBLE_SHAPES mode does not allow you to select multiple overlapping shapes. You cannot select a shape obscured by another.

onPreFilter

public final SbEventHandler<SoExtSelection.PreFilterEventArg> onPreFilter

The ExtSelection will traverse and test selection for each node of the scene graph. The PreFilter event is raised for each node, before doing the intersection test, and can be used to skip a particular node to avoid doing costly computation. To skip a node, call the method SoExtSelection.PreFilterEventArg.skipNode() inside your callback.

Constructor Detail

SoExtSelection

public SoExtSelection()

Constructor.

Method Detail

animateOverlayLasso

public void animateOverlayLasso()

Calls animateOverlayLasso(true).

useFastEditing

public void useFastEditing()

Calls useFastEditing(true).

useOverlay

@Deprecated
public void useOverlay()

Deprecated.

Calls useOverlay(true).

isUsingOverlay

@Deprecated
public boolean isUsingOverlay()

Deprecated. As of Open Inventor 9610 See documentation for more details

Gets whether the lasso is drawn in the overlay plane. Deprecated since Open Inventor 9610
Overlay feature is legacy, and no longer makes sense with current hardware.

useOverlay

@Deprecated
public void useOverlay(boolean flg)

Deprecated. As of Open Inventor 9610 See documentation for more details

Sets whether the lasso is drawn in the overlay plane.
This only works if the graphics board supports overlay planes (for example the NVIDIA Quadro boards). Default is false.Deprecated since Open Inventor 9610
Overlay feature is legacy, and no longer makes sense with current hardware.

getOverlaySceneGraph

public SoSeparator getOverlaySceneGraph()

Returns the scene graph that should be passed to the render area function setOverlaySceneGraph . Applies only if the lasso is drawn in the overlay plane.

isUsingFastEditing

public boolean isUsingFastEditing()

Gets whether the lasso is drawn using fast editing.

useFastEditing

public void useFastEditing(boolean flg)

Sets whether the lasso should be drawn using fast editing.
When the application uses the FastEdit mode it must call this function first before calling any other function in this class. See also SoGLRenderAction.setFastEditSavePolicy for possible limitations. Default is false.

getLassoCoordsWC

public SbVec3f[] getLassoCoordsWC()

Returns the lasso coordinates in world coordinates.

getSelectionPathList

public java.util.Vector<SoPath> getSelectionPathList()

Returns paths list of selected objects.

select

public void select(SoNode root,
                   SbVec2f[] lassoCoord,
                   SbViewportRegion viewport,
                   boolean shiftPressed)

Simulates interactive selection starting from the root node with the given lasso contour, updating the selection list and triggering any associated callback . Even though the selection operation may not involve a window per se, some nodes need the viewport information to determine their size and placement.

NOTE: The root node must be the root of a scene graph that includes the camera node. For example, when using an Open Inventor viewer, use getSceneManager()->getSceneGraph().

Setting shiftPressed true simulates the effect of pressing the shift key while selecting, consistent with the SoSelection.Shift policy.

The lasso type can be set using the lassoType field, but the lasso will not be drawn when using this method. The lasso coordinates are given in normalized device coordinates ranging from -1 to +1 in the X and Y directions, determined directly from the viewport.

Note: When the lassoType is set to LASSO the objects are selected according to the points defined by the lasso coordinates so the segments between those points are not part of the lasso!.

getDirectLassoCoordsDC

public java.nio.ShortBuffer getDirectLassoCoordsDC()

Returns the lasso coordinates in device coordinates.

getLassoCoordsDC

public SbVec2s[] getLassoCoordsDC()

Returns the lasso coordinates in device coordinates.

getDirectLassoCoordsWC

public java.nio.FloatBuffer getDirectLassoCoordsWC()

Returns the lasso coordinates in world coordinates.

animateOverlayLasso

public void animateOverlayLasso(boolean flg)

Sets the the lasso animation flag. This controls whether the lasso is animated (its line pattern changes) or not. Default is false.

getOverlayLassoPattern

public short getOverlayLassoPattern()

Gets the lasso stipple pattern. Values can range from 0 (invisible) to 0xffff (solid).

setOverlayLassoPattern

public void setOverlayLassoPattern(short pattern)

Sets the lasso stipple pattern. Values can range from 0 (invisible) to 0xffff (solid). This specifies how dashed or dotted lasso lines will be drawn. This function actually sets the line pattern in all cases, not just overlay. Default is 0xffff (solid).

setSelectionSceneGraph

public void setSelectionSceneGraph(SoNode sceneGraph)

Sets the scenegraph to be displayed as "lasso" in fast edit mode. Note: This function is available only in FastEdit mode.

The geometry in this scene graph can be dynamically updated by the application as the user moves the cursor. See the methods setStartSelectionCallback(), setMovingSelectionCallback(), etc. This can useful to display dynamic feedback without actually doing selection. For example to display a "rubber band" line while positioning annotation or measurements.

Note: The geometry in this scene graph is not automatically used for selection! (It may not be appropriate.) The application can use the select() method, if desired, to do a selection using any set of 2D points defining a "lasso".

getSelectionSceneGraph

public SoNode getSelectionSceneGraph()

Returns the scenegraph displayed as "lasso" in fast edit mode. Note: This function is available only in FastEdit mode, returns NULL otherwise.

isOverlayLassoAnimated

public boolean isOverlayLassoAnimated()

Gets the the lasso animation flag.

setLassoColor

public void setLassoColor(SbColor c)

Sets the lasso color. Applies only if the lasso is not drawn in the overlay plane. This function sets the color in FastEdit mode also. Default is red (1,0,0).

getOverlayLassoColorIndex

public int getOverlayLassoColorIndex()

Gets the lasso color index. Applies only if the lasso is drawn in the overlay plane.

setOverlayLassoColorIndex

public void setOverlayLassoColorIndex(int index)

Sets the lasso color index. Applies only if the lasso is drawn in the overlay plane.

getLassoWidth

public float getLassoWidth()

Gets the lasso line width.

setLassoWidth

public void setLassoWidth(float width)

Sets the lasso line width. This function sets the width in FastEdit mode also. Default is 1.

getLassoColor

public SbColor getLassoColor()

Gets the lasso color. Applies only if the lasso is not drawn in the overlay plane.