SoWinExaminerViewer Class Reference
[Win]

VSG extension Viewer component which uses a virtual trackball to view the data. More...

#include <Inventor/Win/viewers/SoWinExaminerViewer.h>

Inheritance diagram for SoWinExaminerViewer:
SoWinFullViewer SoWinViewer SoWinRenderArea SoStereoViewer SoWinGLWidget SoWinComponent

List of all members.

Classes

class  SoViewingDolly
  VSG extension Viewing Function: Dolly (move forward and backward) to get closer to or further away from the point of interest. More...
class  SoViewingEmpty
  VSG extension Viewing Function: Does nothing. More...
class  SoViewingFunction
  VSG extension Viewing Function: Abstract base class for viewing function classes. More...
class  SoViewingReverseDolly
  VSG extension Viewing Function: Reverse Dolly (move backward and forward) to get further to or closer away from the point of interest. More...
class  SoViewingRotationX
  VSG extension Viewing Function: Rotates the object around the X axis. More...
class  SoViewingRotationXViewer
  VSG extension Viewing Function: Rotates the object around the screen X axis. More...
class  SoViewingRotationY
  VSG extension Viewing Function: Rotates the object around the Y axis. More...
class  SoViewingRotationYViewer
  VSG extension Viewing Function: Rotates the object around the screen Y axis. More...
class  SoViewingRotationZ
  VSG extension Viewing Function: Rotates the object around the Z axis. More...
class  SoViewingRotationZViewer
  VSG extension Viewing Function: Rotates the object around the screen Z axis. More...
class  SoViewingSeek
  VSG extension Viewing Function: Seek (to quickly move the camera to a desired object or point). More...
class  SoViewingSphericalRotation
  VSG extension Viewing Function: Rotates the view around a point of interest using a virtual trackball. More...
class  SoViewingTranslation
  VSG extension Viewing Function: Translates the camera in the viewer plane. More...

Public Types

enum  ViewingMode {
  VIEWING_MODE_SPIN,
  VIEWING_MODE_SPIN_CONSTRAINED,
  VIEWING_MODE_PAN,
  VIEWING_MODE_ZOOM
}
enum  ConstrainedViewingMode {
  NONE,
  CONSTRAINED_VIEWING_MODE_X,
  CONSTRAINED_VIEWING_MODE_Y,
  CONSTRAINED_VIEWING_MODE_Z
}

Public Member Functions

 SoWinExaminerViewer (SoWidget parent=NULL, const char *name=NULL, SbBool buildInsideParent=TRUE, SoWinFullViewer::BuildFlag flag=SoWinFullViewer::BUILD_ALL, SoWinViewer::Type type=SoWinViewer::BROWSER)
 ~SoWinExaminerViewer ()
void setViewingMode (ViewingMode viewingMode)
ViewingMode getViewingMode () const
void setConstrainedViewingMode (ConstrainedViewingMode mode)
ConstrainedViewingMode getConstrainedViewingMode () const
virtual void addFunctionKeyBinding (SoKeyboardEvent::Key key, const SoViewingFunction *viewingFunc)
virtual void removeFunctionKeyBinding (SoKeyboardEvent::Key functionKey)
virtual void addViewingMouseBinding (SoKeyboardEvent::Key *keys=NULL, int numKey=0, SoMouseButtonEvent::Button *mouseBtn=NULL, int numMouseBtn=0, const SoViewingFunction *viewingFunc=NULL)
virtual void removeViewingMouseBinding (SoKeyboardEvent::Key *keys=NULL, int numKeys=0, SoMouseButtonEvent::Button *mouseBtn=NULL, int numMouseBtn=0)
void setFeedbackVisibility (SbBool onOrOff)
SbBool isFeedbackVisible () const
void setFeedbackSize (int newSize)
int getFeedbackSize () const
void setAnimationEnabled (SbBool onOrOff)
SbBool isAnimationEnabled ()
void stopAnimating ()
SbBool isAnimating ()
virtual void viewAll ()
virtual void resetToHomePosition ()
virtual void setCamera (SoCamera *cam)
virtual void setViewing (SbBool onOrOff)
virtual void setCursorEnabled (SbBool onOrOff)
virtual void setSeekMode (SbBool onOrOff)
virtual void activateSpinning (const SbVec2s &newLocator)
virtual void activatePanning (const SbVec2s &newLocator)
virtual void activateDolly (const SbVec2s &newLocator)
virtual void activateRoll (const SbVec2s &newLocator)
virtual void rollCamera (const SbVec2s &newLocator)
virtual void spinCamera (const SbVec2f &newLocator)
virtual void spinConstrainedCamera (const SbVec2f &newLocator, int axisIndex)
virtual void dollyCamera (const SbVec2s &newLocator)
virtual void reverseDollyCamera (const SbVec2s &newLocator)
virtual void panCamera (const SbVec2f &newLocator)

Detailed Description

VSG extension Viewer component which uses a virtual trackball to view the data.

The Examiner viewer component allows you to rotate the view around a point of interest using a virtual trackball. The viewer uses the camera focalDistance field to figure out the point of rotation, which is usually set to be at the center of the scene. In addition to allowing you to rotate the camera around the point of interest, this viewer also allows you to translate the camera in the viewer plane, as well as dolly (move forward and backward) to get closer to or further away from the point of interest. The viewer also supports seek to quickly move the camera to a desired object or point.

Focal point:

The center of rotation for the ExaminerViewer, called the focalPoint, is defined as a point that is focalDistance from the camera position, along the viewVector, where the viewVector is (indirectly) defined by the camera orientation. You can compute the focalPoint for the current camera settings like this:
       SoCamera* camera = viewer->getCamera();
       SbMatrix mx;                         // Note constructor does not accept SbRotation
       mx = camera->orientation.getValue(); // Assignment converts SbRotation to SbMatrix
       SbVec3f viewVec(-mx[2][0], -mx[2][1], -mx[2][2]);
       SbVec3f camPos  = camera->position.getValue();
       float   focDist = camera->focalDistance.getValue();
       SbVec3f focalPt = camPos + (focDist * viewVec);
To better understand the above code, remember that we can convert an SbRotation to an SbMatrix and, since orientation is a pure rotation matrix, we can consider the first three columns of this matrix to be the orthogonal X, Y and Z vectors defining the rotated coordinate system. Therefore the view vector is the inversion of the Z axis vector; and finally because this vector is already normalized, an offset of "dist" along this vector is simply "dist * vector". Of course if you have a focalPoint in mind, you can work backward to compute camera position or focalDistance depending on which parameters you want to keep constant.

Customize behaviors:

See the addFunctionKeyBinding() and addViewingMouseBinding() methods to customize some behaviors of the viewer.

Viewer components:

For applications that need more flexibility, we recommend using the "viewer component" classes to build exactly the viewing behaviors that your application needs. Please see the SoCameraInteractor, SceneInteractor and SceneExaminer classes.

USAGE

SEE ALSO

SoWinFullViewer, SoWinViewer, SoWinComponent, SoWinRenderArea, SoWinWalkViewer, SoWinFlyViewer, SoWinPlaneViewer

See related examples:

CorrectTransp, SetKeyBinding


Member Enumeration Documentation

Constrained viewing mode.

Enumerator:
NONE 

No axis constraints.

CONSTRAINED_VIEWING_MODE_X 

Constrains camera rotation around X axis.

CONSTRAINED_VIEWING_MODE_Y 

Constrains camera rotation around Y axis.

CONSTRAINED_VIEWING_MODE_Z 

Constrains camera rotation around Z axis.

Viewing mode.

Enumerator:
VIEWING_MODE_SPIN 

Rotate the camera around the point of interest.

VIEWING_MODE_SPIN_CONSTRAINED 

Same as VIEWING_MODE_SPIN but add also constrained camera rotation.

It modifies the viewer usage described previously as follow:

  • Ctrl + Left Mouse : Rotation around the Z axis
  • Shift + Left Mouse or : Rotation around the X or the Y axis.

If the mouse movement is globally from the left to the right (resp. from up to down) the Y axis (resp. X axis) is chosen.

VIEWING_MODE_PAN 

Translate the camera in the viewer plane.

VIEWING_MODE_ZOOM 

Dolly/Zoom (move forward and backward) to get closer to or further away from the point of interest.


Constructor & Destructor Documentation

SoWinExaminerViewer::SoWinExaminerViewer ( SoWidget  parent = NULL,
const char *  name = NULL,
SbBool  buildInsideParent = TRUE,
SoWinFullViewer::BuildFlag  flag = SoWinFullViewer::BUILD_ALL,
SoWinViewer::Type  type = SoWinViewer::BROWSER 
)

Constructor which specifies the viewer type.

Please refer to SoWinViewer for a description of the viewer types.

NOTES

    On Windows, the constructor will not create a new top level window -- you must pass a valid window handle for the parent parameter and pass TRUE for buildInsideParent .

SoWinExaminerViewer::~SoWinExaminerViewer (  ) 

Destructor.


Member Function Documentation

virtual void SoWinExaminerViewer::activateDolly ( const SbVec2s newLocator  )  [virtual]

Sets the start locator for dolly camera animation.

This method should be called fisrt, before to start a dolly camera animation.

Parameters:
newLocator The start mouse position in pixels. The coordinates must be defined with x in the range [0,window width] and y in the range [0,window height] with min y at the bottom and min x on the left.
Since Open Inventor 9.2.1

virtual void SoWinExaminerViewer::activatePanning ( const SbVec2s newLocator  )  [virtual]

Sets the start locator for pan camera animation.

This method should be called fisrt, before to start a pan camera animation.

Parameters:
newLocator The start mouse position in pixels. The coordinates must be defined with x in the range [0,window width] and y in the range [0,window height] with min y at the bottom and min x on the left.
Since Open Inventor 9.2.1

virtual void SoWinExaminerViewer::activateRoll ( const SbVec2s newLocator  )  [virtual]

Sets the start locator for roll camera animation.

This method should be called fisrt, before to start a roll camera animation.

Parameters:
newLocator The start mouse position in pixels. The coordinates must be defined with x in the range [0,window width] and y in the range [0,window height] with min y at the bottom and min x on the left.
Since Open Inventor 9.2.1

virtual void SoWinExaminerViewer::activateSpinning ( const SbVec2s newLocator  )  [virtual]

Sets the start locator for spin camera animation.

This method should be called fisrt, before to start a spin camera animation.

Parameters:
newLocator The start mouse position in pixels. The coordinates must be defined with x in the range [0,window width] and y in the range [0,window height] with min y at the bottom and min x on the left.
Since Open Inventor 9.2.1

virtual void SoWinExaminerViewer::addFunctionKeyBinding ( SoKeyboardEvent::Key  key,
const SoViewingFunction viewingFunc 
) [virtual]

Adds a new function key binding to the viewer.

This method allows you to associate a keyboard key with a viewing function, such as rotation or translation. The specified viewing function replaces any viewing function currently associated with the specified key. Any key may be used, not just "function keys".

A key cannot be associated with more than one viewing function at a time. However, more than one key can be associated with a single viewing function. For example, the S and T keys could each be used to invoke the seek operation.

virtual void SoWinExaminerViewer::addViewingMouseBinding ( SoKeyboardEvent::Key keys = NULL,
int  numKey = 0,
SoMouseButtonEvent::Button mouseBtn = NULL,
int  numMouseBtn = 0,
const SoViewingFunction viewingFunc = NULL 
) [virtual]

Adds a new mouse binding to the viewer.

This method allows you to associate an array of modifier keys (of length numKey) and an array of mouse buttons (of length numMouseBtn) with a viewing operation, such as rotation or translation. The specified viewing function replaces the viewing function currently associated with the specified key and mouse button sequence.

Modifier keys (CTRL, SHIFT, CTRL+SHIFT...) can be specified in addition to the mouse buttons chosen. There is no error for specifying non-modifier keys, but they have no effect. The order of the keys and the mouse buttons is important. For example, CTRL+SHIFT+BT1 is different from SHIFT+CTRL+BT1. Likewise, CTRL+BT1+BT2 is different from CTRL+BT2+BT1.

A key and mouse button sequence cannot be associated with more than one viewing function at a time. However, more than one key and mouse button sequence can be associated with a single viewing function.

Notes:

  • Mouse button and key bindings are active in both viewing and selection mode. This means that bindings can be used to have viewing functions available in selection mode. But note that if a binding exists for a mouse button or key, then the corresponding event is not sent to the scene graph in selection mode.
  • When one of the viewing functions, e.g. SoViewingDolly, is activated it will automatically set an appropriate cursor shape (if there is one) for that function.
  • Many keyboards have Shift and Ctrl keys on the left side and the right side. The left and right keys, e.g. LEFT_SHIFT and RIGHT_SHIFT, are different for event handling. But for convenience, assigning either one to a mouse binding effectively assigns both keys.
  • It is also possible to redefine any of the mouse buttons by handling the mouse button events before the viewer handles them (see setEventCallback()).
  • Popup menu is automatically disable when Button3 is redefined.
  • When one of the viewing functions is activated and the viewer is in "selection" mode, the viewer is switched to "viewing" mode when applying the function and then, returns in selection mode.

Limitations:

  • It is not currently possible to redefine Button1 as selection (picking). However you can implement this behavior using setEventCallback() to always send Button1 events to the scene graph.
  • In the default viewer behavior, pressing a modifier key during an LButton viewing operation will temporarily change the active viewing function. For example, while pressing LButton to spin, pressing the shift key temporarily switches to pan function. It is not currently possible to define such behavior using mouse bindings.
virtual void SoWinExaminerViewer::dollyCamera ( const SbVec2s newLocator  )  [virtual]

Move the camera on the z axis based on cursor motion.

This corresponds to pressing left and middle mouse buttons, pressing control + shift + left mouse button or using the mouse wheel.

Parameters:
newLocator The new cursor position. The coordinates are in pixels with x in the range [0,window width-1] and y in the range [0,window height-1] with min y at the bottom and min x on the left.
ConstrainedViewingMode SoWinExaminerViewer::getConstrainedViewingMode (  )  const [inline]

Returns the current constrained viewing mode.

int SoWinExaminerViewer::getFeedbackSize (  )  const [inline]

Returns the point of rotation feedback size in pixels.

ViewingMode SoWinExaminerViewer::getViewingMode (  )  const [inline]

Gets the current viewing mode.

SbBool SoWinExaminerViewer::isAnimating (  )  [inline]

Queries if the viewer is currently animating.

SbBool SoWinExaminerViewer::isAnimationEnabled (  )  [inline]

Returns whether spin animation is enabled.

SbBool SoWinExaminerViewer::isFeedbackVisible (  )  const [inline]

Returns the rotation feedback flag.

virtual void SoWinExaminerViewer::panCamera ( const SbVec2f newLocator  )  [virtual]

Pans the camera based on cursor motion.

Parameters:
newLocator The new cursor position. The coordinates are in normalized device coordinates with x and y in the range [0,1] with min y at the bottom and min x on the left.
virtual void SoWinExaminerViewer::removeFunctionKeyBinding ( SoKeyboardEvent::Key  functionKey  )  [virtual]

Removes the specified function key binding (if it exists).

virtual void SoWinExaminerViewer::removeViewingMouseBinding ( SoKeyboardEvent::Key keys = NULL,
int  numKeys = 0,
SoMouseButtonEvent::Button mouseBtn = NULL,
int  numMouseBtn = 0 
) [virtual]

Removes a mouse binding (if it exists).

The key and button order is important. For example, CTRL+SHIFT+BT1 is different from SHIFT+CTRL+BT1. Likewise, CTRL+BT1+BT2 is different from CTRL+BT2+BT1.

virtual void SoWinExaminerViewer::resetToHomePosition (  )  [virtual]

Restores the camera values.

Reimplemented from SoWinViewer.

virtual void SoWinExaminerViewer::reverseDollyCamera ( const SbVec2s newLocator  )  [virtual]

Same as dollyCamera but reversed.

Parameters:
newLocator The new cursor position. The coordinates are in pixels with x in the range [0,window width-1] and y in the range [0,window height-1] with min y at the bottom and min x on the left.
virtual void SoWinExaminerViewer::rollCamera ( const SbVec2s newLocator  )  [virtual]

Roll the camera based on cursor motion.

Parameters:
newLocator The new cursor position. The coordinates are in pixels with x in the range [0,window width-1] and y in the range [0,window height-1] with min y at the bottom and min x on the left.
void SoWinExaminerViewer::setAnimationEnabled ( SbBool  onOrOff  ) 

Enables/disables the spin animation feature of the viewer (enabled by default).

The default value can be set using the environment variable OIV_VIEWER_ANIMATION (0 = OFF, 1 = ON).

virtual void SoWinExaminerViewer::setCamera ( SoCamera cam  )  [virtual]

Sets the edited camera.

Setting the camera is only needed if the first camera found in the scene when setting the scene graph isn't the one the user really wants to edit.

Reimplemented from SoWinFullViewer.

void SoWinExaminerViewer::setConstrainedViewingMode ( ConstrainedViewingMode  mode  ) 

Sets the constrained viewing mode.

This method is useful to associate a key combination with a constrained mode. Notes:

  • There is no need to set the viewing mode to VIEWING_MODE_SPIN_CONSTRAINED to apply a constraint.
  • When the constrained mode is set to NONE, the automatic constraints apply if VIEWING_MODE_SPIN_CONSTRAINED is set.
  • This setting is a "one shot". It only applies to the next mouse button down event.
virtual void SoWinExaminerViewer::setCursorEnabled ( SbBool  onOrOff  )  [virtual]

Sets whether the viewer is allowed to change the cursor over the renderArea window.

When disabled, the cursor is undefined by the viewer and will not change as the mode of the viewer changes. When re-enabled, the viewer will reset it to the appropriate icon.

Disabling the cursor enables the application to set the cursor directly on the viewer window or on any parent widget of the viewer. This can be used when setting a busy cursor on the application shell.

Reimplemented from SoWinViewer.

void SoWinExaminerViewer::setFeedbackSize ( int  newSize  ) 

Sets the point of rotation feedback size in pixels (default 20 pix).

void SoWinExaminerViewer::setFeedbackVisibility ( SbBool  onOrOff  ) 

Shows/hides the point of rotation feedback, which only appears while in viewing mode (default is off).

virtual void SoWinExaminerViewer::setSeekMode ( SbBool  onOrOff  )  [virtual]

Externally set the viewer into/out off seek mode (default OFF).

Actual seeking will not happen until the viewer decides to (ex: mouse click).

Note: setting the viewer out of seek mode while the camera is being animated will stop the animation to the current location.

Reimplemented from SoWinViewer.

virtual void SoWinExaminerViewer::setViewing ( SbBool  onOrOff  )  [virtual]

Sets whether the viewer is turned on or off.

When turned on, messages are consumed by the viewer. When viewing is off, messages are processed by the viewer's render area. This means messages will be sent down to the scene graph for processing (i.e. picking can occur). Note that if the application has registered a message callback , it will be invoked on every message, whether viewing is turned on or not. However, the return value of this callback (which specifies whether the callback handled the message or not) is ignored when viewing is on. That is, the viewer will process the message even if the callback already did. This is to ensure that the viewing paradigm is not broken (default viewing is on).

Reimplemented from SoWinFullViewer.

void SoWinExaminerViewer::setViewingMode ( ViewingMode  viewingMode  ) 

Sets the viewing mode.

This method specifies what is the viewing behavior when the left mouse is pressed. The default value is SPIN_VIEWING_MODE.

virtual void SoWinExaminerViewer::spinCamera ( const SbVec2f newLocator  )  [virtual]

Spin the camera based on cursor motion.

Parameters:
newLocator The new cursor position. The coordinates are in normalized device coordinates with x and y in the range [0,1] with min y at the bottom and min x on the left.
virtual void SoWinExaminerViewer::spinConstrainedCamera ( const SbVec2f newLocator,
int  axisIndex 
) [virtual]

Spin the constrained camera based on cursor motion.

Parameters:
newLocator The new cursor position. The coordinates are in normalized device coordinates with x and y in the range [0,1] with min y at the bottom and min x on the left.
axisIndex the axis index:

  • X = 0
  • Y = 1
  • Z = 2
void SoWinExaminerViewer::stopAnimating (  ) 

Stops animation, if it is occurring.

virtual void SoWinExaminerViewer::viewAll (  )  [virtual]

Changes the camera position to view the entire scene (the camera zoom or orientation isn't changed).

The viewer applies an SoGetBoundingBoxAction to the scene graph to get bounding box of the entire scene. The bounding box will only include shapes that are actually traversed. For example the bounding box will not include shapes under an SoSwitch with whichChild set to SO_SWITCH_NONE. The action does not consider the visibility of shapes that are traversed. In other words the bounding box will include shapes that are invisible (SoDrawStyle), shapes that are clipped (SoClipPlane), etc. Use an SoBBox node to exclude shapes from the bounding box computation. Bounding boxes are automatically cached at SoSeparator nodes, so getting the bounding box is very fast when the scene graph has not been changed.

See all SoCamera::viewAll(). This method allows the application to adjust the camera based on a specific sub-graph or path in the scene graph.

Reimplemented from SoWinViewer.


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

Open Inventor Toolkit reference manual, generated on 28 Oct 2019
Copyright © Thermo Fisher Scientific All rights reserved.
http://www.openinventor.com/