Xj3D as a Java3D Loader

This document is dedicated to showing you how to incorporate Xj3D code into your application. One aim of the Xj3D codebase is to provide as flexible a system as possible. There are many different ways to use the code depending on the requirements of your application.

Java3D Loader

The first method of using the code is to use it as a standard loader as defined by Sun's utility interface com.sun.j3d.loaders.Loader. Implementing a loader means that the code is required to obey a set of flags and also to do most of the work within the loader, rather than by your application code. When using the loader, you don't care what happens inside, so long as you have the right look in the scene graph.

Assumptions

Behaviours define all runtime capabilities. If you don't load behaviours, none of the runtime model will execute. That means scripts, sensors or even basic event model processing is not loaded. Another item impacted by this is Inline and Externproto definitions. If these are not loaded, then some or all of the visible scene graph is not going to be visible.

Event model processing is handled by the simplistic SimpleRouteManager rather than more complex implementations. This results in faster running code, but less correct interpretation. For example, it does not handle eventOuts with more than one ROUTE connected to it.

When loading external files, we use the simpler memory based MemCacheLoadManager for processing external files. Because we don't know what environment the loader will be used in, using a load manager that caches files to disk is not the best thing in the world to do to a user's machine.

Note: Currently you as an end user have no control over these settings. It is a future goal to allow a user to specify which schemes are to be used through system properties.

The loader implementation automatically determines the file type to be loaded. It will handle both VRML97 and X3D for you. Unfortunately, the current implementation only handles raw files. Gzipped files that do not have the .gz extension will not be handled. That is going to be handled further down the track.

Many aspects of the standard runtime environment are not available. Keyboard and navigation handling is disabled because we don't have a way of hooking to the input requests from the screen. The reason for this is that bindable nodes are not handled by the standard scenegraph. Bindable node management is handled outside of the scene graph and so without this, the rest of the user interaction is hard to deal with. We also assume that because you are using a loader, you are integrating this into other applications that will be providing their own navigation handling anyway. All you care about is the transform group that holds the ViewPlatform.

XJ3D Handles VRML97 files. It doesn't read VRML1.0 files. If you need to read a simple VRML1.0 file I recommend the application vrml1tovrml2 which you can download for free here:

http://synapses.bu.edu/tools/vrml2/vrml1to2.zip

Downloading the code

For compilation:

• j3d-org.jar
• xj3d-j3d.jar

For Running:

• xj3d-common.jar
• xj3d-render.jar
• xj3d-parser.jar
• xj3d-runtime.jar
• xj3d-script-base.jar
• xj3d-ecmascript.jar
• xj3d-jsai.jar
• xj3d-core.jar
• xj3d-sav.jar
• uri.jar
• vlc_uri.jar
• j3d-org.jar
• xj3d-j3d.jar

If you wish to use Xj3D as an X3D loader rather than VRML97, then you need to use an alternate listing of JAR files. The main difference is swapping out the VRML97 scripting implementation for the X3D version, and changing to use the loader class org.web3d.j3d.loaders.X3DLoader:

• xj3d-common.jar
• xj3d-render.jar
• xj3d-parser.jar
• xj3d-runtime.jar
• xj3d-script-base.jar
• xj3d-ecmascript.jar
• xj3d-java-sai.jar
• xj3d-sai.jar
• xj3d-core.jar
• xj3d-sav.jar
• xj3d-xml.jar
• uri.jar
• vlc_uri.jar
• j3d-org.jar
• xj3d-j3d.jar

Constructing a Loader

Constructing a new loader requires creating an instance of the class org.web3d.j3d.loaders.VRML97Loader. There is the two standard constructors available - the default, no-argument constructor and one that takes an int argument, which are the load flags. For example:

import java.io.IOException;
import com.sun.j3d.loaders.Loader;
import com.sun.j3d.loaders.Scene;
import org.web3d.vrml.j3d.loaders.VRML97Loader;

....

  Loader ldr = new VRMLLoader(Loader.LOAD_ALL);

will create a loader that builds a fully compliant VRML scene graph (given the above assumptions and limitations).

Obtaining the scene graph

Once you have a loader constructed, the next step is to load one or more files. This is done through the usual assortment of load() methods. Construct a URL or file path and pass it to the load method. In return, the code will hand you a Scene or spit the dummy at you.

  try
  {
    Scene vrml_scene = ldr.load("/home/myplace/hello.wrl");
  }
  catch(Exception e)
  {
    // do stuff
  }