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.
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
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
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
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
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
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
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
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.
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
include and of that system-level information, you can define another variable
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
if [ ! -x $dir ] ; then
echo $2 does not exist
builtin cd $1
builtin cd $dir
export PS1="[$AREA \W] \$ "
cd $PROJECT_HOME $1
Using the Build Environment
With the environment variable set up, all you need to do is
bash$ cd $PROJECT_ROOT
This will generate class files, a jar file and the javadoc for the classes.
Various options with make are:
The code directory structure has 7 subdirectories under the main code area.
Five of these are there when you download the code:
- class - Generates just the class files
- jar - Compiles the code and creates a JAR file
- javadoc - Creates javadoc for you
- clean - Cleans up everything!
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
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
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.
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
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
[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
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
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.