root/juggler/branches/2.0/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.0 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: SPROC,
        POSIX, and Netscape Portable Runtime (NSPR). Win32, on the other hand,
        only uses the NSPR subsystem. The subsystems are:</para>

        <itemizedlist>
          <listitem>
            <para>SPROC (IRIX only)</para>
          </listitem>

          <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.0</title>

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