Doxygen Awesome (original) (raw)

The SoWin library is a C++ GUI toolkit that binds together the Coin rendering library with the user interface parts of the Microsoft Windows Win32 API, thereby providing application programmers a convenient method of using the Coin library from Microsoft Windows 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 Programming 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)

{

HWND mainwin = SoWin::init(argc, argv, argv[0]);

SoSeparator * root = new SoSeparator;

root->ref();

SoBaseColor * col = new SoBaseColor;

col->rgb = SbColor(1, 1, 0);

root->addChild(col);

root->addChild(new SoCone);

delete eviewer;

root->unref();

return 0;

}

virtual void show(void)

Definition SoWinComponent.cpp:368

The SoWinExaminerViewer class is a 3D-model examination viewer.

Definition SoWinExaminerViewer.h:50

virtual void setSceneGraph(SoNode *root)

Definition SoWinViewer.cpp:2841

static void done(void)

Definition SoWin.cpp:417

static HWND init(const char *appname, const char *classname="SoWin")

Definition SoWinCommon.cpp:173

static void show(HWND const widget)

Definition SoWin.cpp:456

static void mainLoop(void)

Definition SoWin.cpp:375

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 single buffered versus double buffered 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 scene graph 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 light sources 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](classSoWinFlyViewer.html "The SoWinFlyViewer class implements controls for moving the camera in a "flying" motion.") (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 Kongsberg Oil & Gas Technologies.

The SoWin API is based on and closely matches the InventorXt library API, originally developed by SGI. This should make it straightforward 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 https://coin3d.github.io.