Installation

This page is divided into three sections. The first is common for everyone. This section details all of the libraries that are needed beyond those that are included in the download. The second section is for users that would like to install Aviatrix3D for using it in developing other applications. The third section is for developers that are interested in compiling their own version of Aviatrix3D from source.

This setup refers to the 2.0 codebase and it's requirements. If you are interested in the requirements for the older 1.0 codebase, please visit the 1.0 Setup page.

System Requirements

The first thing that you will need to do is download the latest version of Aviatrix3D. You can find these on our downloads page. Aviatrix3D is a relatively simple library with few dependencies. Most of those are in the utility section of the codebase, where we make use of code from the main j3d.org Code repository and provide Aviatrix3D-specific implementations. There are a few dependencies on external libraries that we do not include as part of the download. This is because they require native libraries, and they'll change depending on what operating system you will be running the code on. The following gives a list of what else you will need to install.

For all users, you need at least a J2SE v1.5.0 (JDK if you're a developer, JRE if you're an end user or installing this as part of a bigger app). This is required by JOGL as prior versions have some major bugs dealing with the native AWT interface code. JOAL is required if you are going to be using audio capabilities. There's also a fair amount of fiddling to be done to get the right drivers to support OpenAL - particularly with Creative cards. Creative's drivers are broken and you'll need to find some third-party drivers for them (see below). Note that this code has not been tested with the JOGL 2.0 codebase.

• J2SE v1.5.0
• JOGL JSR 231 1.1.1
• JOAL 1.1.1
• vecmath 1.5.0

There are no other hard requirements for the code. If you wish to use the SWT capabilities then you will need a copy of either SWT or Eclipse itself version 3.2 or later. Lightweight Eclipse support requires Draw2D 3.2.1 or later. These can be downloaded from Eclipse.org. In addition, you will need our SWT OpenGL bindings, which is a port of the JOGL APIs to run within the SWT framework. However, be aware that the two JOGL APIs are not compatible so make sure that they are isolated in your CLASSPATH setup. Either run one or the other, but not both accessible in the same classpath at the same time.

Since you are going to be doing 3D graphics coding, we recommend the best video card your money can buy. Either the nVidia GeForce or ATI Radeon cards are the current best of the crop in the PC market. Of course, the Sun hardware is well supported too :) Other platforms supported depend on what JOGL can handle. We know that a Mac version is running, but requires MacOS X 10.4, so you can't run this code on anything earlier than that.

If you want to test the shader capabilities, then you'll need a card that can support that. We don't have the option to support CG shaders yet (though JOGL does have the APIs to access the CG compilers). OpenGL 1.5/2.0 Shader objects are supported, assuming your video card and drivers support them.

Requirements for end user developers

For you, you will need to download the most recent release of Aviatrix3D. In the zip file, there will a number of JAR files. Three of these are specifically Aviatrix3D, related, the rest are utilities that come from the main j3d.org Code repository that Aviatrix3D relies on. There are two ways of making use of Aviatrix3D for your end-user development - everything or parts.

For the user that wants everything, grab the all of the utility JAR files that start with j3d-org-*. Place those somewhere in your classpath. Also grab aviatrix3d-all.jar as this contains all the code in Aviatrix3D to use. Also place that somewhere in your CLASSPATH.

For the user that only wants to use the core API (org.j3d.aviatrix3d.* and below), then you will only need to grab j3d-org-util.jar and aviatrix3d-core.jar, All the rest can be ignored.

Requirements if you want to compile Aviatrix3D from scratch

The code is built around a standard unix environment for setup. We use the various GNU tools to build the code - in particular there is a heavy reliance on GNU Make for the compilation.

You can of course compile the codebase by hand using javac. This is entirely possible, and we make sure to architect the codebase so that you will not get caught with needing to compile 3 different directories simultaneously. However we do recommend using the build environment because it makes life soooooo much easier.

Win32

For Microsoft OS users, you will need to download and install cygwin from Redhat. This can be found at http://sourceware.cygnus.com/cygwin/. Follow the installation instructions. The default environment should be good enough for you. However, when you install it, make sure that you chose unix file types, not DOS. If you do not, checking things out of SVN will break the Makefile setup due to all the extra ^Ms that are added. Make sure you have at least Make and Bash installed.

Unix

You really don't need to do much at all. Make sure that you have the GNU tools installed as we use a number of features from GNU Make. The local vendor-specific make will not work as the build system uses several GNU features to provide cross-platform compile ability.

MacOS

Using Mac OS X 10.4, everything should already be available for you. Since we use make for the build environment, everything should just work under the standard installation of OS X.

Environment Settings

The code relies on a single environment variable to be set called PROJECT_ROOT.This variable will point to the root of the code, that you have installed. Usually your code will be placed somewhere like

   /home/justin/projects/j3d.org/aviatrix3d

If you are using cygwin, you will have to put the dos path to your code. For example:

  c:/cygwin/home/justin/projects/j3d.org/aviatrix3d

Yes, the slashes are meant to be that way around. If you put the local unix-style path to the codebase then you will get javac complaining about errors or classes not found etc.

Many people have their own, personal classpath setups too. The makefile that comes with this codebase ignores your standard CLASSPATH. To include and of that system-level information, you can define another variable called PROJECT_CLASSPATH. This is used to bring in any other general/system JARs that you might wish to include other than the those used internally. The typical usage is to write the following:

  export PROJECT_CLASSPATH=${CLASSPATH}

If you are using BASH for your shell, then I find the following little setup handy in my .bashrc/.bash_login. This allows me to swap between various different projects on the fly:

JOGL_DOS_HOME="c:/java/jogl/1.1.1/lib"
JOGL_CLASSPATH="${JOGL_DOS_HOME}/jogl.jar;${JOGL_DOS_HOME}/gluegen-rt.jar"
JOGL_LIB_PATH="${JOGL_DOS_HOME}/jogl.dll:${JOGL_DOS_HOME}/gluegen-rt.dll"

JOAL_DOS_HOME="c:/java/joal/1.1.2/lib"
JOAL_CLASSPATH="${JOAL_DOS_HOME}/joal.jar;${JOAL_DOS_HOME}/gluegen-rt.jar"
JOAL_LIB_PATH="${JOAL_DOS_HOME}/joal_native.dll:${JOAL_DOS_HOME}/gluegen-rt.dll"

J3D_HOME=${HOME}/j3d.org
J3D_DOS_HOME="c:/cygwin/home/${USER}/j3d.org"
J3D_BASE_CLASSPATH="${TEST_CLASSPATH}"
J3D_LIB_PATH=
J3D_PATH=$PATH

J3D_AV3D_HOME=${J3D_HOME}/aviatrix3d
J3D_AV3D_PROJECT_ROOT="${J3D_DOS_HOME}/aviatrix3d/trunk"
J3D_AV3D_CLASSPATH="${J3D_AV3D_CLASSPATH};${J3D_AV3D_PROJECT_ROOT}/classes"
J3D_AV3D_CLASSPATH="${J3D_AV3D_CLASSPATH};${J3D_AV3D_PROJECT_ROOT}/config"
J3D_AV3D_CLASSPATH="${J3D_AV3D_CLASSPATH};${J3D_AV3D_PROJECT_ROOT}/images"
J3D_AV3D_LIB_PATH="${J3D_LIB_PATH}:${JOGL_LIB_PATH}:${JOAL_LIB_PATH}"
J3D_AV3D_PATH="${J3D_PATH}:${JOGL_LIB_PATH}:${JOAL_LIB_PATH}"

if [ -n STD_PATH ] ; then
  STD_PATH="${PATH}:${JDK_HOME}"
fi


cd()
{
  case $# in
    0)  builtin cd $HOME
        ;;
    1)  builtin cd $1
        echo `pwd`
        ;;
    2)  dir=$1/$2
        if [ ! -x $dir ] ; then
          echo $2 does not exist
          builtin cd $1
        else
          builtin cd $dir
          echo `pwd`
        fi
  esac
}

av3d()
{
  export PROJECT_HOME=${J3D_AV3D_HOME}
  export AREA=av3d
  export PS1="[$AREA \W] \$ "
  export LD_LIBRARY_PATH=${J3D_AV3D_LIB_PATH}
  export PATH=${J3D_AV3D_PATH}
  export PROJECT_ROOT=${J3D_AV3D_PROJECT_ROOT}
  export CLASSPATH="${J3D_AV3D_CLASSPATH}"
  export PROJECT_CLASSPATH="${J3D_AV3D_PROJECT_CLASSPATH}"

  cd $PROJECT_HOME $1
}

Note that the above script is setup for cygwin (ie Win32) so you'll need to tweak it for linux/mac.

Using the Build Environment

With the environment variable set up, all you need to do is

  bash$ cd $PROJECT_ROOT
  bash$ make

This will list the available make options. The options with make are:

• class - Generates just the class files
• jar - Compiles the code and creates a JAR file
• javadoc - Creates javadoc for you
• clean - Cleans up everything!

The code directory structure has 7 subdirectories under the main code area. Five of these are there when you download the code:

• make The makefiles for building the code
• lib External JARs that we use during compilation and runtime.
• docs Project documentation and the generated javadoc
• src Source files for the project. Sub directories broken down by implementation language
• examples Example code to show how to use the toolkit

The classes, jar and docs/javadoc directories are created by the build process.

Building the class files

To build the entire codebase from scratch, change to the project root directory. Now type:

   [j3d aviatrix3d] $ make clean
   [j3d aviatrix3d] $ make class

You will now see make run off and do its thing. If everything compiles successfully, you will find all the .class files in the $PROJECT_ROOT/classes directory. You may elect to use these directly or build a JAR file for them

If you only wish to recompile a single directory then you can change to that directory and just type:

   [j3d aviatrix3d] $ make

This will then build only the local files.

Building JAR files

If you wish for a binary distribution of the code, they you can create the jar file with the command

   [j3d aviatrix3d] $ make jar

These file will be built and placed in the $PROJECT_ROOT/jars directory (if the directory does not exist it will be created). The JARs created already include all the manifest information that you need to run Aviatrix3D as an Eclipse plugin. You will note that the generated JAR file name is aviatrix3d-all_2.0.0.jar. This is not compatible with the eclipse naming convention for plugins, so if you do use it, you'll need to rename the JAR file to org.j3d.aviatrix3d_2.0.0.jar before putting that into your plugins directory.

Building Javadocs

Of course, no Java project is complete without the accompanying javadoc. This too can be generated using the make system. Before running the make process, you may want to customise the code for your system. We automatically attempt to link to any other javadoc that you have on your machine - in particular the Java 3D, JDK and XML projects. To include these, or to disable the ability, you will need to edit one of the makefiles.

Firstly change into the $PROJECT_ROOT/java directory. There you will find a file called Makefile. Open this up in your editor of choice and go to the very bottom of the file. There you will find a variable called LINK_URLS. Edit the values there to suit your system. Make sure you follow the instructions there and put fully qualified URLs.

Now, to generate the documentation, change back to the project root directory and type

   [j3d aviatrix3d] $ make javadoc

If everything goes according to plan, you will see a big stream of printouts as the documentation is produced. After all this is finished, you will find the docs in the $PROJECT_ROOT/docs/javadoc directory.

Example Code

The example code area does not use the makefiles to build the code. What this means is you have to hand compile each directory. Firstly, make sure that the classpath is setup correctly and points to your example directory(s) that you wish to compile and run.

To run the demo code after you have compiled it, change to the appropriate directory and run the class file with the normal java command. You will need to be in the directory where the .class file is normally as a lot of the examples reference resources, like images for textures, using relative file paths.