Xj3D Logo

Using Xj3D in your Java Application

Xj3D was designed to make it easy to add 3D capabilities to any application. By combining Java's 2D user interface capabilites with Xj3D you get a powerful environment for developing cross platform 3D applications.

What is the SAI?

SAI is the Scene Access Interface. It provides a compatible way to run and modify X3D scenes for many X3D implementations. This tutorial will use the SAI to load and manipulate an X3D scenegraph. Some special Xj3D only options will be provided to enhance your application development, but these will be flagged so you understand the issues. Using SAI will make your code portable between many different X3D implementations and help avoid vendor lockin.

Here is the abstract specification for the SAI: ISO 19775 Part II

Here is the Java Language binding: ISO 19777

VRML programmers may be familiar with the EAI, External Authoring Interface. The EAI was the way to access VRML scenes externally. It differed from the method of internal scripting. The SAI has merged these two programming models. In addition SAI has several improvements in regards to browser portability and cleaner scenegraph interaction.

Using the SAI is not the only way to use the Xj3D toolkit. It has been designed to allow component use of its different parts. Each component like parsing, rendering, exporting, scripting can be used by itself or replaced by your own code. This tutorial will not address how to use Xj3D in this way. Please refer to other documentation on www.xj3d.org on how to do this.

Setting up your environment

Your classpath needs to include the Xj3D jars. You can find the required jars in the precompiled releases of Xj3D. The following jars are always required: Xj3D supports multiple renderers. You will need to include at least one of the following jars depending on which renderer you are using. The default renderer is currently the OpenGL renderer.

For the Java3D rendering you will need to have at least Java3D 1.3 installed and the following jar in your classpath.

For the OpenGL renderer you will need JOGL installed. You can download JOGL here: JOGL Project. You will also need the following jars from Xj3D in your classpath:

We have developed an ANT script which sets up the CLASSPATH for you. The following zip file contains the ANT script and a set of sample SAI programs.

General SAI

This tutorial shows you how to use the Xj3D toolkit to develop X3D applications. We also have a general SAI tutorial which explains how to program using SAI available here: General SAI Tutorial

Browser Parameters

The X3D specification allows applications to specify parameters to change how a browser operates. You can also specify browser specifc options. The following options are supported by Xj3D.

Param NameDescriptionTypeDefaultLegal Values
AntialiasedWhether to turn on antialiasingBooleanfalsetrue,false
TextureQualityA quality metric for texturing. High turns on all tricks like anisotropicFilteringStringmediumlow,medium,high
PrimitiveQualityA quality metric for primitives. Scales how many polygons to use for primitiveStringmediumlow,medium,high
Xj3D_InterfaceTypeWhether to use Swing or AWTStringSwingswing,awt,swing-lightweight,offscreen
Xj3D_NavbarShownWhether to show the navigation barBooleantruetrue,false
Xj3D_NavbarPositionWhere to position the navigation barStringTopTop,Bottom
Xj3D_LocationShownWhether the current location is shownBooleantruetrue,false
Xj3D_LocationPositionWhere to position the location barStringTopTop,Bottom
Xj3D_LocationReadOnlyWhether the location is read onlyBooleanfalsetrue,false
Xj3D_ShowConsoleWhether to show the consoleBooleanfalsetrue,false
Xj3D_OpenButtonShownWhether to show a content Open buttonBooleanfalsetrue,false
Xj3D_ReloadButtonShownWhether to show a content Reload buttonBooleanfalsetrue,false
Xj3D_StatusBarShownWhether to show a status barBooleanfalsetrue,false
Xj3D_FPSShownWhether to show a Frames Per Second meterBooleanfalsetrue,false
Xj3D_ContentDirectoryThe initial directory to load content fromStringCurrent DirectoryAll
Xj3D_AntialiasingQualityHow many multisamples to use for antialiasing. Must be enabled to matter.Stringlowlow,medium,high
Xj3D_PreferredDimensionsPreferred size of the rendering surface in pixels
Contains both width and height.
Required when the interface type is "offscreen"
Xj3D_Culling_ModeWhat sort of visual culling to doStringfrustumnone, frustum

To specify these values pass a HashMap to the createX3DComponent call with the name, value pairs. Here is a code sample which enables the console.

        // Setup browser parameters
        HashMap requestedParameters=new HashMap();

        // Create an SAI component
        X3DComponent x3dComp = BrowserFactory.createX3DComponent(requestedParameters);

Section 9.2.4 of the X3D base specification has a table 9.2 which lists Browser options. These are all valid entries to the hashmap as well. As of Xj3D 1.0 only a few of these options are mapped.

Selecting a Renderer

Xj3D supports multiple renderers to display your 3D data. Currently its supports a Java3D and OpenGL renderer. You can specify which renderer to use by setting a System property named x3d.sai.factory.class to the renderer you want. Specify org.web3d.ogl.browser.X3DOGLBrowserFactoryImpl for the OpenGL renderer and org.web3d.j3d.browser.X3DJ3DBrowserFactoryImpl for the Java3D renderer. The default renderer is the Java3D renderer. This is an Xj3D specific property and will not affect other X3D implementations.
        System.setProperty("x3d.sai.factory.class", "org.web3d.ogl.browser.X3DOGLBrowserFactoryImpl");
        X3DComponent x3d_comp = BrowserFactory.createX3DComponent(requestedParameters);

Using Multiple 3D Windows

Multiple 3D Windows Seperate Content, reuse 3D window Same Content with Different Views

Xj3D Specific Options


The returned External Browser can be cast to the org.xj3d.sai.Xj3DBrowser interface. This will allow the programmer access to Xj3D specific functions. Check the JavaDoc for a complete list of functions(Xj3DBrowser Javadoc)

You can find the complete example in Xj3DSpecificDemo.java.


Xj3D's skin can be changed through two methods. Either by directing passing in a skinProperties object to the createX3DComponent call or by providing a properties file called xj3d-properties in Java system property user.dir location. Java WebStary deployments will look for the resource using the following call: BrowserConfig.class.getClassLoader().getResourceAsStream("xj3d-skin.properties");

An example of how to setup properties in an SAI program is:

        Properties skinProperties = new Properties();
        skinProperties.setProperty("touchSensor.cursor", "CursorFly.gif");

        HashMap params = new HashMap();
        params.put("Xj3D_Skin_Properties", skinProperties);
        X3DComponent x3dComp = BrowserFactory.createX3DComponent(params);
A full example is available here: Xj3DAppearanceDemo.java

Sensor Cursors

Navigation Mode Cursors

Location Buttons

Navigation Buttons


Input Devices

How to configure input devices like mouse, keyboard and USB devices.

Heavyweight Swing Issues

j3d.org faq reference http://www.j3d.org/faq/swing.html

Java Webstart deployment

Talk about Java webstart issues.

Java WebStart Example

Professional Training

Yumetech offers training on X3D and how to use Xj3D in your application. Details available at: Yumetech Training
[ Xj3D Homepage | Xj3D @ Web3d | Download | Screenshots | Dev docs | Dev Releases | Conformance | Contributors | Getting Started | Bug Tracking ]
Last updated: $Date: 2007-09-20 15:37:21 $