Open Inventor - Examples from the Inventor Toolmaker

These directories contain source code for all the examples in the
Inventor Toolmaker.  Note that each example is illustrated only 
in C++.

The following directories correspond to chapters in the book. 
Each chapter illustrates how to create a specific type of
new Inventor object:

    02.Nodes - Objects in the scene database
               (See also directory 02.NodesDLL for the Win32 environment.)
    03.Fields - Parts of a node object; lightweight datatypes
    04.Actions - Database operations
    05.Elements - Database traversal state
    06.Engines - Objects that allow you to encapsulate motion and geometry
    07.Nodekits - Macro nodes
    08.Manips - Direct manipulation interactive objects
    09.Highlights - Highlighting classes used by selection
    10.Viewers - Xt components used to view a scene
    11.Events - Events and Xt devices

General Notes:

 1) Test Programs
    The following directories contain code fragments only,
    there are *no test programs* in these directories!

      03.Fields
      05.Elements
      06.Engines

-----------------------------------------------------------------------

WIN32 NOTES:
(updated 07/08/96)

    Issues specific to the Windows NT and Windows 95 environment.

    In general Open Inventor is just as extensible under WIN32 as it is
    in every other environment.  You will see that only minor changes
    (under "#ifdef WIN32") are required to port extension code to WIN32.


 1) Static Data and DLLs

    DLLs are very similar to the shared libraries, DSOs and so on used
    in the UNIX environment, but there are a few things that are more
    awkward.  In order to handle static member variables in the Inventor
    classes, it is necessary to both export and import them explicitly.
    In almost every case this is handled for you transparently using
    conditional compilation in the Inventor include files.  However,
    when you use the extension macros (SO_NODE_SOURCE etc) to create new
    nodes, nodekits, actions and so on you must take specific steps to
    handle it.

    Starting with release 2.1.1 we have largely eliminated the need to
    deal with this problem explicitly, however we still recommend using
    the following procedure as a preventative measure.  You definitely
    should use the following procedure if your subclasses get compiler
    errors like "attempt to redefine dllimport static data".

    We have made it easy to handle static data import and export by
    providing two new include files.  You should bracket the class
    definition in your subclass header file with these includes.  The
    header file will then look something like this:

        // Header file for a new kind of node

        #include <Inventor/nodes/SoGroup.h>

        class Alternate : public SoGroup {

            ...

        };


 2) Function "main"

    The WIN32 environment reserves the function name "main" for its own
    use.  Programs written specifically for WIN32 will supply a function
    named "WinMain", but to make it easy to port simple Inventor programs
    our WIN32 implementation supplies this function for you.  After doing
    various setup operations the Inventor WinMain function makes a call
    to a function which is expected to be prototyped:

        void ivMain( int argc, char** argv );

    Therefore you will see that the test programs in these directories
    have been slightly changed in some cases from the UNIX version so
    that the declaration of "main" matches this prototype (ie accepts an
    int and a char** and returns void).  They also have:

        #ifdef WIN32
        #define main(foo,bar) ivMain(foo,bar)
        #endif


 3) Extension Nodes as DLLs

    An example of this capability is included as directory "02.NodesDLL".
    Functionally it's pretty much the same as the DSO capability on SGI
    machines, but the file extension and search order are different.  See
    the README in that directory for more information.


 4) Stdout and Stderr

    Stdout and stderr basically don't exist in the WIN32 environment.
    (Actually you can build a "console application" that has stdout and
    so on, but standard WIN32 programs are intended to be started from
    an icon, not a command line.)  The result is that some of these test
    programs detect errors (eg. "could not open file") and attempt to
    report them, but you will not see the report because it is written to
    stdout (which is effectively the "bit bucket").  You can easily
    modify them to call the standard WIN32 function "MessageBox" or the
    Inventor convenience function "SoWin::createSimpleErrorDialog".

    The "printVolume" test program has already been modified to report
    the result of invoking the new action using MessageBox.


 5) Chapters 10 and 11

    The Toolmaker examples from chapters 10 and 11 (Components and
    Events) are much more difficult to convert to the WIN32 environment
    because they handle raw X events.  These examples are not currently
    provided.
