SoWin Documentation

1.4.1a

The SoWin library is a C++ GUI toolkit that binds together the Coin rendering library with the user interface parts of the MSWindows Win32 API, thereby providing application programmers a convenient method of using the Coin library from MSWindows development environments.

By using the combination of Coin and SoWin for your 3D applications, you have a complete framework for writing software for Microsoft Windows operating systems.

SoWin, like Coin, 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/Win/SoWin.h>
  #include <Inventor/Win/viewers/SoWinExaminerViewer.h>
  #include <Inventor/nodes/SoBaseColor.h>
  #include <Inventor/nodes/SoCone.h>
  #include <Inventor/nodes/SoSeparator.h>
  
  int
  main(int argc, char ** argv)
  {
    // Initializes SoWin library (and implicitly also the Coin
    // library). Returns a top-level / shell window to use.
    HWND mainwin = SoWin::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 SoWin viewer classes.
    SoWinExaminerViewer * eviewer = new SoWinExaminerViewer(mainwin);
    eviewer->setSceneGraph(root);
    eviewer->show();
  
    // Pop up the main window.
    SoWin::show(mainwin);
    // Loop until exit.
    SoWin::mainLoop();

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

    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 SoWinExaminerViewer class), plus toolbar controls on the right-side decorations border for often used controls:

The SoWin library contains several such high-level classes as the SoWinExaminerViewer 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 SoWinRenderArea, 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 SoWin library fits in with the other system components:

As can be seen from the above figure, SoWin builds on Systems in Motion's Coin library for the 3D graphics, and the standard Microsoft Windows Win32 API for the 2D user interface components.

The additional functionality provided by SoWin over Coin 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 SoWinGLWidget class and through the SoWinRenderArea class (which contains the main binding into the Coin library's main data structures).

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

  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 SoWinViewer and SoWinFullViewer, which provides additional services on top of the SoWinRenderArea for assisting the application programmer in convenient handling of cameras and lightsources in the 3D scene (by the SoWinViewer), plus adding the basic, common user interface components (by the SoWinFullViewer).

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

For those who are using the implementation of the Inventor API from SGI, we would like to point out that SoWin can also be used on top of that library instead of the Coin library from Systems in Motion.

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

For more information about the Coin3D family of libraries, including licensing information, please visit the Coin3D web site <http://www.coin3d.org>.

See also:

The documentation for the Coin library: <http://doc.coin3d.org/Coin>.