Local Info


Installation for Aviatrix3D 1.0

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.


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.4.2 (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).

There are no other hard requirements for the code.

If you are running on a Win32 machine, and have a Creative audio card, there's an extra installation step required. The standard OpenAL drivers that creative ships, are broken. Nothing works and there are a lot of errors. What you need to do is go to nVidia's audio drivers page and download their OpenAL drivers. But, before you do, you need to head into c:\Windows\System32 and delete openal.dll. The nVidia drivers will not install while that file is in place.

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.3, 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. However, please understand that OpenGL shader support is still very sketchy in most drivers, which may cause crashes or non-functionality beyond our control.


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.


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. Make sure you have at least Make and Bash installed.


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.


No idea at this stage. We're looking for someone to help us out on this part.

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
If you are using cygwin, you will have to put the dos path to your code. For example:
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 you 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:

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:

  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
          builtin cd $dir
          echo `pwd`

  export AREA=j3d
  export PS1="[$AREA \W] \$ "
  export PATH=$J3D_PATH



Using the Build Environment

With the environment variable set up, all you need to do is
  bash$ cd $PROJECT_ROOT
  bash$ make
This will generate class files, a jar file and the javadoc for the classes. Various 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
  • config Runtime configuration files and images (if defined)
  • 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. First time up, you will need to copy one file from the make directory. After the first time you will never need to do it again. Now type:
   [j3d aviatrix3d] $ cp make/Makefile .
   [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). Unfortunately the build process only currently creates a JAR for the executable content. The config files and images used in the user interface code is not included. You will need to create a separate, hand-built JAR for this. We do intend to get this working sometime in the near future.

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.