Changes between Version 1 and Version 2 of MigratingToVrjTwo

Author:

dshipton (IP: 10.23.1.189)

Timestamp:

02/01/07 19:47:15 (4 years ago)

Comment:

—

MigratingToVrjTwo

@@ -1 +1 @@
-
-
-
-
-
-
-
-
+
+
+
+
-First, please note that VR Juggler 1.1 is a development only version.  All odd-numbered minor version numbers are development-only versions.  There will never be a non-developer VR Juggler 1.1 release. VR Juggler 1.1 is only for VR Juggler development. The next non-developer release will be VR Juggler 2.0. It will be released when our development goals for VR Juggler 1.1 have been completed and the code has stabilized.
-
-here.
-
-
-
-
-
+
+
-To help make VR Juggler more modular, each of the major subsystems of VR Juggler has been split into a separate module. Each of these modules has an associated C++ namespace for all of the symbols in the module. For example, the new [http://www.vrjuggler.org/gadgeteer/ Gadgeteer] module (which handles all of the device interfaces you might use for a VR application) has the namespace `gadget`. Thus all symbols in Gadgeteer must be accessed using the `gadget::` scoping prefix.
-
-Because of the move to namespaces, the "vj" prefix from all VR Juggler 1.0 class names has been removed and replaced with the namespace of the module that contains the given class. For example, `vjKernel` has moved to the VR Juggler module which defines the `vrj` namespace. So `vjKernel` is now `vrj::Kernel`.
-
-
-
+
-VR Juggler now has a common module called [http://www.vrjuggler.org/vapor/ VPR] (VR Juggler Portable Runtime) that captures all platform-specific system abstractions.  This includes programming constructs such as threads and semaphores and system access methods such as serial ports and sockets. This common abstraction makes it possible for VR Juggler applications to run on all supported platforms with little or no platform-specific code.
-
-
-
+
-As a result of the separation of VR Juggler into multiple subsystems, the standalone `Juggler_utils` library became unnecessary. In VR Juggler 1.0 and early versions of VR Juggler 1.1, this library contained a lot of standalone "utility" code that was needed by the other VR Juggler libraries. The separationinto subsystems resulted in most of the utility code migrating to the VPR (Vapor) module mentioned before.
-
-
-
+
-VR Juggler introduces the use of a new common math library called [http://ggt.sourceforge.net/ GMTL].
-
-
-
+
-If you've looked at the new VR Juggler 1.1, you'll notice that much has changed since 1.0. Of particular note is the directory structure. In the source code, you'll see many standalone modules where before they were mixed. The installation of Juggler has more directories in the include directory (=vrj=, `snx`, `tweek`, `vpr`, `gadget`, and `jccl`). Below is a step-by-step list of the things you will need to port and how to do it.
-
-
-
+
-In VR Juggler 1.0, every object that was part of the Juggler API started with the prefix "vj". Since VR Juggler 1.1 has been broken up into distinct functional modules, there needed to be a way to differentiate between their respective objects. All of the classes and objects that used to start with "vj" now instead have a namespace designating which module they belong to.
-
-For the purposes of VR Juggler 1.1, namespaces are used as a way to make it clear which module an object belongs to. As stated before, these modules are roughly defined along the lines of their functionality:
-
-
-
-
-
-
-
-
+       
+       
+       
+       
+       
+       
+       
-
-To create and run VR Juggler applications, you only need to use the first five modules listed. The others are optional for VR Juggler 1.1 but can be extremely useful depending on your needs. These modules can also be used independent of VR Juggler for purposes other than VR applications.
-//Passing a Juggler 1.0 matrix to an OpenGL function call
-vjMatrix mat;
-
+ 
-glMultMatrixf(mat.getFloatPtr());
-
-//Passing a Juggler 1.1 matrix to an OpenGL function call
-gmtl::Matrix44f mat;
-
+ 
-glMultMatrixf(mat.getData());
-}}}
-This is by no means a complete list of changes necessary for every VR application. Read on for module-specific information regarding their header files and other porting changes.
-
-
-
+
-In writing applications, the names of the application object parent classes have changed. For example, VR Juggler 1.0 applications that derived from `vjPfApp` now derive from `vrj::PfApp`.  This is shown in the following:
-
-When linking, the library names have changed, and more options are required because there are more libraries in VR Juggler 2.x than there were in VR JUggler 1.0.  The libraries are the following:
-
-
-
-
-
-
-
+       
+       
+       
+       
+       
+       
-
-For a simpler makefile, the following can be done:
-{{{
-app: $(OBJECTS)
-
-
-
+
+
+                         
-}}}
-
-For much more detailed information, interested developers can refer to the headers `vrj/Draw/Pf/PfApp.h`, `vrj/Draw/OGL/GlApp.h`, `vrj/Draw/OSG/OsgApp.h`, `gadget/Type/PositionInterface.h`, `gadget/Type/DigitalInterface.h`, and `vrj/Kernel/Kernel.h`.
-
-
-
+
-To allow the user more control over the synchronization of applications, we have introduced the `bufferPreDraw()` function in these derived application classes: `vrj::GlApp`, `vrj::OpenSGApp`, and `vrj::OsgApp`. This function is executed once per graphics buffer each frame. For instance, if you are running in stereo, you have buffers for both the right and left eyes. You also have multiple buffers when rendering to multiple windows or surface displays.
-
-class myApplication : public vjGlApp
-{
-
-
-
-
-
-
-
-
-
-
-
+       
+       
+       
+               
+               
+               
+
+               
+               
+       
+       
-};
-}}}
-class myApplication : public vrj::GlApp
-{
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+       
+       
+       
+               
+               
+               
+       
+
+       
+       
+               
+               
+
+               
+               
+       
+       
-};
-}}}
-Because when rendering multiple viewports within a single window, the `glClear()` command affects the entire window and not just the current viewport that you're trying to render. So if you clear the color buffer during `draw()`, all of the previously drawn viewports are cleared and you end up with just a single viewport being visible.
-
-
-
+
-VR Juggler now uses the [http://ggt.sourceforge.net/ GMTL math library]. The old vjMath library is no longer available. There are some very fundamental changes between GMTL and Math from VR Juggler 1.0. You should definitely read the GMTL Programmer's Guide and FAQ, both of which are available from http://ggt.sourceforge.net/
-
-In order to aid in quick migration from 1.0 to the most recent version of VR Juggler, we have provided several optional math classes that have the same syntax from VR Juggler 1.0. These include the `vrj::Vec3`, `vrj::Matrix`, and `vrj::Quat` classes (which act exactly as `vjVec3`, `vjMatrix`, and `vjQuat` do). The class header files are located in your VR Juggler source tree in `modules/vrjuggler/deprecated/Math`. For a VR Juggler 2.0 installation, they can be found in `$VJ_BASE_DIR/include/deprecated/Math`.  The file names are `Vec3.h`, `Matrix.h`, and `Quat.h`.
-
-
+       
-
-Using these helper classes makes porting your code much easier.  Instead of converting all of your math code to GMTL, all you have to do is include the header files and make namespace changes to all of your math code. For instance, if you have the following lines of VR Juggler 1.0 code:
-For more information, refer to the http://ggt.sf.net/ website. It has excellent online reference guide and a programming guide that is more in depth than this short porting tutorial. If you don't have a web connection, refer to the header files in the `gmtl` directory. The header files have all the documentation used to generate the reference guide. Typically the headers you will use are `gmtl/Vec.h`, `gmtl/Point.h`, `gmtl/Matrix.h`, and `gmtl/Quat.h`.
-
-
-
+
-One major change to VR Juggler 1.1 is the operating system abstraction in Juggler. It has been separated into a standalone, decoupled portable runtime called the VR Juggler Portable Runtime (VPR, pronounced "vapor"). VPR is a C++ abstraction the following:
-
-
-
-
-
-
-
-
-
-
+       
+       
+       
+       
+       
+       
+       
+       
+       
-
-It even has simulated sockets (using a discrete-event simulator for sockets). What does this mean for you? What will you need to port?
-
-
-
-
-
-
+       
+       
+       
+       
+       
-
-{{{
-}}}
-
-
-
+       
+       
-
-For more detailed information, refer to the VPR ''Programmer's Reference''.
-
-
-
+
-Your interface to sound is `snx::SoundHandle`, found in `snx/SoundHandle.h`.
-
-The new sound library is located in `libsonix`, and the headers can be found in `include/snx`. See also: `include/snx/SoundHandle.h`, `include/snx/sonix.h`.
-
-
-
+
-Header file includes for access to devices in Gadgeteer:
-
-if (mAccelerateButton->getData() == gadget::Digital::TOGGLE_ON)
-{
-
+       
-}
-}}}
-Gadgeteer is located in `libgadget` and `include/gadget`.
-
-
-
+
-In VR Juggler 1.0 all applications were treated in feet, which caused problems for all our friends outside the United States who use SI units.  Therefore for VR Juggler 2.0 we have switched to meters and added a Position Filter Proxy that allows an application to use any units that it wishes. The addition of position filters causes three potential changes for applications.
-
-gadget::PositionInterface posInt;
-
-
+ 
-// the value in feet.
-gmtl::Matrix44f mat = posInt.getData(3.28f);
-There are 4 built in unit conversions that Juggler supplies they are:
-
-
-
-
-
-
-
-
+
+
+
+
+
+
-Gadgeteer 1.0 Beta 1 includes refactored handling of keybard and mouse data.  Plain windows (now referred to as "input windows") and graphics windows feed keyboard and mouse events from the windowing system into keyboard/mouse devices.  User applications can get access to these events through the type `gadget::KeyboardMouseInterface` (formerly `gadget::EventWindowInterface` and `gadget::KeyboardInterface` before that).  VR Juggler 1.0 used the name `vjKeyboardInterface`.
-
-Other XSLT 1.0 processors such as [http://xml.apache.org/xalan-j/ Xalan-J] or [http://saxon.sourceforge.net/ Saxon] can be used instead of '''xsltproc''' if it is not available. Consult the documentation for specific tool you use for usage information.
-
-
-
+
-The configuration system in VR Juggler has been separated into a standalone library. This library gives exactly the same features as before. This library has its own namespace: `jccl`. The library is called JCCL, short for Juggler Configuration and Control Library.
-
-int main(int argc, char* argv[])
-{
-
-
-
-
-
-
-
-
+       
+       
+       
+               
+               
+       
+
+       
-}
-}}}
-The JCCL library is located in `libjccl`, and the headers are in `include/jccl`.
-
-
-
+
-The configuration files used by VR Juggler have gone through quite a lot of changes since VR Juggler 1.0. The old formats used by description files and configuration files have been replaced completely by a new XML format. This means that the old formats are no longer supported by the Java or C++ code, so conversions must be made externally to VRJConfig and VR Juggler before trying to use existing configuration files. In this section, we explain some brief background information regarding the conversion to XML, and we then explain how to update existing configuration files to the latest format.
-
-
-
+
-The configuration files used by VR Juggler have undergone three overhauls since version 1.0. In August 2001, the first pass at converting to XML was made. In the configuration definition files, the complex format was replaced by very straightforward XML. The job done by the definition files was already very hierarchical in nature, so the transition to a standard, inherently hierarchical file format was a natural progression. In the actual configuration files, the changes made were not so elegant. Essentially, the key tokens were replaced by XML elements, but the actual values were left as specially formatted strings that required extra parsing ''after'' the XML parser had done its job.
-
-In July 2003, the third version fo the XML configuration file and definition file formats were introduced.  These are the final versions for VR Juggler 2.0, and they include many important new features.  The most valuable new feature is config element versioning and automatic element upgrading through VRJConfig.  With the third version, there is now one config definition per `.jdef` file.  Each `.jdef` file can contain multiple versions of its definition, and each version includes XSLT code for migrating config files of the previous version.  VRJConfig uses this XSLT code to perform automatic upgrades of config elements.
-
-
-
+
-The versions of the configuration definition files are as follows:
-
-
-
-
+       
+       
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
-
+
-The versions of the configuration files are as follows:
-
-
-
-
+       
+       
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
+       
-
-{{{
-}}}
-
-
-
+
-We now explain how to update from one version of a file format toanother. We begin with the first step: updating from the (versionless) VR Juggler 1.0 formats to version 2.0 of the definition file format and version 2.0 of the configuration file format. We then move on to explain how to do iterative updates once you have converted to the base XML format.
-
-
-
+
-Before we describe the generalized process for updating config files and config definitions, there are some higher level updates that must be applied when updating from one VR Juggler 2.0 pre-release to the next.  This will be the process used by all users of a given VR Juggler 2.0 pre-release since 2.0 Alpha 1.
-
-Users taking advantage of more advanced configuration features of VR Juggler by defining custom config element types should review the remaining updating descriptions.
-
-
-
+
-At this time, there is no automated way to update VR Juggler 1.0 configuration files to the 2.0 format. Extensive changes have been made in the basic structure and the content of the files. It is recommended that users run VRJConfig and create new VR Juggler 2.0 configurations from scratch. This offers a chance to get familiar with the new configuration editor. We hope to offer an automated update mechanism in time for the full VR Juggler 2.0.0 release.
-
-
-
+
-A Python 2 script has been written to update from the so-called 1.9 configuration file format version to 2.0. You can find it in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate` depending on whether you have a source or a binary distribution of VR Juggler. The script is called '''xmlupdate.py''', and it is run as follows:
-
-The updated files will have the same base name as the original file but with the extension `.new`. The original files will not be modified.
-
-
-
-
-
+
+
+
-Updating to version 2.1 of the definition file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate`, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `desc_2.0-2.1.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a
-definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 2.2 of the definition file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate`, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `desc_2.1-2.2.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a
-definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 2.3 of the definition file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate`, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `desc_2.2-2.3.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a
-definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 3.0 of the definition file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate`, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `desc_2.3-3.0.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a
-definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 3.1 of the definition file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in `$VJ_BASE_DIR/share/jccl/tools/xmlupdate`, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `jdef_3.0-3.1.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a
-definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 2.1 of the configuration file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in
-=$VJ_BASE_DIR/share/jccl/tools/xmlupdate=, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `cfg_2.0-2.1.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a definition file as follows:
-At this time, the makefile only supports the use of '''xsltproc''' and the Xalan command-line utility. It defaults to using '''xsltproc'''. If that tool is not available, line 38 of the makefile so that the value of `$(XSLT_TARGET)` is `update-xalan`. If neither Xalan nor '''xsltproc''' is available, you will have to use whatever XSLT processor is available on your system.
-
-
-
+
-Updating to version 3.0 of the configuration file format can be done through the use of an XSLT stylesheet. This stylesheet is found in `juggler/modules/jackal/tools/xmlupdate` or in
-=$VJ_BASE_DIR/share/jccl/tools/xmlupdate=, depending on whether you have a source or a binary distribution of VR Juggler. The stylesheet is named `cfg_2.1-3.0.xsl`, and it can be used with any XSLT 1.0 processor. For example, if you have '''xsltproc''' available, you can use it to update a definition file as follows: