root/juggler/trunk/doc/README.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article lang="en">
   <articleinfo>
      <title>Juggler Project Overview</title>

      <authorgroup>
         <author>
            <othername>The Juggler Team</othername>
         </author>
      </authorgroup>

      <pubdate>$Date$</pubdate>
   </articleinfo>

   <section>
      <title>Introduction</title>

      <para>Congratulations, you have downloaded the source code to the
      Juggler Project, open source software for virtual reality from the
      <ulink url="http://www.vrac.iastate.edu/">Virtual Reality Applications
      Center</ulink> at <ulink url="http://www.iastate.edu/">Iowa State
      University</ulink>. Within this document, you will find information
      about the new VR Juggler 2.x directory structure including descriptions
      of all the component modules that make up the Juggler Project.
      Instructions for building the individual modules can be found within the
      specific module directories and on the VR Juggler website.</para>
   </section>

   <section>
      <title>Compiling</title>

      <para>For information on compiling the source code, refer to either the
      <filename>INSTALL.txt</filename> or <filename>INSTALL.html</filename>
      file found in this directory.</para>
   </section>

   <section id="modules-section">
      <title>Modules</title>

      <para>The Juggler Project is made up of several modules that have
      evolved from the original VR Juggler source tree. Within this section,
      we describe each of the modules, what they are used for, and, when
      possible, how they relate to VR Juggler 1.0.</para>

      <section>
         <title>VR Juggler</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/vrjuggler</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>VR Juggler is still VR Juggler. There are many new features
            in VR Juggler since the 1.0 series, but in essence, it is still
            the same familiar tool. Of the projects listed below, VR Juggler
            depends on VPR, JCCL, Sonix, and Gadgeteer. Its individual
            components have simply been broken out into individually developed
            modules. More information about the latest version of VR Juggler
            is given in the following section.</para>
         </section>
      </section>

      <section>
         <title>VR Juggler Portable Runtime (VPR)</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/vapor</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>VPR is the foundation for all the Juggler modules. It
            provides an object-oriented, cross-platform abstraction layer to
            common operating system features such as threads, semaphores, and
            sockets. All the other modules depend on VPR so that they may be
            ported easily to other platforms. In VR Juggler 1.0, VPR was the
            collection of directories Threads, SharedMem, and Sync. Since
            then, that code has been collected into a single library and
            greatly extended into what is now VPR.</para>

            <para>VPR itself contains a great deal of platform-specific code.
            It categorizes this code into subsystems, and various subsystems
            may be chosen depending upon the target platform and target
            threading system. For example, on IRIX, there are three possible
            subsystems: POSIX and Netscape Portable Runtime (NSPR). Win32, on
            the other hand, only uses the NSPR subsystem. The subsystems
            are:</para>

            <itemizedlist>
               <listitem>
                  <para>POSIX (UNIX-based platforms only)</para>
               </listitem>

               <listitem>
                  <para>NSPR (all platforms, required on Win32 and Mac OS
                  X)</para>
               </listitem>
            </itemizedlist>

            <para>Because VPR is the foundation for all the other modules, it
            is important to choose the right subsystem.</para>

            <para>Choosing the correct subsystem depends on many factors. For
            example, which of the subsystems are supported on the desired
            target platform? Are there compatibility issues with software
            outside the Juggler Project? In most cases, however, the choice is
            straightforward. Indeed, IRIX is the only platform that presents
            any real issues. In particular, the use of OpenGL Performer from
            SGI raises important compatibility concerns. SPROC threads are the
            only threads that are stable with OpenGL Performer (on IRIX).
            POSIX threads will work, but applications may sometimes crash on
            startup. As of this writing, OpenGL Performer does not work at all
            with NSPR. Other software may pose similar problems, and it is
            important to know the needs of other tools when configuring
            VPR.</para>

            <para>On platforms other than IRIX, the choice is relatively
            simple. If NSPR is available, its use is recommended. If NSPR is
            not available, POSIX threads is the next logical choice--at least
            on UNIX-based platforms. On Win32 and Mac OS X, NSPR is
            required.</para>

            <para>As mentioned above, all the other modules depend on VPR, so
            it must be compiled before anything else. For more information on
            compiling VPR, refer to
            <filename>modules/vapor/INSTALL.txt</filename>.</para>
         </section>
      </section>

      <section>
         <title>Juggler Configuration and Control Library (JCCL)</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/jackal</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>JCCL provides the configuration layer for VR Juggler and
            other modules. The config chunks and reusable configuration editor
            JavaBeans come from JCCL. These JavaBeans are used by the VR
            Juggler configuration editor tool, VRJConfig (see below). In
            essence, JCCL is the VR Juggler 1.0 Config directory with many new
            features including XML-based config files.</para>

            <para>To build the JCCL C++ library, CppDOM is required for
            parsing XML. CppDOM is a lightweight XML parser written in C++ and
            designed to provide an interface similar to JDOM. More information
            can be found at <ulink
            url="http://xml-cppdom.sourceforge.net/">http://xml-cppdom.sourceforge.net/</ulink>.</para>

            <para>To build the configuration editor JavaBeans, JDOM and the
            Tweek Java API are required. Tweek is another module in the
            Juggler Project, and it will be built automatically as a
            dependency of JCCL. JDOM comes with the Juggler Project source
            code and can be found in the directory
            <filename>juggler/external/jdom</filename>.</para>
         </section>
      </section>

      <section>
         <title>Gadgeteer</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/gadgeteer</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>Gadgeteer is made up of the code that was formerly in the VR
            Juggler 1.0 Input directory. It contains all the drivers used for
            VR Juggler input devices, and it contains the high-level Input
            Manager. The goal with Gadgeteer is to mold it into the first
            dynamically loadable component within the VR Juggler microkernel.
            At this time, it must still be compiled in, but we hope to
            generalize the concepts of VR Juggler Managers to the point that
            the kernel knows nothing about them until they are loaded at run
            time.</para>
         </section>
      </section>

      <section>
         <title>Sonix</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/sonix</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>Sonix provides an interface useful to many simple VR and
            entertainment applications to trigger and position sounds in 3D.
            This library provides simple audio sound objects on top of several
            audio APIs. The interface to Sonix is kept very simple in order to
            get people up and running with sound as fast as possible.</para>

            <para>The interface to sonix is kept very simple in order to get
            people up and running with sound as fast as possible. Sonix is
            reconfigurable allowing audio APIs to be safely swapped out at
            runtime without the dependent systems noticing. Systems using this
            layer expect to be completely portable.</para>
         </section>
      </section>

      <section>
         <title>Tweek</title>

         <section>
            <title>Directory</title>

            <para><filename>juggler/modules/tweek</filename></para>
         </section>

         <section>
            <title>Description</title>

            <para>Tweek is a cross-platform, cross-language library consisting
            of a C++ API and a Java API. Its purpose is to provide a
            convenient mechanism for a Java-based GUI to interact with a
            complex C++ library or application. The Tweek GUI can be run in
            virtual environments, external on a palm top, or on the desktop
            next to a running application. Each of these methods gives a
            familiar 2D widget set that can control applications flexibly. To
            provide this capability, it uses CORBA.</para>

            <para>The Java code in Tweek includes the Tweek Java API and the
            Tweek JavaBean loader application. The Java API is provided to
            make the use of JavaBeans and CORBA simpler for programmers. The
            JavaBean loader application simply loads the Beans it finds and
            presents them to the user in some sort of structured manner (for
            example, a collection of icons with web-style navigation).</para>
         </section>
      </section>

      <section>
         <title>VRJConfig</title>

         <para>VRJConfig is the configuration editor for VR Juggler. It is a
         complete rewrite of VjControl, both in terms of the user interface
         and the back-end code. The new interface is based on open discussion
         and feedback from users of VR Juggler 1.0 and VjControl.</para>

         <para>The back-end is much more extensible. It allows users to write
         plug-in editors to simplify complex editing tasks. User-defined
         configuration elements can be handled in a much more dynamic manner
         as well. No modification of VR Juggler or JCCL <quote>system</quote>
         files must be made to get user-defined elements into the
         editor.</para>

         <para>VRJConfig is itself a JavaBean that is loaded into the Tweek
         Java GUI. VRJConfig uses JavaBeans internally to facilitate user
         extensions. All in all, VRJConfig is a highly dynamic, powerful
         editor for VR Juggler configurations.</para>
      </section>
   </section>

   <section>
      <title>VR Juggler 2.x</title>

      <para>TODO... (this is the version number of the next release of
      Juggler)</para>
   </section>
</article>