SoQtViewer - Man Page

The SoQtViewer class is the top level base viewer class.


#include <Inventor/Qt/viewers/SoQtViewer.h>

Inherits SoQtRenderArea.

Inherited by SoQtFullViewer.

Public Types

enum Type { BROWSER, EDITOR }
enum DrawType { STILL = 0, INTERACTIVE }

Public Member Functions

virtual void setCamera (SoCamera *camera)
SoCamera * getCamera (void) const
virtual void setCameraType (SoType type)
SoType getCameraType (void) const
virtual void toggleCameraType (void)
virtual void viewAll (void)
virtual void saveHomePosition (void)
virtual void resetToHomePosition (void)
virtual void setHeadlight (SbBool enable)
SbBool isHeadlight (void) const
SoDirectionalLight * getHeadlight (void) const
virtual void setDrawStyle (SoQtViewer::DrawType type, SoQtViewer::DrawStyle style)
SoQtViewer::DrawStyle getDrawStyle (const SoQtViewer::DrawType type) const
virtual void setBufferingType (SoQtViewer::BufferType type)
SoQtViewer::BufferType getBufferingType (void) const
virtual void setViewing (SbBool enable)
SbBool isViewing (void) const
virtual void setCursorEnabled (SbBool enable)
SbBool isCursorEnabled (void) const
void setAutoClipping (SbBool enable)
SbBool isAutoClipping (void) const
void setAutoClippingStrategy (const AutoClippingStrategy strategy, const float value=0.6f, SoQtAutoClippingCB *cb=NULL, void *cbuserdata=NULL)
virtual void setStereoViewing (SbBool enable)
SbBool isStereoViewing (void) const
virtual void setStereoOffset (const float dist)
float getStereoOffset (void) const
SbBool setStereoType (SoQtViewer::StereoType s)
SoQtViewer::StereoType getStereoType (void) const
void setAnaglyphStereoColorMasks (const SbBool left[3], const SbBool right[3])
void getAnaglyphStereoColorMasks (SbBool left[3], SbBool right[3])
void setDetailSeek (const SbBool enable)
SbBool isDetailSeek (void) const
void setSeekTime (const float seconds)
float getSeekTime (void) const
void addStartCallback (SoQtViewerCB *func, void *data=NULL)
void addFinishCallback (SoQtViewerCB *func, void *data=NULL)
void removeStartCallback (SoQtViewerCB *func, void *data=NULL)
void removeFinishCallback (SoQtViewerCB *func, void *data=NULL)
void setWireframeOverlayColor (const SbColor &color)
const SbColor & getWireframeOverlayColor (void) const
virtual void setDoubleBuffer (const SbBool enable)
virtual void setSceneGraph (SoNode *root)
virtual SoNode * getSceneGraph (void)

Protected Member Functions

SoQtViewer (QWidget *parent, const char *name, SbBool embed, Type type, SbBool build)
~SoQtViewer ()
virtual void sizeChanged (const SbVec2s &size)
virtual void setSeekMode (SbBool enable)
SbBool isSeekMode (void) const
SbBool seekToPoint (const SbVec2s screenpos)
void seekToPoint (const SbVec3f &scenepos)
virtual void computeSeekFinalOrientation (void)
virtual void actualRedraw (void)
virtual SbBool processSoEvent (const SoEvent *const event)
void interactiveCountInc (void)
void interactiveCountDec (void)
int getInteractiveCount (void) const
void setSeekDistance (const float distance)
float getSeekDistance (void) const
void setSeekValueAsPercentage (const SbBool on)
SbBool isSeekValuePercentage (void) const
virtual void changeCameraValues (SoCamera *camera)
void addSuperimposition (SoNode *scene)
void removeSuperimposition (SoNode *scene)
void setSuperimpositionEnabled (SoNode *scene, const SbBool enable)
SbBool getSuperimpositionEnabled (SoNode *scene) const

Additional Inherited Members

Detailed Description

The SoQtViewer class is the top level base viewer class.

This is an abstract class, which adds the following features to its SoQtRenderArea superclass: convenient methods for camera handling, an automatic headlight configuration.

As for the camera handling: when setting a new scene graph for the viewer, the scene graph will automatically be scanned for a node derived from SoCamera. If not found, the viewer will itself set up a camera for the scene. The camera can then be conveniently controlled by the application programmers in many aspects:

Note that there is no dragger or manipulator attached to the scene camera. The camera transform manipulation is calculated in a more direct manner in the non-abstract viewer classes inheriting SoQtViewer by reading mouse and keyboard events and interpreting how these should influence the camera. The calculations results in new values for SoCamera::position, SoCamera::orientation, and the other SoCamera field values for the camera designated to be the viewer viewpoint camera. These values are then inserted directly into the viewer's SoCamera node.

See e.g. the source code for SoQtExaminerViewer::processSoEvent() for the details.

The SoQtViewer class automatically adds a headlight to the scene, which will always point in the approximate same direction as the current viewer camera, thereby securing that the scene geometry is always lighted and visible. (If you don't want the constant headlight, but rather want to light the scene on your own, this behavior can be turned off with SoQtViewer::setHeadlight()).

SoQtViewer-derived viewers all inherit the following keyboard controls from this class (but only when the viewer is in 'examine mode', i.e. SoQtViewer::isViewing() returns TRUE):


Member Enumeration Documentation

enum SoQtViewer::Type

Hints about what context the viewer will be used in. Usually not very interesting for the application programmer, it doesn't matter much which value is used for the viewer type. This 'feature' of the viewer is included just to be compatible with the old SGI Inventor API.



If a user-supplied scene graph passed into the setSceneGraph() function does not contain a camera, setting the viewer type to BROWSER will make the viewer in that case automatically set up a camera outside the scene, as part of the viewer's private and hidden 'supergraph'.


If a user-supplied scene graph passed into the setSceneGraph() function does not contain a camera, setting the viewer type to EDITOR will make the viewer in that case automatically set up a camera in the user-supplied scene.

So if you want to avoid having the SoQtViewer class muck about with your supplied scene graph, set the type-flag to SoQtViewer::BROWSER instead, which makes an inserted camera node go into the viewer's own 'wrapper' scene graph instead.

enum SoQtViewer::DrawStyle

Decides draw style for a scene with either a still camera or an animating camera.

See also

SoQtViewer::setDrawStyle(), SoQtViewer::DrawType



Normal rendering, draws all scene geometry in its original style.


Draw scene in 'hidden line' mode: that is, as wireframe with no 'see-through'.

Note that this is actually an expensive way to render, as the scene must be rendered twice to achieve the effect of hiding lines behind the invisible geometry.


Render scene without textures.


Render all 'complex' shape types with low complexity to improve rendering performance.


View all polygon geometry in wireframe mode.


Render only the vertex positions of the geometry.


View the scene's bounding boxes, instead of rendering the full geometry.

A very efficient way of optimizing rendering performance for scenes with high primitive counts while moving the camera about is to set this mode for the SoQtViewer::INTERACTIVE DrawType.


Render as wireframe and don't bother with getting them rendered correctly in depth.


Render as vertex points and don't bother with getting them rendered correctly in depth.


Always render a scene with an animating camera (i.e. SoQtViewer::INTERACTIVE DrawType) in the same manner as scene with a still camera.


Render the scene as normal, but overlay a set of lines showing the contours of all polygons.

enum SoQtViewer::DrawType

Contains valid values for the first argument to the SoQtViewer::setDrawStyle() call. Decides the effect of the second argument.

See also

SoQtViewer::setDrawStyle(), SoQtViewer::DrawStyle



If this value is passed as the first argument of SoQtViewer::setDrawStyle(), the second argument decides which draw style to use when the viewer camera is standing still in the same position with the same orientation -- i.e. when the end user is not interacting with the scene camera.


If this value is passed as the first argument of SoQtViewer::setDrawStyle(), the second argument decides which draw style to use when the end user is interacting with the scene camera, causing continuous animation redraws.

enum SoQtViewer::BufferType

Set of valid values for SoQtViewer::setBufferingType().



Change underlying OpenGL canvas to be single buffered.


Change underlying OpenGL canvas to be double buffered.


Set up so animation rendering is done in a double buffered OpenGL canvas, but ordinary rendering happens directly in the front buffer.

This mode can be useful with absurdly large scenes, as the rendering will visibly progress, and one will avoid having the end user wonder why nothing is happening while the scene is rendered to the back buffer in the default SoQtViewer::BUFFER_DOUBLE mode.

enum SoQtViewer::AutoClippingStrategy

Enum for auto clipping strategy.

See also




Variable near plane auto clipping strategy. Explained in detail in the documentation for the SoQtViewer::setAutoClippingStrategy() method.


Constant near plane auto clipping strategy. Explained in detail in the documentation for the SoQtViewer::setAutoClippingStrategy() method.

enum SoQtViewer::StereoType

Contains list of supported stereo rendering techniques.

See also




Use monoscopic rendering.


Render stereo by superimposing two images of the same scene, but with different color filters over the left and right view (or 'eye').

This is a way of rendering stereo which works on any display, using color-filter glasses. Such glasses are usually cheap and easy to come by.

See also



Render stereo by using OpenGL quad-buffers. This is the most common interface for stereo rendering for more expensive hardware devices, such as shutter glasses and polarized glasses.

The well known Crystal Eyes glasses are commonly used with this type of stereo display.


Interleaving / interlacing rows from the left and right eye is another stereo rendering method requiring special hardware. One example of a provider of shutter glasses working with interleaved glasses is VRex:


Basically the same technique as SoQtViewer::STEREO_INTERLEAVED_ROWS, but vertical lines are interleaved / interlaced, instead of horizontal lines.

Constructor & Destructor Documentation

SoQtViewer::SoQtViewer (QWidget * parent, const char * name, SbBool embed, SoQtViewer::Type t, SbBool build) [protected]

Constructor. parent, name and embed are passed on to SoQtRenderArea, so see the documentation for our parent constructor for for more information on those.

The t type setting hints about what context the viewer will be used in. Usually not very interesting for the application programmer, but if you want to make sure the SoQtViewer class doesn't muck about with your supplied scene graph, set the type-flag to SoQtViewer::BROWSER. (This 'feature' of the viewer is included just to be compatible with the old SGI Inventor API.)

The build flag decides whether or not to delay building the widgets / window which is going to make up the components of the viewer.

SoQtViewer::~SoQtViewer () [protected]


Member Function Documentation

void SoQtViewer::setCamera (SoCamera * cam) [virtual]

Set the camera we want the viewer to manipulate when interacting with the viewer controls.

The camera passed in as an argument to this method must already be part of the viewer's scene graph. You do not inject viewpoint cameras to the viewer with this method.

You should rather insert a camera into the scene graph first (if necessary, often one will be present already), then register it as the camera used by the viewer controls with this method.

If the application code doesn't explicitly set up a camera through this method, the viewer will automatically scan through the scene graph to find a camera to use. If no camera is available in the scene graph at all, it will set up its own camera.

See also


Reimplemented in SoQtExaminerViewer, SoQtFlyViewer, SoQtPlaneViewer, and SoQtConstrainedViewer.

SoCamera * SoQtViewer::getCamera (void) const

Returns the camera currently used by the viewer for the user's main viewpoint.

It is possible that this function returns NULL, for instance if there's no scene graph present in the viewer. (This is mostly meant as a note for developers extending the SoQt library, as application programmers usually controls if and when a viewer contains a scene graph, and therefore know in advance if this method will return a valid camera pointer.)

See also


void SoQtViewer::setCameraType (SoType t) [virtual]

When the viewer has to make its own camera as a result of the graph passed to setSceneGraph() not containing any camera nodes, this call can be made in advance to decide which type the camera will be of.

Default is to use an SoPerspectiveCamera.

If this method is called when there is a scene graph and a camera already set up, it will delete the old camera and set up a camera with the new type if the t type is different from that of the current camera.

See also


Reimplemented in SoQtFlyViewer.

SoType SoQtViewer::getCameraType (void) const

Returns camera type which will be used when the viewer has to make its own camera.

Note that this call does not return the current camera type, as one might expect. Use getCamera() and SoType::getTypeId() for that inquiry.

See also


void SoQtViewer::toggleCameraType (void) [virtual]

If the current camera is of perspective type, switch to orthographic, and vice versa.

Automatically calls SoQtViewer::setCameraType() so the change will immediately take place.

void SoQtViewer::viewAll (void) [virtual]

Reposition the current camera so we can see the complete scene.

Reimplemented in SoQtFlyViewer.

void SoQtViewer::saveHomePosition (void) [virtual]

Store the current camera settings for later retrieval with resetToHomePosition().

See also


Reimplemented in SoQtConstrainedViewer.

void SoQtViewer::resetToHomePosition (void) [virtual]

Restore the saved camera settings.

See also


Reimplemented in SoQtConstrainedViewer, and SoQtFlyViewer.

void SoQtViewer::setHeadlight (SbBool on) [virtual]

Turn the camera headlight on or off.

Default is to have a headlight turned on.

See also

isHeadlight(), getHeadlight()

SbBool SoQtViewer::isHeadlight (void) const

Returns status of the viewer headlight, whether it is on or off.

See also

setHeadlight(), getHeadlight()

SoDirectionalLight * SoQtViewer::getHeadlight (void) const

Returns the a pointer to the directional light node which is the viewer headlight.

The fields of the node is available for user editing.

See also

isHeadlight(), setHeadlight()

void SoQtViewer::setDrawStyle (SoQtViewer::DrawType type, SoQtViewer::DrawStyle style) [virtual]

Set up a drawing style. The type argument specifies if the given style should be interpreted as the draw style during animation or when the camera is static.

Default values for the drawing style is to render the scene 'as is' in both still mode and while the camera is moving.

See the documentation for the DrawType and DrawStyle for more information.

See also


SoQtViewer::DrawStyle SoQtViewer::getDrawStyle (const SoQtViewer::DrawType type) const

Return current draw styles for the given type (STILL or INTERACTIVE).

See also


void SoQtViewer::setBufferingType (SoQtViewer::BufferType type) [virtual]

Set the viewer's buffer type. Available types are SoQtViewer::BUFFER_SINGLE, SoQtViewer::BUFFER_DOUBLE and SoQtViewer::BUFFER_INTERACTIVE.

(With a buffer type of SoQtViewer::BUFFER_INTERACTIVE, the viewer will render with double buffering during user interaction and with single buffering otherwise.)

Default is SoQtViewer::BUFFER_DOUBLE.

See also


SoQtViewer::BufferType SoQtViewer::getBufferingType (void) const

Return the viewer's buffer type.

See also


void SoQtViewer::setViewing (SbBool enable) [virtual]

Set view mode.

If the view mode is on, user events will be caught and used to influence the camera position / orientation. If view mode is off, all events in the viewer canvas (like for instance keypresses or mouse clicks and -movements) will be passed along to the scene graph.

Default is to have the view mode active.

See also


Reimplemented in SoQtExaminerViewer, SoQtFlyViewer, SoQtPlaneViewer, and SoQtFullViewer.

SbBool SoQtViewer::isViewing (void) const

Return state of view mode.

TRUE means that the mode of the viewer is set such that user interaction with the mouse is used to modify the position and orientation of the camera.

See also


void SoQtViewer::setCursorEnabled (SbBool on) [virtual]

Set whether or not the mouse cursor representation should be visible in the viewer canvas.

Default value is on.

See also


Reimplemented in SoQtExaminerViewer, SoQtFlyViewer, and SoQtPlaneViewer.

SbBool SoQtViewer::isCursorEnabled (void) const

Returns visibility status of mouse cursor.

See also


void SoQtViewer::setAutoClipping (SbBool enable)

Turn on or off continuous automatic adjustments of the near and far clipping planes.

If on, the distance from the camera position to the near and far planes will be calculated to be a 'best fit' around the geometry in the scene, to maximize the 'stretch' of values for the visible geometry in the z-buffer. This is important, as z-buffer resolution is usually limited enough that one will quickly see flickering in the rasterization of close polygons upon lousy utilization of the z-buffer.

Automatic calculations of near and far clip planes are on as default.

For better control over what happens in boundary conditions (for instance when the distance between near and far planes get very far, or if geometry gets very close to the camera position), it is possible to use the SoQtViewer::setAutoClippingStrategy() method to fine-tune the near/far clipping plane settings.

On a major note, be aware that turning auto-updating of near and far clip planes off have a potentially serious detrimental effect on performance, due to an important side effect: updating the near and far clip planes triggers an SoGetBoundingBoxAction to traverse the scene graph, which causes bounding boxes to be calculated and stored in caches. The bounding box caches are then used by the SoGLRenderAction traversal for view frustum culling operations. With no bounding box caches, the rendering will not do culling, which can cause much worse performance. Kongsberg Oil & Gas Technologies are working on correcting this problem properly from within the Coin library.

On a minor note, be aware that notifications will be temporarily turned off for the scene's SoCamera when changing the near and far clipping planes (which is done right before each redraw). This is done to avoid notifications being sent through the scene graph right before rendering, as that causes some latency. It is mentioned here in case you have any client code which for some reason needs to sense all changes to the scene camera. This is however unlikely, so you can very probably ignore this.

See also


SbBool SoQtViewer::isAutoClipping (void) const

Return value of the automatic near/far clip plane adjustment indicator.

See also


void SoQtViewer::setAutoClippingStrategy (const AutoClippingStrategy strategy, const float value = 0.6f, SoQtAutoClippingCB * cb = NULL, void * cbuserdata = NULL)

Set the strategy used for automatic updates of the distances to the near and far clipping planes.

When auto clipping is enabled, the near plane distance is calculated so that it is just in front of the scene bounding box. If this near plane is behind or very close to the projection point, one of the following strategies will be used to calculate the new clipping plane.

The VARIABLE_NEAR_PLANE strategy considers the number of z buffer bits available for the current OpenGL context, and uses value to calculate the number of bits that is lost because of the far/near ratio. value should be in the range [0.0, 1.0]. A higher value will increase the z-buffer precision, but also push the near plane further away from the projection point.

The CONSTANT_NEAR_PLANE strategy simply sets the near plane to value. If value at some point approaches the far clipping plane distance, the near plane distance will be set to far plane distance divided by 5000.0.

The default strategy is VARIABLE_NEAR_PLANE.

It is also possible to register a callback method cb, which will then be invoked after the near and far clipping planes have been calculated by the SoQtViewer code. The callback can then adjust the values for the distance to the near and far planes to exactly match the needs of the application (for instance at specific parts in the scene), to limit the distance to either plane, or whatever else needs to be controlled.

The signature of the SoQtAutoClippingCB callback must match:

SbVec2f myfunc(void * data, const SbVec2f & nearfar);

The first argument is the cbuserdata passed in along with the callback function pointer itself (i.e. the callback function's closure). The second argument are the near and far clipping plane distances from the camera position, as calculated internally by the viewer, including 'slack'.

The function callback can then modify the near and far clipping plane distances to what will actually be used by the viewer. These values will then be used unmodified for the viewer's camera.

This is a good way of dynamically modifying the near and far distances such that they at all times exactly matches the specific layout of the application scene, for instance with regard to the trade-off between z-buffer resolution and how early geometry is clipped at the near plane (or at the far plane).

Note that the internal near/far calculations should be good enough for the vast majority of scenes. Application programmers should only need to set up their own adjustments upon 'unusual' scenes, like for instance scenes with a large world space, but where one would still like to be able to get up extremely close on details in some parts of the scene.

See also


void SoQtViewer::setStereoViewing (SbBool enable) [virtual]

Turn stereo viewing on or off.

Note: this function is being obsoleted, you should use the setStereoType() function instead.

Coin does 'correct' stereo rendering, using the method known as 'parallel axis asymmetric frustum perspective projection'. For more information, see this link:

See also

isStereoViewing(), setStereoType()

SbBool SoQtViewer::isStereoViewing (void) const

Returns a boolean indicating whether or not we're in stereo viewing mode.

NOTE: in the original InventorXt API, this method was virtual. It is not virtual here.

See also

setStereoViewing(), getStereoType()

void SoQtViewer::setStereoOffset (const float dist) [virtual]

Set the offset between the two viewpoints when in stereo mode. Default value is 0.1.

NOTE: In the original InventorXt API, this method was not virtual.

See also


float SoQtViewer::getStereoOffset (void) const

Return the offset distance between the two viewpoints when in stereo mode.

See also


SbBool SoQtViewer::setStereoType (SoQtViewer::StereoType s)

Set up stereo rendering.

Coin does 'correct' stereo rendering, using the method known as 'parallel axis asymmetric frustum perspective projection'. For more information, see this link:

Note: it is preferred that one uses this function for control of which type of stereo rendering to use, instead of the older SoQtViewer::setStereoViewing() and SoQtGLWidget::setQuadBufferStereo() functions.

The default is to do monoscopic rendering, i.e. the default SoQtViewer::StereoType value is SoQtViewer::STEREO_NONE.

See also

SoQtViewer::StereoType, SoCamera::setStereoAdjustment


SoQt 1.2

SoQtViewer::StereoType SoQtViewer::getStereoType (void) const

Returns the current type of stereo rendering used (or SoQtViewer::STEREO_NONE if monoscopic).

void SoQtViewer::setAnaglyphStereoColorMasks (const SbBool left[3], const SbBool right[3])

If display is configured to render in anaglyph stereo, this function can be used to control which filter is used for each eye.

The default filters are red (i.e. color vector [TRUE,FALSE,FALSE]) for the left eye, and cyan (color vector [FALSE,TRUE,TRUE]) for the right eye.

See also

SoQtViewer::StereoType, setStereoType()

void SoQtViewer::getAnaglyphStereoColorMasks (SbBool left[3], SbBool right[3])

Returns color masks for left and right eye filters in anaglyph stereo.

See also


void SoQtViewer::setDetailSeek (const SbBool on)

Toggle between seeking to a point or seeking to an object.

Default is to seek to a point.

See also


SbBool SoQtViewer::isDetailSeek (void) const

Returns a


Wed Jul 20 2022 Version 1.6.0 SoQt