A 3D Scene Graph Library

• [2004/05/13] Version 0.7.0 (beta) released.  This version includes support for the newer compilers and operating systems (MAC OSX). API changes to support the addition of reference counted texture image data; better and more flexible support for rendering transparent geometry including sorting as well as using multisample buffers (user selectable); support for numerous new extension including vertex and fragment programs; an interface to Qt; DDS image format support; and an image cache for sharing texture image data.  This release also contains a number of bug fixes and improvements in efficiency.  There are also a number of known issues listed in the Changelog.  Go to the SGL Project Home Page and look at the File Releases section for complete details.

• [2002/07/03] Version 0.6.0 (beta) released.  This version includes API changes to support the addition of reference counted sglGeoSet data (vertex, normal, color, and texture coordinates) as well as support for all valid types (1D, 2D, and 3D, as well as all integer, float and double types).  It also contains a number of bug fixes related to texture fonts, other minor bug fixes, and a few improvements in efficiency.

• [2002/04/25] Version 0.5.2 (beta) released.  This version includes bug fixes to the animation and light classes.  A new sglLightProcessor class replaces the initial light priority function pointer.  A new VRML loader is under development..

• [2002/03/27] Version 0.5.1 (beta) released.  This version includes mostly bug fixes, improvements to the pick and intersect traversals, and improvements to the FLT loader. It also adds support for PNG, JPEG, and TGA image formats, and md3 model format. Also added to this release is support for cube map texturing and texture dot3 and combiner environments (for multitexturing), support for user-defined light priority algorithms, application control over frame time and frame count, and environment variables to control the use of certain OpenGL features.

• [2001/12/17] Version 0.5.0 (beta) released.  This version adds support for multitexturing, optional loaders for Terrex Terrain Page, FLT model and TIFF image formats, and many other things.
• [2001/10/08] TXP (Terrex Terrain Page format) loader code contributed by Bryan P. Walsh.
• [2001/10/03] FLT loader code contributed by Michael M. Morrison.  Michael will also manage the new fltlib module - a standalone FLT file parser - which can be obtained by doing 'cvs co fltlib'.

• [2001/09/07] Version 0.4.1 (beta) released. This includes minor bug fixes and support for multisampling (when present in the hardware).
• [2001/07/20] Version 0.4.0 (beta) released (finally).  Adds new nodes types: textured fonts, animation nodes, sglBitMaskSwitch, sglSphericalTransform. Added a pick traversal, and some finally name changes.
• [2001/04/11] Version 0.3.0 (beta) released. This release represents a somewhat significant change to the API hence the bumping of the minor revision number.  Sorry for the inconvenience, but hopefully this will be the last major API change (sans additions for new functionality).
• [2001/01/12] Version 0.2.3 (beta) released.
• [2000/11/29] Version 0.2.2 (beta) released.
• [2000/10/19] Version 0.2.1 (beta) released.
• [2000/09/15] Version 0.2 (beta) released.  State sorting finally implemented!
• [2000/08/02] Version 0.1.2 (beta) released.
• [2000/06/30] Version 0.1.1 (beta) released.
• [2000/05/03] Version 0.1 (beta) released.
• [2000/04/24] The SGL home page has a new look.
• [1999/12/29] Sourceforge has agreed to host the development of SGL.

SGL consists of a set of  cross-platform C++ libraries, built on top of OpenGL, which implements 3D scene graph functionality (sgl), some simple 3D model loaders (sgldb, sglobj, sgl3ds), and some miscellaneous utilities (sglu).  A scene graph is a directed acyclic graph that organizes and stores all of the data needed to render a 3D scene.  All vertex data and OpenGL state is stored in leaf nodes in the graph, and all internal nodes control placement (via transformation matrices) and selection (via switches, discriminators, level-of-detail ranges, etc.) of sub-graphs for rendering.  Rendering of the 3D scene is performed by traversing the graph, selecting the leaf nodes to be drawn, and issuing OpenGL commands for the information contained in the selected leaf nodes. Note that during the traversal, view-frustum culling can be performed where nodes completely outside the current view are not selected, thus reducing the amount of OpenGL calls performed. 
 

Features

Current Features (latest features are in red): 

• Object-oriented (implemented in C++) therefore extendable (subclassing nodes is easy).
• Cross platform - currently runs on some of the older compilers may no longer work:
• Linux - g++ 2.95.x, 3.0, 3.1-3.4, Red Hat 9, Intel Linux Compiler (ca. 9/25/02), Debian PowerPC.
• Solaris - g++ 2.95.x, 3.0, 3.1.
• IRIX - MIPSPro C++ 7.3.x, 7.4.x
• Windows 2K, NT - MSVC++ 6.0 (with all Dev Studio Service Paks - up to 5 now), MSVC++ 7.1, MSDev project files for sgljpeg, sglpng, sgltiff.
• VxWorks - Green Hill compiler 3.0 (Tornado 1 and Tornado 2) (untested as of 0.7.0)
• MAC OSX - requires 10.3 of "Fink" extensions.
• Traversal features:
• Reentrant cull, draw, and intersection traversals for greater parallelism.
• Single or double precision traversals (switchable on the fly).
• View frustum culling.
• Transparency sorting.
• User configurable light priority sorting.
• Occlusion culling sorting (for occlusion culling extension).
• Intersection traversal segments against triangle, quad and polygon geometry types
• Pick traversal using frusta instead of line segments.
• Statistics collection.
• State sorting
• Cloning traversal.
• sglView class (like pfChannel) that handles the details of traversing and rendering the scene graph for fast application prototyping.
• Ability to render bounding spheres and boxes for debugging.
• Flexible support for sorting and rendering transparent objects using different methods (including multisample).
• Node types supported:
• group
• ordered group (for some multipass rendering techniques)
• switch, bitmask switch and indexed bitmask switch (for FLT models)
• LOD and LOD state nodes, and sglDistanceSwitch (for switching all children of a node at a specified distance)
• transform (spherical transform), translate, and scale (DP or SP)
• billboard, unscale, range limited unscale, and unproject nodes
• layer (decal) nodes for coplanar polygons
• animation nodes: key frame and real time
• discriminators
• default and override state nodes - affects state for all geometry below or until the next override is encountered.
• geodes - leaf nodes containing geometry
• lights - directional (infinite), positional, and spotlights
• cameras - sglViewPlatform leaf node for view position and orientation, and perspective and orthographic cameras for frustums
• Geometry types supported (interleaved arrays, indexed, mono-indexed, and non-indexed):
• points
• lines and line strips
• triangles, triangle strips, triangle fans
• quads and quad strips
• polygons
• bezier curves 
• bezier (nurbs) surfaces
• text: bitmapped and texture fonts
• Simple 3D primitives: cube, cone, sphere, axes, and cylinders
• Reference counted data for all types, including texture image data.
• Takes advantage of the following OpenGL extensions (or OpenGL 1.2, 1.3 and 1.4 features):
• vertex arrays
• vertex array prefetching
• interleaved arrays
• multisampling
• normal rescaling
• occlusion culling
• GL_EXT_stencil_wrap
• fog support including GL_NV_fog_distance extension
• point parameters via the GL_EXT_point_parameters and GL_ARB_point_parameters extension
• multitexturing
• cube map texturing via the GL_ARB_texture_cube_map extension
• texture border edge clamping, Texture border clamp extensions
• anisotropic texture filters (GL_EXT_texture_filter_anisotropic)
• Texture function extensions: ADD, DOT3, and COMBINE
• Texture LOD and LOD bias extensions
• texture auto mipmap extension
• hardware texture compression: GL_ARB_texture_compression or GL_EXT_texture_compression_s3tc
• OpenGL Shading Language extensions
• Cg vertex and fragment program extensions
• Shadow mapping support
• Textured points (point sprites)
• Sample coverage support for GL_*_multisample extension.
• ATI's point normal triangle extension
• ATI's bumpmap extension
• Point, line, and polygon antialiasing.
• Point size, line width, line and polygon stipples
• Display list optimized
• 1D, 2D, and cube map texture support
• Interface to Qt 3.0.x
• 3D model format loaders: OBJ, FLT, TXP, VRML, MD3 (in process), 3DS (in process)...
• Image format loaders: SGI, BMP, TIFF, JPEG, PNG, TGA, DDS (preliminary), support for BGR and BGRA image formats
• Image format writers: SGI, JPEG, PNG
• An image cache for sharing image data.

• 3D model format loaders: Inventor, DXF
• Image format loaders: GIF

Right now SGL comes in source code only. This means that you have to compile the package for yourself.  The following is a list of other software you will need or is recommended to build this package: 

• OpenGL v1.1 or later - SGL is built on top of OpenGL.  A free workalike version, called Mesa, can be downloaded from www.mesa3d.org. If you go this route, I strongly recommend getting version 3.2 of Mesa (currently beta) over version 3.1 which exhibits many bugs.
• GLUT - SGL uses GLUT (OpenGL Utility Toolkit) in the sglu library for its test programs and optionally in the sgl library for fonts. Note that if one module depends on it they all do; however, if you edit the files in the make directory, and only build sgl and sgldb you can get away without GLUT.  GLUT version 3.6 or later which can be downloaded with the Mesa demos distribution or from its work-alike at Sourceforge. If you get it from the latter, you must be sure to build a shared version of the library to get proper mouse behaviour in the test programs.
• GNU make v.3.77 or later is required to build with the provided makefiles.
• C++ compiler - A current C++ compiler is also recommended.  I use MIPSPro 7.3.x on IRIX, VC++ 6.0 on NT with all available service paks,  g++ 2.91.66 that came with RedHat 6.0 Mandrake distribution, and g++ 2.95.x on Solaris.  This does not mean other compilers won't work, but I have had many problems with earlier versions (e.g., g++ 2.7.2) in the past.  Support for g++ versions prior to 2.95.1 may be dropped in the near future.
• Service Packs for Windows - Did I mention you need the latest Dev Studio Service Pack when building on Windows? This is not to be confused with the latest Operating System Service Pack -- although it is recommended as well.
• Cygwin tools for Windows is recommended if you are building on an NT platform with the provided makefiles, you can only use the provided makefiles if you install the Cygwin tools (a bash environment for Windows) from Cygnus . I have finally found some time to develop VC++ project files that mimic, as closely as I could, the behaviour of the provided makefiles...read below.


If you discover any other requirements let me know.

You can obtain the source code in one of two ways: (1) download a packaged released from the SGL Releases Page, or (2) check out the distribution from the cvs server (details about how to do this is available on the SGL CVS Repository Info Page). The entire package is contained in the sgl module, and you can check this out with the following cvs command:

cvs checkout sgl

This will create a directory called sgl consisting of the following files/directories: 

     Makefile         - top level makefile
     make/            - all of the files need to build versions of the SGL
                          libraries for all of the supported platforms
     make.msdev/      - Microsoft Dev Studio workspace and project files
     sgl/sgl          - source files for the scenegraph library
     sgl/sglu         - source code for miscellaneous utilities (libsglu.so
                          or sglu.dll) 
     sgl/sgldb        - source code for loading 3D formats (currently a
                          subset of OBJ is supported)

     sgl/sgl3ds       - 3D Studio Max model loader
     sgl/sglobj       - OBJ format (Wavefront) model loader.
     sgl/sgltxp       - Terrex Terrain Page (TXP) model loader.
     sgl/sglwrl       - VRML 2.0 model loader.
     sgl/sglflt       - Optional OpenFlight model loader (requires fltlib)

     sgl/sgltiff      - Optional TIFF image loader (requires libtiff).
     sgl/sgljpeg      - Optional JPEG image loader (requires libjpeg).
     sgl/sglpng       - Optional PNG image loader (requires libpng).
     sgl/sgldds       - Microsofts DDS image format loader.

     sgl/sglqt        - Interface to the Qt library (requires Qt 3.0.x).

     sgl/testsgl      - test programs
     sgl/models       - data used by the test programs to test the loaders.
     docs/            - directory containing documentation (or files for
                          producing it) for SGL

The fltlib package written by Michael Morrison, is hosted in SGL's CVS repository and can also be checked out as follows:

cvs checkout fltlib

This will create a fltlib directory which contains instructions for how to build this library. This package is required by the code in the sgl/sglflt directory of the SGL distribution.

Building and Installation

Please read the INSTALL file for the latest instructions on building the package in case what follows becomes a bit dated from time to time as the build environment evolves....

A feature of this make environment is that multiple platforms can be built for the same source tree at the same time by mounting the source tree in the filesystems on multiple platforms (or debug and optimized versions can coexist). The currently supported plaforms are:

• linux.i686[.dbg]   - for Redhat 9.0 distribution
• linux.ppc.dbg   - Linux on PowerPC
• linux-icc.i686   - for use with the Intel C++ Compiler
• linux.sparcv8[.dbg]   (Tom's Debian woody/sid hybrid distribution on a Sun workstation)
• solaris551.sparcv8[.dbg] - optimized no longer builds due to internal compiler errors which will not be fixed.
• solaris57.sparcv8[.dbg]
• solaris58.sparcv8[.dbg]
• irix65.mips[.dbg]
- MIPSPro 7.3.x (and probably 7.4.x) compilers
• mipsstd.r5[.dbg] (Another IRIX platform using a C++ standard-compliant mode.)
• vizc.i686[.dbg]   (Windoze Visual C++ 6.0 using gmake 3.77 and Cygwin, NT tested)
• msvc60.i686[.dbg]  (Platform built with the workspace and project files in make.msdev subdirectory for Dev Studio 6.0 - it should be identical to the vizc.i686 platform)
• vxw.ppc603.dbg   (VxWorks - Tornado 2) deprecated
• vxwghs.ppc603.<dbg|opt>   (VxWorks - Green Hill Compiler) deprecated
• vxw2ghs30.ppc603.<dbg|opt>   (VxWorks Tornado 2 - Green Hill Compiler 3.0) deprecated

The optional '.dbg' denotes a build with all the debug symbols. There is a file corresponding to each of these platforms in the make directory called make.platform.<platform>. All modifications to the default configuration should be made here (especially if you have headers and libraries in non-standard locations). For example, you can define OPENGLLIBDIR and OPENGLINCDIR environment variables to point to the appropriate directories to compiler and link with your favorite version of OpenGL (I personally test about three versions of Mesa at a time). Also if you are using the old Mesa libs that were installed as libMesaGL.so and libMesaGLU.so then you need to set a MESA environment variable to 'Mesa' as follows (for tcsh): 

setenv OPENGLLIBDIR /usr/local/lib      setenv OPENGLINCDIR /usr/local/include      setenv MESA Mesa

or (for bash): 

export OPENGLLIBDIR=/usr/local/lib      export OPENGLINCDIR=/use/local/include      export MESA=Mesa

There are two ways to build the package for a given platform. If you don't plan on doing code development, cd to the directory containing the top-level Makefile (the top sgl directory) and type: 

make <platform>

where <platform> is one of the platform strings listed above. This should compile all of the source, create all of the shared libraries, and compile and link all of the test programs. Three new directories are created to hold these as follows:

./obj/platform.<platform> - the obj files
./lib/platform.<platform> - the shared libraries
./bin/platform.<platform> - the test programs 

If you plan to develop SGL code then it is recommended that you set the SGL_PLATFORM environment variable to specify which platform you are building on. Depending on your shell, this is either done with

setenv SGL_PLATFORM <platform>   (tcsh)

or

export SGL_PLATFORM=<platform>  (bash)

Change to the directory containing the top-level Makefile and type: 

make

The <platform> specification is not needed on the command line. With the SGL_PLATFORM environment variable set, you can now also perform builds in the various individual subdirectories (sgl, sglu, sgldb, testsgl...). 

There is currently no install target in the Makefile 

Please enter bug reports in the SGL Bug Tracking Page if you encounter problems with the various configurations. Please email me new files if you port to a different platform.

There is also no autoconf based configuration.  Right now I simply don't have a clue how to set it up to do what I want. Therefore we will have to wait until someone helps me out here or I find the time to do a little research on the subject. I'd certainly appreciate some help on this. 
 

Optional Libraries

There are number of libraries that come with SGL that require other thirdparty libraries: sgljpeg (requires libjpeg), sglpng (requires libpng), sgltiff (requires libtiff), and sglflt (requires fltlib).

• sgljpeg

  To build the sgljpeg (JPEG image loader) library, first you must install a copy of libjpeg for your platform. When using the provided makefiles, you then need to add the LDJPEG variable to the make.platform.$PLATFORM file (depends on your platform). It should contain the compiler command for specifying another library to link with when using the provided makefiles:

  LDJPEG = -ljpeg       (Unix)     LDJPEG = jpeg.lib     (Windoze - just an example)

  If the libjpeg.so does not reside in a standard location then the path to the library will also need to be included:

  LDJPEG = -L/path/to/library -ljpeg           (Unix)     LDJPEG = -LIBPATH:/path/to/library jpeg.lib  (Windoze - just an example)

  Building the SGL packages as you normally would should then also build the sgljpeg area.

  For users using Dev Studio workspace files for building SGL: there is currently no sgljpeg.dsp file and will have to be created by the user. I recommend copying something similar like sgl3ds.dsp to sgljpeg.dsp and editting it to specify the SGL files in sgljpeg and location of the jpeg library.

  Note that I have not built this package on the Windows platform so I cannot be of too much help if you run into problems. If you get this to work please let me know what is required so that I can add more details here.

• sglpng

  To build the sglpng (PNG image loader) library, first you must install a copy of libpng for your platform. When using the provided makefiles, you then need to add the LDPNG variable to the make.platform.$PLATFORM file (depends on your platform). It should contain the compiler command for specifying another library to link with when using the provided makefiles:

  LDPNG = -lpng       (Unix)     LDPNG = png.lib     (Windoze - just an example)

  If the libpng.so does not reside in a standard location then the path to the library will also need to be included:

  LDPNG = -L/path/to/library -lpng           (Unix)     LDPNG = -LIBPATH:/path/to/library png.lib  (Windoze - just an example)

  Building the SGL packages as you normally would should then also build the sglpng area.

  For users using Dev Studio workspace files for building SGL: there is currently no sglpng.dsp file and will have to be created by the user. I recommend copying something similar like sgl3ds.dsp to sglpng.dsp and editting it to specify the SGL files in sglpng and location of the png library.

  Note that I have not built this package on the Windows platform so I cannot be of too much help if you run into problems. If you get this to work please let me know what is required so that I can add more details here.

• sgltiff

  To build the sgltiff (TIFF image loader) library, first you must install a copy of libtiff for your platform. When using the provided makefiles, you then need to add the LDTIFF variable to the make.platform.$PLATFORM file (depends on your platform). It should contain the compiler command for specifying another library to link with when using the provided makefiles:

  LDTIFF = -ltiff       (Unix)     LDTIFF = tiff.lib     (Windoze - just an example)

  If the libtiff.so does not reside in a standard location then the path to the library will also need to be included:

  LDTIFF = -L/path/to/library -ltiff           (Unix)     LDTIFF = -LIBPATH:/path/to/library tiff.lib  (Windoze - just an example)

  Building the SGL packages as you normally would should then also build the sgltiff area.

  For users using Dev Studio workspace files for building SGL: there is currently no sgltiff.dsp file and will have to be created by the user. I recommend copying something similar like sgl3ds.dsp to sgltiff.dsp and editting it to specify the SGL files in sgltiff and location of the tiff library.

  Note that I have not built this package on the Windows platform so I cannot be of too much help if you run into problems. If you get this to work please let me know what is required so that I can add more details here.

• sglflt

  To build the sglflt model loader library the user must first download and build the fltlib package (which is also hosted at the SGL site). When using the provided makefiles, you then need to add some variables to the make.platform.$PLATFORM file (depends on your platform). These are given as follows:

  LDFLT = -L$(FLTLIBHOME) -lflt              (Unix)     LDFLT = -LIBPATH:$(FLTLIBHOME) fltlib.lib  (Windows)

  This and the sglflt Makefile depend on a couple environment variables:

  FLTHOME = <fltlib directory containing the header files>     FLTLIBHOME = <fltlib directory containing the library>

  If both of these are left undefined then the values default to ../fltlib which corresponds to a sibling directory to the top level sgl directory. FLTHOME must be be set if this location is different. If FLTLIBHOME is not defined it defaults to the value contained in FLTHOME. If the library does not reside in the same directory as the header files for fltlib then then this environment variable must be set to point to the correct location.

  A sglflt.dsp exists for building the sglflt area but it must be inserted into the SGL.DSW workspace file before it will be built (after fltlib.lib has been built separately). Some modification of the location of the fltlib library may be necessary before this works.

The following is a list of documentation related to SGL:

• A hierarchy for the classes contained in SGL: basic/complete from doxygen
• An overview of "User's Guide"-type information on how to use SGL.
• Doxygen generated reference documentation: frames/ no frames/ gzipped tar file
• Current TODO list

Sourceforge provides a host of services: CVS repository for the code and documentation; a bug list that also contains future features to be worked on; and a mailing list, sgl-dev, which also gets all of the CVS repository commit messages. The links to these are listed below: 

• SGL Development Home Page
• SGL Releases Page
• SGL CVS Repository Info
• SGL Bug Tracking Info
• SGL-DEV Mailing List Info

• Current nightly CVS snapshot of SGL source code only (currently no models directory or fltlib).

  The following is a list of related links: 

• Mesa Development Home Page
• Freeglut Project (GLUT workalike)

The following is a list of contributors and developers: 

Scott McMillan - Original author and project manager.

Thomas J. Stimson - state sorting, multitexturing, mono indexed geosets, more complete 1D and 2D texture support, bezier curves and surfaces, many image loaders, and countless other things.

Michael M. Morrison - fltlib author, the OpenFlight (FLT) loader, the Quake MD3 loader, the VRML loader, the TIFF, TGA, and DDS image readers, support for numerous OpenGL extensions, and Max OSX port.

Bryan Walsh - Terrain Page (TXP, from Terrex, The Terrain Experts) loader.

John K. Hammond - sglCylinder class.

Will DeVore - quaternion classes

Paul Sherman - miscellaneous scene graph support, information, and testing

Lorenzo Pastrana - absolute/sticky sglOverride behaviours.

Andy Turner - Max OSX port.

We are interested in knowing if you find SGL useful. If you would like to give feedback and/or contribute to its development, please feel free to contact Scott McMillan or (preferably) send email to the SGL-DEV mailing list.