PROGRAMMING Coin 3D

Interactive 3D Worlds with Coin and Qt Virtual World

Qt and Coin, an Open Inventor clone, design particularly simpli- fies programming in make the programming of interactive C++. Open Inventor itself uses OpenGL to 3D worlds a lot easier than OpenGL render graphics and thus inherits its supe- ever has. Speed of image rendering rior quality and speed. is not always the critical requirement. The toolkit is far more than just a library Quick and easy to follow program- that provides classes for creating 3D graphics. Open ming may produce better results. Inventor allows you to describe and store 3D scenes in BY STEPHAN SIEMEN so-called scene graphs, for exam- ple. The file format developed for this purpose was used as a template for VRML (Virtual Reality Modelling Language) in 1994. Open Inventor also or most people OpenGL, immedi- allows interaction with the scene. The ately spring to mind when it comes scene graphs can be used to identify the Fto programming 3D worlds. Often objects and thus define appropriate Open Inventor by SGI or the compatible reactions. Coin (see “Open Inventor and Coin”) are Unfortunately, Coin and SoQt are not The command binds the Coin and SoQt a better choice: OpenGL may render included with every Linux distribution libraries and uses the “-I$QTDIR/ graphics quickly, but it does involve (see the “Installation” insert). Both include” option to specify the location of complex and time-consuming program- packages contain exhaustive documen- the Qt header files. The results are ming. OpenGL’s structure and tation. shown in Figure 2. commands are closely oriented on graphics hardware. Compared to Open 3D Graphics with a GUI Discovering and Exploring Inventor, OpenGL is on the same level as The biggest difference between program- Virtual Worlds Assembler. ming with Open Inventor and Coin is the The “SoQtExaminerViewer” class (line The object oriented Open Inventor GUI integration. The following examples 31) provides a variety of functions that Toolkit was developed in 1991 by the use SoQt to interface with the Qt library, allow you to view various sections of the same SGI programmers that produced Motif variants are available from [7]. scene. The graphic follows mouse move- OpenGL. Open Inventor maps the func- With the exception of the SoQt compo- ments if you hold down the left mouse tionality of OpenGL to objects. The nents, all of these examples also run on button. The viewer provides alternative SGI’s Open Source Variant of Open views of the scene via the wheels and Coin Inventor; thus the names Coin and Open buttons on the window borders. Manufacturer: Systems in Motion Inventor are interchangeable in the fol- The three wheels are particularly inter- lowing sections. esting: two of them are in the bottom left License: LGPL (GPL for Version 2.0 planned) As befits a programming tutorial, our corner, and another is located on the Stable Version: Coin 1.0.3,SoQt 1.0.1 first example will be a Hello World pro- lower right. The right wheel, or dolly, Coin Professional: Commercial license (per gram. It initializes a viewer and displays influences the distance between the user developer and year 2000 US dollars),suit- a three dimensional text. The user can and the scene (zoom effect). The two able for proprietary projects view the text from any arbitrary position. wheels on the left rotate the scene about Multi platform support: Coin runs on Linux, The code is shown in Listing 1 and can its x or y axis. other Unix type systems and Windows; you be downloaded from [7]. The following need a C++ compiler and an OpenGL library command compiles the program: Discovery Tools GUI Bindings: Currently supports Qt,Gtk+, A total of seven buttons are located Motif and Windows; Coin can be used with- g++ HelloSoQt.cpp -o HelloSoQt U above the dolly wheel on the right win- out these bindings -lCoin -lSoQt -I$QTDIR/include dow margin:

72 March 2003 www.linux-magazine.com Coin 3D PROGRAMMING

Application

Motif SoQt SoXt Coin - Open Qt Inventor Qt-GL

OpenGL

Operating System

Hardware

Figure 1:The Coin library mediates between the application and OpenGL. Figure 2:The sample Hello SoQt program is shown in the viewer.The user SoQt is used to bind the Qt GUI toolkit while SoXt is an alternative for Motif can alter the viewing position

• Arrow: Edit mode mode is automatically enabled on objects in a scene. The elements of the • Hand: Interactive mode launching the viewer and allows the user scene graph are nodes, which contain • House: Reset camera position to to modify the camera position and angle various functions. Each of these nodes default as required using the GUI wheels and the describes part of the image scene. •Blue House: Set a camera position mouse. Additional settings are available When calculating and rendering a (viewer angle) as the new default posi- in the pop-up menu (right click). scene, Open Inventor works its way tion methodically from the root to the leaves •Eye: View the whole scene The Scene Graph: Managing (the lowest nodes) of the scene graph, • Lamp: Set the focus for the zoomer 3D Objects left to right and top down. (dolly) Open Inventor uses scene graphs for the Special nodes are used to permit addi- •Box: Toggles various transformations. efficient management of 3D scenes (3D tional modifications, such as All of these interactions move the cam- worlds). The scene graph has a tree transformations and rotation. These era and not the scene itself. Interactive structure whose roots allow access to the modifications affect any subordinate

Listing 1:“HelloSoQt.cpp” 01 // SoQt header files 24 02 #include 25 // Create a text 03 #include 26 SoText3 *text3D = new SoText3(); 04 27 text3D->string.setValue("Hello SoQt"); 05 // Coin header files 28 root->addChild(text3D); 06 #include 29 07 #include 30 // Create a viewer 08 #include 31 SoQtExaminerViewer *b = new 09 SoQtExaminerViewer(window); 10 int main(int argc, char **argv) 32 b->setSceneGraph(root); 11 { 33 b->show(); 12 // Initialize SoQt library. 34 13 // The return value points to a Qt window 35 // Start the window 14 QWidget *window = SoQt::init("test"); 36 SoQt::show(window); 15 37 // Loop until exit. 16 // Create a "scene graph" 38 SoQt::mainLoop(); 17 SoSeparator *root = new SoSeparator; 39 18 root->ref(); 40 // Delete viewer and reference for scene 19 41 delete b; 20 // Set the RGB color. Yellow in this case 42 root->unref(); 21 SoBaseColor *color = new SoBaseColor; 43 22 color->rgb = SbColor(1, 1, 0); 44 return 0; 23 root->addChild(color); 45 }

www.linux-magazine.com March 2003 73 PROGRAMMING Coin 3D

available as PDF documents under [3]

chair (enter the document name you require in the search box) In the case of Coin and its extensions seat front legs back legs back (such as SoQt) the documentation is included in the source code. You can use right right left left Doxygen to generate a HTML overview.

seat color seat surface displacement 5rot back color se ation at back Inserting a New Node The following example inserts a new displacement displacement 2 displacement 3 displacement 4 node into a scene graph: leg leg 2 SoCone *cone = new SoCone; hcone->height.setValue(4); cone->parts.setValue("SIDES"); leg color post post 2 root->addChild(cone) Transformation Separator Appearance/Design Geometry This creates an object of the desired Figure 3:The scene graph divides the chair into its components:seat, front and hind legs as well as lean class (“SoCone” in this case) and defines angle.The left and right legs differ only by their position values for some fields. In our example nodes. At this point a similarity to the active operations or describe various Open Inventor and Coin OpenGL status machine becomes appar- transformations. In 1996 SGI handed over the development ent. A property, for example the color of of Open Inventor as of version 2.1 to TGS [2]. a 3D object (class “SoBaseColor”) Nodes: Shapes, Colors, This company develops and distributes the remains active until a new value is Materials and Light latest version (currently 3.1) commercially.In assigned to the property. Each node is described in a class. The August 2000 SGI decided to publish its own The programmer can organize the name of a node class starts with “So”, as Open Source Open Inventor version (2.1) for objects in the scene graph to manipulate in “SoMaterial” or “SoCone”. The “So” Linux [1]. the appearance and behavior of the gen- prefix is omitted when describing a The Norwegians,Systems in Motion [4], erated scene. scene in a file. Node names are VRML offer an implementation of their own,called The order of the effects is important. like in this case. Coin [5],for Windows,Linux and other Unix systems. Coin is currently available Replacing a rotation with a translation Each class comprises of fields that under the LGPL license (version 1.x), will lead to different generated results. characterize the properties of the node. although version 2.0 is due to be released Open Inventor offers a variety of node The SGI documentation details the fields under GPL. types that can define surfaces, describe available in each node type: the “Open materials or adjust the camera lighting. Inventor Nodes Quick Reference” and More Dynamism with Coin Other nodes provide interfaces for inter- “Open Inventor C++ Reference” are Coin was chosen for this article – its devel- opment promises more dynamism than Table 1 Shape Classes the SGI variant. Coin attempts to implement the new Open Inventor 3.x features, Nodename Meaning Fields Standard values whereas SGI has merely ported Open SoCone Cone parts ALL (SIDES,BOTTOM) Inventor 2.1 to Linux.The various extensions bottomRadius 1 provided by SIM are another good reason height 2 for choosing Coin. In addition to the SoCube Cube width 1 standard Motif binding,it also supports height 1 Qt,Gtk and Java. depth 1 These bindings are important since Open SoCylinder Cylinder parts ALL (SIDES,TOP,BOTTOM) Inventor merely describes the 3D scene; the radius 1 programmer must provide the window height 2 frame and the binding to the window SoSphere Sphere radius 1 manager. OpenGL provides the GLUT SoText2 2D text string Empty string extension for this purpose,whereas spacing 1 Open Inventor decided on Motif to simplify justification LEFT (RIGHT,CENTER) this task. However,alternatives such as Gtk SoTest3 3D text string Empty string and Qt are simpler and more commonly spacing 1 available for Linux than Motif. Qt matches justification LEFT (RIGHT,CENTER) Coin perfectly,as both are implemented parts FRONT (SIDES,ALL,BACK) in C++.

74 March 2003 www.linux-magazine.com Coin 3D PROGRAMMING

the height is set to “4” and the sides are Before starting to encode a program, describes the features, such as setting visible. Finally, the node is added to the you should take care to plan the scene light and camera positions, creating graph (called root in this case). Table 1 graph, as repeated use of duplicate complex geometries, animating scenes includes the most important shape objects saves memory. If multiple and programming interactions. classes with their fields. We will be dis- instances of subgraphs (for example, the In addition to the Inventor Mentor, cussing how to create nodes in a legs in our chair example) can be used, you can also to download the “Open subsequent article. you will not only save memory, but Inventor C++ Reference Manual” from These elements can be combined ensure that the scene graph and the SGI. The manual describes the classes to create complex structures, to display source code remain clear. that the SGI version of Open Inventor a chair for example. To create a graph for This may not seem important in the comprises, unfortunately without the this purpose the scene has to be divided context of our example, but in the case of Coin extensions. into individual components. The more larger projects such as games or CAD If you want to learn even more about components used to describe a scene, programs, the number of objects is a Coin, you might like to take a look at the the more realistic the results. vital criterion. HTML documentation, which is included with the tool. A Simple Chair as an Example Documentation of a Scene Graph If you are interested in Open Inventor Conclusion and Prospects A chair is fairly simple to construct; and cannot wait until the next article Coin and SoQt provide for fairly simple it comprises a seat, a back, and four appears, you might like to check out interactive programming of three dimen- legs. The legs are the same, apart from some interesting online sources. SGI sup- sional graphics, without needing to leave their position. Figure 3 shows the plies the most complete documentation the (L)GPL world. The effort involved is scene graph for this construction; [3]. The “Inventor Mentor” is the Bible often trivial, particularly in contrast to every property and the accompanying for Open Inventor programmers. It that of programming with OpenGL, but geometry is described by an individual the results are convincing. After all Open object. Installation Inventor does use OpenGL for rendering The object oriented approach means operations. that only one definition is required for Coin requires you to pre-install OpenGL and The features described in this article GLUT.The rendering speed of Open Inventor duplicate objects, as multiple instances only scratch the surface of Open Inven- mainly depends on OpenGL.The Mesa can be added to the scene graph. tor’s capabilities. Our next article OpenGL library relies on software for 3D In our chair example, the front and discusses how programmers can provide calculations,but optimized OpenGL drivers rear legs are each only described once are available for some 3D graphics adapters. additional interaction via the menus or ■ and (following the required transforma- The author used a Geforce 2MX and nVidia’s with the mouse. tions) added to the scene graph as and drivers for XFree 4.x.You should enable when they are needed. hardware acceleration if possible,as Open INFO This also applies to the color of the Inventor needs a lot of power,especially in chair legs. The source code for our exam- the case of interactions. [1] Open Source Variant of Open Inventor: http://oss.sgi.com/projects/inventor/ ple is available to download from [7]; The Coin source code [6] is easy to compile [2] TGS:http://www.tgs.com Figure 4 shows the results after running and install. Simply follow the familiar steps the program. after expanding the archive file: [3] Technical documentation by SGI: http://techpubs.sgi.com/library ./configure [4] Systems in Motion:http://www.sim.no/ make [5] Coin:http://www.coin3d.org make install [6] Sourcecode for Coin and SoQt: Most Linux distributions include Qt, ftp://ftp.coin3d.org/pub/coin/src/ although you will often find that the Qt [7] Files for this article: libraries have been installed without the ftp://ftp.linux-magazin.de/pub/listings/ header files required for programming.You magazin/2003/02/3d/ also have to compile the library with OpenGL support. For SuSE 8.1 you will need to install all the Qt 3.0.5 packages,set the Dr. Stephan Siemen works as a “$QTDIR”variable to “/usr/lib/qt-3.0.5”and scientist at the University of Essex (UK) add “$QTDIR/bin”to your “$PATH”variable. where he is involved with creating software for 3D representation of The SoQt sources are also available for HOR downloading at [6]; follow the compilation T weather systems and teaches com- puter graphics and programming. steps as described for Coin. After installing Additional information on this subject Coin and SoQt,root can invoke the Figure 4:The chair described in the scene graph is available from his website at “/sbin/ldconfig”command to make both THE AU http://prswww.essex.ac.uk/ seems already very realistical, although it only libraries available throughout the system. stephan/3D/. has a few nodes described

www.linux-magazine.com March 2003 75