Open Inventor Release 2024.1.3
 
Loading...
Searching...
No Matches
SceneOrbiter Class Reference

(Preview feature) Tool class for building a basic interactive OpenInventor application with mode-less scene "orbiter" viewing behavior. More...

#include <Inventor/ViewerComponents/nodes/SceneOrbiter.h>

+ Inheritance diagram for SceneOrbiter:

Public Types

enum  RotationMethod {
  TURNTABLE ,
  TRACKBALL
}
 Defines how the mouse events or touch events control the rotations of the scene. More...
 
- Public Types inherited from SceneInteractor
enum  CameraMode {
  PERSPECTIVE ,
  ORTHOGRAPHIC
}
 Type of camera (perspective or orthographic) More...
 
- Public Types inherited from SoSeparator
enum  CacheEnabled {
  OFF ,
  ON ,
  AUTO
}
 Possible values for caching. More...
 
enum  FastEditing {
  DISABLE = 0x01 ,
  KEEP_ZBUFFER = 0x02 ,
  CLEAR_ZBUFFER = 0x03
}
 Fast editing policy enumeration values. More...
 

Public Member Functions

 SceneOrbiter ()
 Constructor.
 
virtual ~SceneOrbiter ()
 Destructor.
 
void setConstraintLevel (float level)
 Sets the constraint level to limit the turntable rotation.
 
float getConstraintLevel ()
 Returns the current constraint level which limits the turntable rotation.
 
void setRotationMethod (RotationMethod method)
 Sets the scene rotation method.
 
RotationMethod getRotationMethod ()
 Returns the current scene rotation method.
 
void setUpAxis (openinventor::inventor::Axis::Type axis)
 Sets the up axis of the scene.
 
openinventor::inventor::Axis::Type getUpAxis ()
 Returns the current up axis of the scene.
 
void enableViewingCube (bool enabled)
 Enables or disables viewing cube.
 
bool isViewingCubeEnabled () const
 Returns if viewing cube is enabled.
 
SoViewingCubegetViewingCube ()
 Returns the viewing cube object.
 
virtual void setCameraMode (SceneInteractor::CameraMode mode)
 Selects perspective or orthographic camera.
 
- Public Member Functions inherited from SceneInteractor
 SceneInteractor ()
 Constructor.
 
virtual ~SceneInteractor ()
 Destructor.
 
void adjustClippingPlanes (const SbViewportRegion &vpRegion)
 Adjust near and far clipping planes to minimize clipping of objects in the scene.
 
void viewAll (const SbViewportRegion &viewport)
 Move the camera to view the scene defined by the given path.
 
void viewAxis (const SbVec3f &direction, const SbVec3f &up)
 Moves the camera to be aligned with the given direction vector while keeping the "up" direction of the camera parallel to the specified up vector.
 
SoCameraInteractorgetCameraInteractor ()
 Returns the current camera interactor.
 
SoCameragetCamera () const
 Returns the current camera.
 
SceneInteractor::CameraMode getCameraMode ()
 Returns the current camera mode.
 
void enableHeadLight (bool enabled)
 Enable or disable headlight.
 
bool isHeadLightEnabled ()
 Returns if headlight is enabled.
 
- Public Member Functions inherited from SoSeparator
virtual SoType getTypeId () const
 Returns the type identifier for this specific instance.
 
 SoSeparator ()
 Creates a separator node with default settings.
 
 SoSeparator (int nChildren)
 Constructor that takes approximate number of children.
 
- Public Member Functions inherited from SoGroup
 SoGroup ()
 Creates an empty group node.
 
 SoGroup (int nChildren)
 Constructor that takes approximate number of children.
 
virtual void addChild (SoNode *child)
 Adds a child as last one in group.
 
virtual void insertChild (SoNode *child, int newChildIndex)
 Adds a child so that it becomes the one with the given index.
 
virtual SoNodegetChild (int index) const
 Returns pointer the child node with the given index.
 
virtual int findChild (const SoNode *child) const
 Finds index of given child within group.
 
virtual int getNumChildren () const
 Returns number of children.
 
virtual void removeChild (int index)
 Removes child with given index from group.
 
virtual void removeChild (SoNode *child)
 Removes first instance of given child from group.
 
virtual void removeAllChildren ()
 Removes all children from group.
 
virtual void replaceChild (int index, SoNode *newChild)
 Replaces child with given index with new child.
 
virtual void replaceChild (SoNode *oldChild, SoNode *newChild)
 Replaces first instance of given child with new child.
 
- Public Member Functions inherited from SoNode
virtual void setOverride (const SbBool state)
 Turns the override flag on or off.
 
virtual SbBool isOverride () const
 Returns the state of the override flag.
 
virtual SoNodecopy (SbBool copyConnections=FALSE) const
 Creates and returns an exact copy of the node.
 
virtual void touch ()
 Marks an instance as modified, simulating a change to it.
 
- Public Member Functions inherited from SoFieldContainer
void setToDefaults ()
 Sets all fields in this object to their default values.
 
SbBool hasDefaultValues () const
 Returns TRUE if all of the object's fields have their default values.
 
SbBool fieldsAreEqual (const SoFieldContainer *fc) const
 Returns TRUE if this object's fields are exactly equal to fc's fields.
 
void copyFieldValues (const SoFieldContainer *fc, SbBool copyConnections=FALSE)
 Copies the contents of fc's fields into this object's fields.
 
SoNONUNICODE SbBool set (const char *fieldDataString)
 Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.
 
SbBool set (const SbString &fieldDataString)
 Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.
 
void get (SbString &fieldDataString)
 Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.
 
virtual int getFields (SoFieldList &list) const
 Appends references to all of this object's fields to resultList, and returns the number of fields appended.
 
virtual int getAllFields (SoFieldList &list) const
 Returns a list of fields, including the eventIn's and eventOut's.
 
virtual SoFieldgetField (const SbName &fieldName) const
 Returns a the field of this object whose name is fieldName.
 
virtual SoFieldgetEventIn (const SbName &fieldName) const
 Returns a the eventIn with the given name.
 
virtual SoFieldgetEventOut (const SbName &fieldName) const
 Returns the eventOut with the given name.
 
SbBool getFieldName (const SoField *field, SbName &fieldName) const
 Returns the name of the given field in the fieldName argument.
 
SbBool enableNotify (SbBool flag)
 Notification at this Field Container is enabled (if flag == TRUE) or disabled (if flag == FALSE).
 
SbBool isNotifyEnabled () const
 Notification is the process of telling interested objects that this object has changed.
 
virtual void setUserData (void *data)
 Sets application data.
 
void * getUserData (void) const
 Gets user application data.
 
- Public Member Functions inherited from SoBase
virtual SbName getName () const
 Returns the name of an instance.
 
virtual void setName (const SbName &name)
 Sets the name of an instance.
 
void setSynchronizable (const bool b)
 Sets this to be a ScaleViz synchronizable object.
 
bool isSynchronizable () const
 Gets the ScaleViz synchronizable state of this object.
 
- Public Member Functions inherited from SoRefCounter
void ref () const
 Adds a reference to an instance.
 
void unref () const
 Removes a reference from an instance.
 
void unrefNoDelete () const
 unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
 
int getRefCount () const
 Returns current reference count.
 
void lock () const
 lock this instance.
 
void unlock () const
 unlock this instance.
 
- Public Member Functions inherited from SoTypedObject
SbBool isOfType (const SoType &type) const
 Returns TRUE if this object is of the type specified in type or is derived from that type.
 
template<typename TypedObjectClass >
SbBool isOfType () const
 Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.
 

Additional Inherited Members

- Static Public Member Functions inherited from SoSeparator
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 
- Static Public Member Functions inherited from SoGroup
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 
- Static Public Member Functions inherited from SoNode
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 
static SoNodegetByName (const SbName &name)
 A node's name can be set using SoBase::setName().
 
static int getByName (const SbName &name, SoNodeList &list)
 A node's name can be set using SoBase::setName().
 
- Static Public Member Functions inherited from SoFieldContainer
static SoType getClassTypeId ()
 Returns the type of this class.
 
- Static Public Member Functions inherited from SoBase
static SoType getClassTypeId ()
 Returns type identifier for this class.
 
- Static Public Member Functions inherited from SoTypedObject
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 
- Public Attributes inherited from SoSeparator
SoSFEnum boundingBoxCaching
 Whether to cache during bounding box traversal.
 
SoSFEnum renderCulling
 Whether to cull during rendering traversal.
 
SoSFEnum pickCulling
 Whether to cull during picking traversal.
 
SoSFEnum fastEditing
 Specifies the fast edit mode of the separator node.
 
SoSFInt32 renderUnitId
 Used during the ScaleViz depth compositing process, this field specifies which render unit (OIRU) will render the sub scene graph below this separator.
 
SoDEPRECATED SoSFEnum renderCaching
 Whether to cache during rendering traversal.
 
- Public Attributes inherited from SoGroup
SoSFBool boundingBoxIgnoring
 Whether to ignore this node during bounding box traversal.
 

Detailed Description

(Preview feature) Tool class for building a basic interactive OpenInventor application with mode-less scene "orbiter" viewing behavior.

The SceneOrbiter is an extension of the SceneInteractor node that provides camera and headlight manipulations like panning, zooming and orbiting similar to the classic Open Inventor "Examiner" viewer classes (e.g. SoWinExaminerViewer) and the SceneExaminer (in Orbit navigation mode).

The SceneOrbiter provides a "mode-less" viewer which is very convenient for users. The Examiner viewer and SceneExaminer viewers are always in either viewing mode (mouse events control the camera) or in selection mode (mouse events are sent to the scene graph and objects can be selected). This often requires the user to frequently switch between viewing and selection mode (for example by pressing the ESC key) while interacting with the scene. SceneOrbiter does not have modes. For example, a mouse click without moving the mouse is interpreted as a selection and the event is sent to the scene graph, but a mouse click and "drag" is interpreted as controlling the camera.

The SceneOrbiter provides two different methods to control the rotation of the camera around the scene : trackball and turntable, see RotationMethod enum.
The trackball method allows the camera to move along any circular orbit around the scene and look in the direction of its center. The orbit orientation can change at any time while interpreting a mouse drag. Thus the trackball is known as an unconstrained orbiting mode. The trackball is the unique method used by the historical examiner viewer and by the SceneExaminer.
The additional turntable method is a more constrained orbiting mode. It lets the camera move only along vertical orbits such as the earth meridians, and along horizontal circles such as the earth parallels. The vertical orbits and the horizontal circles are related to an up axis, which can be changed calling setUpAxis. The horizontal circles are centered around this up axis, and the vertical orbits share their south and north pole on this up axis. As the camera cannot move along any other circle, this mode is more constrained compared to the trackball mode. However, it provides a more natural navigation experience when viewing a scene that has strong vertical and horizontal references. For instance, when orbiting in turntable mode around a scene representing the Eiffel tower, this one always looks vertical on your screen. Compared to the trackball mode, the turntable mode does not need any tedious small mousemove correction to keep the scene well aligned with the borders of the screen.

The 'headlight', an SoDirectionalLight node, is automatically aligned with the camera's view direction.

An SoViewingCube node is automatically added to the scene. The viewing cube can be hidden by calling the enableViewingCube() method. Note that the up axis of the viewing cube is synchronized with the up axis of the SceneOrbiter.

See parent class SceneInteractor for more details about the structure of the internal scene graph.

The SceneOrbiter uses an instance of SoCameraInteractor to manipulate the camera in response to OpenInventor events.

Notes:

  • Window system integration
    The SceneOrbiter needs a component that integrates the Open Inventor 3D rendering window with the native window system. System dependent tasks include creating a window, placing the window in the application's user interface, initializing OpenGL and processing the native event/message loop. System independent support for this is provided by the SoRenderAreaCore class. Example components are provided for various window systems, for example, WinRenderArea for native Microsoft Windows.
  • Event handling
    The SceneOrbiter needs a component that builds OpenInventor events (SoEvent) from native system events. System independent support for this is provided by the SoEventBuilder class. Example components are provided for various window systems, for example, WinEventToSoEvent for native Microsoft Windows.
  • Library
    A basic version of SceneOrbiter is a supported part of the Open Inventor API and a prebuilt library is provided.
  • Source code
    The basic version of SceneOrbiter is also provided as source code to allow applications to customize and build their own interactive tool class.
    See $OIVHOME/source/Inventor/ViewerComponents/nodes.
  • Scene graph
    The application scene graph should be the last child of the SceneOrbiter. The initial application scene graph can be added by simply calling the inherited method addChild(). But note that if you need to replace the application scene graph, for example loading a new data set, do not call removeAllChildren(). That would also remove the SceneOrbiter's camera, headlight and event handler nodes. Add an SoSeparator to the SceneOrbiter to serve as the "scene graph holder", then add and remove the application scene graph from this node.
  • Clip planes
    SceneOrbiter automatically adjusts the 'near' and 'far' clipping planes when events modifying the camera are handled. This adjustment, based on the bounding box of the scene, ensures that shapes will not be clipped as the camera orbits and also that depth buffer precision is maximized.
    Note: Updating clipping planes after a camera move can be insufficient. If the scene graph is modified or if a dragger or a rendered shape is moved, they can disappear or become partially clipped. A classic implementation of a render area must adjust clipping planes before each rendering by calling the provided method adjustClippingPlanes(). See render area's implementations available in $OIVHOME/source/Inventor/gui folder for examples of adjustClippingPlanes use.
  • Compatibility with classical viewers
    Please note that some interaction behaviors are different from the classic Open Inventor viewer classes (e.g. SoXtExaminerViewer):

    • Left Mouse + Shift does Zoom in/out.
    • The Mouse wheel performs a dolly relative to the cursor position, not the center of the viewport.

    • The classic ESC key behavior is not implemented.
      (Not necessary because viewing and selection are supported without separate modes.)
    • The classic Alt key behavior is not implemented. This key is reserved for application use.
    • The Right Mouse button does not display a popup menu. This button is reserved for application use.
    • Seek mode is not supported.
  • Compatibility with SceneExaminer
    • Only the left mouse button has defined behaviors.
      Pan and zoom behaviors require pressing a keyboard key while dragging the mouse.

USAGE



    • Left Mouse: Rotate the scene.
    • Left Mouse + Ctrl: Pan the scene.
    • Left Mouse + Shift: Zoom in/out.
    • Mouse Wheel: Zoom in/out (zoom center is the mouse cursor location).

SEE ALSO

SceneInteractor, SoCameraInteractor, SiInteractionModeListener

Definition at line 151 of file SceneOrbiter.h.

Member Enumeration Documentation

◆ RotationMethod

Defines how the mouse events or touch events control the rotations of the scene.

Enumerator
TURNTABLE 

Constrained mode which forces the camera to follow meridians and parallel circles related to the up-axis.

This mode is very useful to help the user to see the up-axis of the scene vertical, i.e. parallel to the left/right borders of the screen.

TRACKBALL 

Unconstrained mode which allows the camera to follow any circular orbit.

Thus, this mode allows to render the scene with any orientation.

Definition at line 159 of file SceneOrbiter.h.

Constructor & Destructor Documentation

◆ SceneOrbiter()

SceneOrbiter::SceneOrbiter ( )

Constructor.

◆ ~SceneOrbiter()

virtual SceneOrbiter::~SceneOrbiter ( )
virtual

Destructor.

Member Function Documentation

◆ enableViewingCube()

void SceneOrbiter::enableViewingCube ( bool  enabled)

Enables or disables viewing cube.

Default is true.

◆ getConstraintLevel()

float SceneOrbiter::getConstraintLevel ( )

Returns the current constraint level which limits the turntable rotation.

Returns
the constraint level.

◆ getRotationMethod()

RotationMethod SceneOrbiter::getRotationMethod ( )

Returns the current scene rotation method.

◆ getUpAxis()

openinventor::inventor::Axis::Type SceneOrbiter::getUpAxis ( )

Returns the current up axis of the scene.

◆ getViewingCube()

SoViewingCube * SceneOrbiter::getViewingCube ( )

Returns the viewing cube object.

◆ isViewingCubeEnabled()

bool SceneOrbiter::isViewingCubeEnabled ( ) const

Returns if viewing cube is enabled.

◆ setCameraMode()

virtual void SceneOrbiter::setCameraMode ( SceneInteractor::CameraMode  mode)
virtual

Selects perspective or orthographic camera.

Default is perspective.

Reimplemented from SceneInteractor.

◆ setConstraintLevel()

void SceneOrbiter::setConstraintLevel ( float  level)

Sets the constraint level to limit the turntable rotation.

The level is a value between [0,1] used to adjust the constraint on the turntable rotation according to the speed of movement :

  • 0 means no constraint on the rotation regardless of the interaction speed
  • 1 means very strongly constrained even if interaction is slow.

This prevents unexpected changes in the axis of rotation during fast movements. Default is 0 which means no constraint on the rotation.

Parameters
levelthe constraint level.

◆ setRotationMethod()

void SceneOrbiter::setRotationMethod ( RotationMethod  method)

Sets the scene rotation method.

Default is TURNTABLE.

◆ setUpAxis()

void SceneOrbiter::setUpAxis ( openinventor::inventor::Axis::Type  axis)

Sets the up axis of the scene.

Default is Y. Note that the up axis of the viewing cube is synchronized with the up axis of the SceneOrbiter.


The documentation for this class was generated from the following file: