ReadMe for Open Inventor MultiThread Examples
---------------------------------------------

Demo_MT

Multiple Threads example with framerate display.

usage : demo <number of windows> [-s n] [-t]
                        -s n : use single scene graph 1..N
                        -t   : use blended transparency
                        -ss n: use single scene graph 1..N in stereo
                        -v   : use the small model
                        -d   : use the dragon model
                        -x   : render everything in one window (large models)
                        -a   : use anti-aliasing
                The options -v, -d and -s (-ss) are not compatible.
                The last specified option will be used.

This demo uses only "core" Open Inventor, no SoXt or SoWin classes.
By default it demonstrates that using separate threads for viewers
decouples the viewers' respective frame rates.  In other words,
using a single thread (as you must with classic Inventor) the frame
rate is limited by the slowest viewer because the viewers render
sequentially.  Using multiple threads, the viewer with the small
model should get a higher frame rate because the viewers render in
parallel (depending on the number of processors, bandwidth to the
graphics board, and other factors).

The "-s n" option makes the demo load one copy of the specified model
(from the predefined file names numbered 1..N), so all the threads
are traversing a single copy of the scene graph.  In this case the
frame rate will of course be (approximately) the same for each viewer.
This demonstrates that multiple threads, that do not modify the scene
graph, can safely traverse the scene graph at the same time.

The "-ss n" option makes the demo load one copy of the specified model
like the "-s n" option, but displays it in stereo in two separate
widgets.  This could be used, for example, to display "passive
stereo" using two polarizing projectors.

The "-x" option makes a demo load several models and then display
them in one widget. There's a application of it by specifying the
option "-v" or "-d". With the option "-x -d", for example, the model
of a dragon will be loaded in two differents parts (the body and
the wings) that will be rendered in the same widget. The option
"-x -v" uses the same principle but with a very small model (the
dragon is a quite big model). Without the "-x" option, the demo will
display one model of the whole dragon (or the very small model )
in one widget.  This demonstrates that multiple threads can render
into the same window (each using its own OpenGL context).

===========================================================================

MT_Modify1

 This example is based on Inventor Mentor example 13.1.GlobalFlds

 In that example a digital clock is implemented by connecting the
 RealTime global field to an SoText3 string field.

 In this example a digital clock is implemented by creating a
 separate thread which wakes up once every second and updates the
 string field of an SoText3 node.

 Equally pointless :-) but suggests some interesting possibilities.

 Important points:

 1) Open Inventor must be initialized with multi-thread support.
    Call SoXt::threadInit, not SoXt::init.

 2) Each additional thread that will use Open Inventor objects
    must do per-thread initialization (for thread local storage).
    Call SoDB::threadInit in each addition thread.

 3) This example uses Open Inventor's portable SbThread class to
    create the thread, but this is only for convenience.

 4) If more than one thread may be accessing the scene graph (for
    example the viewer in the main thread may be rendering), in
    order to safely _modify_ the scene graph the second thread
    must gain exclusive access by calling SoDB::writelock.

===========================================================================

MT_Render

 This demo is a simplier version of demo_MT. It just opens two 
 widgets in which two models are spinning. 
 It uses only "core" Open Inventor, no SoXt or SoWin classes.
 Demonstrates that using separate threads for viewers
 de-couples the viewer's respective frame rates.  In other words,
 using a single thread (as you must with classic Inventor) the frame
 rate is limited by the slowest viewer because the viewers render
 sequentially.  Using multiple threads, the viewer with the small
 model should get a higher frame rate because the viewers render in
 parallel (depending somewhat on the number of processors).

 Press the ESC key to exit the program.




                                -- end --
