SoQt Documentation

SoQt is a library which provides the glue between Systems in Motion's Coin high-level 3D visualization library and the Qt 2D user interface library.

Qt is a C++ toolkit for multiplatform development of 2D user interfaces, and also includes other functionality to help programmers write multiplatform applications. Qt is currently available on X11-based systems (UNIX, Linux and BSDs), MSWindows, Mac OS X and embedded systems.

For more information on the Qt toolkit, see the web site for Qt: http://www.qt.io.

By using the combination of Coin, Qt and SoQt for your 3D applications, you have a framework for writing completely portable software across the whole range of UNIX, Linux, Microsoft Windows and Mac OS X operating systems. Coin, Qt and SoQt makes this possible from a 100% common codebase, which means there is a minimum of hassle for developers when working on multiplatform software, with the resulting large gains in productivity.

SoQt, like Coin and Qt, provides the programmer with a high-level application programmer's interface (API) in C++. The library primarily includes a class-hierarchy of viewer components of varying functionality and complexity, with various modes for the end-user to control the 3D-scene camera interaction.

For a small, completely stand-alone usage example on how to initialize the library and set up a viewer instance window, see the following code:

#include <Inventor/Qt/SoQt.h>
#include <Inventor/Qt/viewers/SoQtExaminerViewer.h>
#include <Inventor/nodes/SoBaseColor.h>
#include <Inventor/nodes/SoCone.h>
#include <Inventor/nodes/SoSeparator.h>

int
main(int argc, char ** argv)
{
  // Initializes SoQt library (and implicitly also the Coin and Qt
  // libraries). Returns a top-level / shell Qt window to use.
  QWidget * mainwin = SoQt::init(argc, argv, argv[0]);

  // Make a dead simple scene graph by using the Coin library, only
  // containing a single yellow cone under the scenegraph root.
  SoSeparator * root = new SoSeparator;
  root->ref();

  SoBaseColor * col = new SoBaseColor;
  col->rgb = SbColor(1, 1, 0);
  root->addChild(col);

  root->addChild(new SoCone);

  // Use one of the convenient SoQt viewer classes.
  SoQtExaminerViewer * eviewer = new SoQtExaminerViewer(mainwin);
  eviewer->setSceneGraph(root);
  eviewer->show();

  // Pop up the main window.
  SoQt::show(mainwin);
  // Loop until exit.
  SoQt::mainLoop();

  // Clean up resources.
  delete eviewer;
  root->unref();
  SoQt::done();

  return 0;
}

As compiled and run, this example provides the end-user with a full fledged 3D viewer. The viewer automatically contains mouse interaction handling logic to let the end-user "examine" the 3D-model / scene (since this is the SoQtExaminerViewer class), plus toolbar controls on the right-side decorations border for often used controls:

The SoQt library contains several such high-level classes as the SoQtExaminerViewer used in the above example. These are primarily used for doing Rapid Application Development (RAD) of new concepts and ideas for your 3D system. The "real" application will typically use one of the lower-complexity classes higher up in the inheritance hierarchy, such as the SoQtRenderArea, which provides the application programmer with full control over the user interface components and general layout to present for the end-user, as suitable for the specific application needs.

This is how the SoQt library fits in with the other system components:

As can be seen from the above figure, SoQt builds on Systems in Motion's Coin library for the 3D graphics, and the Qt library for the 2D user interface components and the OpenGL canvas binding.

The additional functionality provided by SoQt over Coin and Qt is:

• The most convenient management of OpenGL context types, such as singlebuffered versus doublebuffered rendering, the use of overlay planes, stereo rendering, etc. This is handled through the SoQtGLWidget class, which builds on Qt's QGLWidget class, and through the SoQtRenderArea class (which contains the main binding into the Coin library's main data structures).

• The translation of native Qt interaction device events (from e.g. the mouse or the keyboard) into the Coin library's event types. The translation is done by the SoQtDevice classes, controlled by the SoQtRenderArea.

  These "generic" Coin events are then passed into the 3D scenegraph for further processing, for instance by Coin's 3D user interaction components – like this "trackball manipulator" attached to a simple cone:

  

• Some abstract viewer classes, like the SoQtViewer and SoQtFullViewer, which provides additional services on top of the SoQtRenderArea for assisting the application programmer in convenient handling of cameras and light sources in the 3D scene (by the SoQtViewer), plus adding the basic, common user interface components (by the SoQtFullViewer).

• A set of high-level viewer classes, as has been presented by the SoQtExaminerViewer in the above source code example. There are currently three different non-abstract viewer classes to choose from: the SoQtExaminerViewer (a plain model viewer), the SoQtFlyViewer (for fly-throughs in larger 3D scenes) and the SoQtPlaneViewer (for CAD-style viewing and interaction along the 3 principal axes).

SoQt is released publicly under the 3-clause BSD license.

For those who are using the implementations of the Inventor API from either SGI or TGS, we would like to point out that SoQt can also be used on top of either of those libraries instead of the Coin library from Kongsberg Oil & Gas Technologies.

The SoQt API is based on and closely matches the InventorXt library API, originally developed by SGI. This should make it straightforward to port InventorXt code over to SoQt, for instance to gain greater portability.

See also

The documentation for the Coin library: https://coin3d.bitbucket.io/Coin/.