Changeset 20882

Show
Ignore:
Timestamp:
10/21/07 11:44:33 (1 year ago)
Author:
patrick
Message:

MF22 r20881: Document and reference VJ_DATA_DIR. Fixed a few typos.

I have also started using version numbers appropriate for VR Juggler 3.0.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • juggler/trunk/modules/vrjuggler/doc/getting.started.guide/getting.started.guide.xml

    r20756 r20882  
    638638                  <para>UNIX/Linux systems use these environment variables to 
    639639                  find dynamically loaded libraries, such as 
    640                   <filename>libvrj-2_2.so</filename>. Unless you are building 
     640                  <filename>libvrj-3_0.so</filename>. Unless you are building 
    641641                  everything with static libraries, you will need to set these 
    642642                  to include the VR Juggler library directory. An example of 
    …… 
    735735               <listitem> 
    736736                  <para>The environment variable <envar>VJ_BASE_DIR</envar> 
    737                   plays identifiers where VR Juggler is installed. This 
    738                   information is used for the following purposes:</para> 
     737                  identifies where VR Juggler is installed. This information 
     738                  is used for the following purposes:</para> 
    739739 
    740740                  <itemizedlist> 
    …… 
    756756                        <envar>VJ_BASE_DIR</envar> has been diminished 
    757757                        greatly. The remainder of the description of 
    758                         <envar>Vj_BASE_DIR</envar> explains when it may need 
     758                        <envar>VJ_BASE_DIR</envar> explains when it may need 
    759759                        to be set and when the default will be more than 
    760760                        sufficient.</para> 
    …… 
    776776                  <para>On <productname 
    777777                  class="registered">Windows</productname>, the Juggler DLLs 
    778                   (<filename>vpr-2_0.dll</filename>, 
    779                   <filename>jccl-1_2.dll</filename>, 
    780                   <filename>vrj-2_2.dll</filename>, etc.) determine on their 
     778                  (<filename>vpr-2_2.dll</filename>, 
     779                  <filename>jccl-1_4.dll</filename>, 
     780                  <filename>vrj-3_0.dll</filename>, etc.) determine on their 
    781781                  own where they are installed when they are attached to the 
    782782                  application process. As such, the <productname 
    …… 
    803803                  must be set to the base directory of the installed Juggler 
    804804                  Suite. For example, if you downloaded a UNIX version of VR 
    805                   Juggler 2.2 and extracted it to the directory 
     805                  Juggler 3.0 and extracted it to the directory 
    806806                  <filename>/home/software</filename>, you would set 
    807807                  <envar>VJ_BASE_DIR</envar> with this command:</para> 
    808808 
    809                   <screen>% VJ_BASE_DIR = /home/software/vrjuggler-2.2</screen> 
     809                  <screen>% VJ_BASE_DIR = /home/software/vrjuggler-3.0</screen> 
    810810 
    811811                  <para>The last component of the path depends on the 
    …… 
    818818 
    819819                  <screen>% VJ_BASE_DIR = $HOME/juggler/my_build_dir/instlinks</screen> 
    820  
    821                   <important> 
    822                      <para>When working from withing the build tree and using 
    823                      <filename>instlinks</filename>, 
    824                      <envar>VJ_BASE_DIR</envar> is 
    825                      <emphasis>required</emphasis>.</para> 
    826                   </important> 
     820               </listitem> 
     821            </varlistentry> 
     822 
     823            <varlistentry> 
     824               <term>VJ_DATA_DIR</term> 
     825 
     826               <listitem> 
     827                  <para>On non-<productname 
     828                  class="registered">Windows</productname> platforms, VR 
     829                  Juggler 2.2 and beyond used versioned directories to allow 
     830                  for parallel installations of different versions of VR 
     831                  Juggler. The directories that are versioned are those 
     832                  containing the header files (needed for compiling VR Juggler 
     833                  applications), those containing plug-ins, and those 
     834                  containing data files (needed for running VR Juggler 
     835                  applications) and sample programs. For example, we will 
     836                  refer later to the MPApp sample application. Its source code 
     837                  can be found in 
     838                  <filename>$VJ_BASE_DIR/share/vrjuggler-3.0/samples/OGL/simple/MPApp</filename>. 
     839                  The value of <envar>VJ_DATA_DIR</envar> for VR Juggler 3.0 
     840                  ought to be 
     841                  <filename>$VJ_BASE_DIR/share/vrjuggler-3.0</filename>. In VR 
     842                  Juggler configuration files, there is sometimes a need to 
     843                  refer to files in the VR Juggler data directories. In order 
     844                  to allow a configuration to be used with multiple VR Juggler 
     845                  versions (which may or may not be possible depending on the 
     846                  config elements in use) or between <productname 
     847                  class="registered">Windows</productname> and 
     848                  non-<productname class="registered">Windows</productname> 
     849                  platforms, users can reference the 
     850                  <envar>VJ_DATA_DIR</envar> environment variable.</para> 
     851 
     852                  <para>This environment variable was introduced in VR Juggler 
     853                  2.2.1. If the environment variable is not set when an 
     854                  application is launched, it will be set automatically 
     855                  relative to the value of <envar>VJ_BASE_DIR</envar>. In 
     856                  general, users should not set <envar>VJ_DATA_DIR</envar> 
     857                  unless they know that the default value is 
     858                  inappropriate.</para> 
    827859               </listitem> 
    828860            </varlistentry> 
    …… 
    893925                  be set on all of these platforms. If not set, the default 
    894926                  search path for configuration files is 
    895                   <filename>$VJ_BASE_DIR/share/vrjuggler/data/configFiles</filename>.</para> 
     927                  <filename>$VJ_DATA_DIR/data/configFiles</filename>.</para> 
    896928 
    897929                  <note> 
    …… 
    920952 
    921953                  <para>The default search path for configuration files is 
    922                   always 
    923                   <filename>$VJ_BASE_DIR/share/vrjuggler/data/definitions</filename>. 
     954                  always <filename>$VJ_DATA_DIR/data/definitions</filename>. 
    924955                  Setting the environment variable 
    925956                  <envar>JCCL_DEFINITION_PATH</envar> appends directories to 
    …… 
    10781109         <para>Some sample applications designed for getting started with VR 
    10791110         Juggler are found in 
    1080          <filename>$VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple</filename>. 
    1081          All of these applications were designed to be used as part of courses 
    1082          teaching people how to write VR Juggler applications using OpenGL. 
    1083          They contain clear comments explaining what the code is doing, and 
    1084          they are intended to be as simple as possible. These tutorials are as 
     1111         <filename>$VJ_DATA_DIR/samples/OGL/simple</filename>. All of these 
     1112         applications were designed to be used as part of courses teaching 
     1113         people how to write VR Juggler applications using OpenGL. They 
     1114         contain clear comments explaining what the code is doing, and they 
     1115         are intended to be as simple as possible. These tutorials are as 
    10851116         follows:</para> 
    10861117 
    …… 
    11341165 
    11351166         <para>Examples of OpenGL Performer applications can be found in 
    1136          <filename>$VJ_BASE_DIR/share/vrjuggler/samples/Pf/advanced</filename>. 
    1137          These are for more advanced developers who are familiar with 
    1138          Performer and some of the more complicated aspects of VR Juggler. 
    1139          There are two main programs to be found there:</para> 
     1167         <filename>$VJ_DATA_DIR/samples/Pf/advanced</filename>. These are for 
     1168         more advanced developers who are familiar with Performer and some of 
     1169         the more complicated aspects of VR Juggler. There are two main 
     1170         programs to be found there:</para> 
    11401171 
    11411172         <itemizedlist> 
    …… 
    11681199      and that is the whole point, right? This chapter explains how to compile 
    11691200      the applications provided in the directory 
    1170       <filename>$VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple</filename>.</para> 
     1201      <filename>$VJ_DATA_DIR/samples/OGL/simple</filename>.</para> 
    11711202 
    11721203      <section> 
    …… 
    12001231 
    12011232            <para>All the sample programs in 
    1202             <filename>$VJ_BASE_DIR/share/vrjuggler/samples</filename> use the 
    1203             same basic steps to compile unless otherwise noted. Always refer 
    1204             to the top of the sample application's 
    1205             <filename>Makefile</filename> for information that may be specific 
    1206             to building that application. In general, though, all 
    1207             applications' makefiles require the GNU version of the 
     1233            <filename>$VJ_DATA_DIR/samples</filename> use the same basic steps 
     1234            to compile unless otherwise noted. Always refer to the top of the 
     1235            sample application's <filename>Makefile</filename> for information 
     1236            that may be specific to building that application. In general, 
     1237            though, all applications' makefiles require the GNU version of the 
    12081238            <command>make</command>(1) utility, sometimes installed as 
    12091239            <command>gmake</command>.</para> 
    …… 
    12111241            <para>The example used here will be the MPApp tutorial application 
    12121242            found in 
    1213             <filename>$VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple/MPApp</filename>. 
    1214             It is an OpenGL-based application that will compile and run on all 
     1243            <filename>$VJ_DATA_DIR/samples/OGL/simple/MPApp</filename>. It is 
     1244            an OpenGL-based application that will compile and run on all 
    12151245            platforms supported by VR Juggler. Begin by changing into the 
    12161246            directory 
    1217             <filename>$VJ_BASE_DIR/share/vrjuggler/samples/OGL/simple/MPApp</filename> 
    1218             in a command shell.</para> 
     1247            <filename>$VJ_DATA_DIR/samples/OGL/simple/MPApp</filename> in a 
     1248            command shell.</para> 
    12191249 
    12201250            <para>To compile MPApp, simply enter the following:</para> 
    …… 
    13481378      modifications. What does change is the configuration files used when 
    13491379      starting the program. In 
    1350       <filename>$VJ_BASE_DIR/share/vrjuggler/data/configFiles</filename>, you 
    1351       can find many basic configuration files including those for running in 
    1352       simulator using a mouse and keyboard to simulate VR input devices and 
    1353       some example files based on those used for the VRAC C4 system. In the 
    1354       directory, you will see some files with names containing 
    1355       <quote>mixin</quote>. These are special files that provide a specific 
    1356       capability not necessarily needed by all applications. They can be mixed 
    1357       in (hence the name) with other configuration files as needed. The 
    1358       configuration files found in the <filename>configFiles</filename> 
    1359       directory will be referenced in the examples provided, so be sure you 
    1360       know where they are.</para> 
     1380      <filename>$VJ_DATA_DIR/data/configFiles</filename>, you can find many 
     1381      basic configuration files including those for running in simulator using 
     1382      a mouse and keyboard to simulate VR input devices and some example files 
     1383      based on those used for the VRAC C4 system. In the directory, you will 
     1384      see some files with names containing <quote>mixin</quote>. These are 
     1385      special files that provide a specific capability not necessarily needed 
     1386      by all applications. They can be mixed in (hence the name) with other 
     1387      configuration files as needed. The configuration files found in the 
     1388      <filename>configFiles</filename> directory will be referenced in the 
     1389      examples provided, so be sure you know where they are.</para> 
    13611390 
    13621391      <section id="section.required.reading"> 
    …… 
    15191548            <filename>$VJ_BASE_DIR\share\vrjuggler\data\configFiles</filename> 
    15201549            on Windows or 
    1521             <filename>$VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles</filename> 
     1550            <filename>$VJ_BASE_DIR/share/vrjuggler-3.0/data/configFiles</filename> 
    15221551            on all other platforms. Beginning users will typically want to 
    15231552            reference the example configuration files in that directory. As 
    …… 
    16571686               Windows</title> 
    16581687 
    1659                <para>In VR juggler 2.2, Cocoa support has been added for Mac 
    1660                OS X usage. This gives much better results than the previous 
     1688               <para>In VR juggler 2.2, Cocoa support was added for Mac OS X 
     1689               usage. This gives much better results than the previous 
    16611690               reliance upon the X Window System. The interface for VR Juggler 
    16621691               applications on Mac OS X is noticeably different than other 
    …… 
    16821711               scope of this document, but Apple has extensive documentation 
    16831712               available for perusal. For typical VR Juggler applications, the 
    1684                bundle data files that come with VR Juggler 2.2 will suffice. 
     1713               bundle data files that come with VR Juggler 3.0 will suffice. 
    16851714               The application bundle is constructed automatically using these 
    16861715               files when the <literal>bundle</literal> target is built for 
    16871716               any VR Juggler application whose build is based on Doozer 2.1.4 
    16881717               and newer. For builds that are not using Doozer, see the files 
    1689                in 
    1690                <filename>$VJ_BASE_DIR/share/vrjuggler-2.2/data/bundle</filename> 
    1691                for a starting point.</para> 
     1718               in <filename>$VJ_DATA_DIR/data/bundle</filename> for a starting 
     1719               point.</para> 
    16921720 
    16931721               <para>The use of application bundles offers several different 
    …… 
    17301758               This is done as follows:</para> 
    17311759 
    1732                <screen>% open -a MPApp.app $VJ_BASE_DIR/share/vrjuggler-2.2/data/configFiles/standalone.jconf</screen> 
     1760               <screen>% open -a MPApp.app $VJ_BASE_DIR/share/vrjuggler-3.0/data/configFiles/standalone.jconf</screen> 
    17331761 
    17341762               <para>Note that the paths given to the application bundle and 
    …… 
    22352263            <quote>training file</quote> for the simulated glove device. The 
    22362264            default training file is 
    2237             <filename>$VJ_BASE_DIR/share/vrjuggler/data/gesture/simpleSimGestures.dat</filename>.</para> 
     2265            <filename>$VJ_DATA_DIR/data/gesture/simpleSimGestures.dat</filename>.</para> 
    22382266         </section> 
    22392267 
    …… 
    23532381 
    23542382            <para>The example configuration files in the directory 
    2355             <filename>$VJ_BASE_DIR/share/vrjuggler/data/configFiles</filename> 
    2356             modeled after those used for VRAC's Onyx-powered C4 system are as 
     2383            <filename>$VJ_DATA_DIR/data/configFiles</filename> modeled after 
     2384            those used for VRAC's Onyx-powered C4 system are as 
    23572385            follows:</para> 
    23582386