Using Xj3D in your Java Application

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

• dis.jar
• gnu-regexp-1.0.8.jar
• httpclient.jar
• j3d-org-images.jar
• j3d-org.jar
• uri.jar
• vlc_uri.jar
• xj3d-config.jar
• xj3d-common.jar
• xj3d-core.jar
• xj3d-ecmascript.jar
• xj3d-external-sai.jar
• xj3d-java-sai.jar
• xj3d-jaxp.jar
• xj3d-net.jar
• xj3d-norender.jar
• xj3d-parser.jar
• xj3d-render.jar
• xj3d-runtime.jar
• xj3d-sai.jar
• xj3d-sav.jar
• xj3d-script-base.jar
• xj3d-xml-util.jar

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

• xj3d-j3d.jar

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:

• xj3d-ogl.jar
• aviatrix3d-all.jar
• vecmath.jar - This is available from the Java3D project

General SAI

Browser Parameters

Param Name	Description	Type	Default	Legal Values
Antialiased	Whether to turn on antialiasing	Boolean	false	true,false
TextureQuality	A quality metric for texturing. High turns on all tricks like anisotropicFiltering	String	medium	low,medium,high
PrimitiveQuality	A quality metric for primitives. Scales how many polygons to use for primitive	String	medium	low,medium,high
Xj3D_InterfaceType	Whether to use Swing or AWT	String	Swing	swing,awt,swing-lightweight,offscreen
Xj3D_NavbarShown	Whether to show the navigation bar	Boolean	true	true,false
Xj3D_NavbarPosition	Where to position the navigation bar	String	Top	Top,Bottom
Xj3D_LocationShown	Whether the current location is shown	Boolean	true	true,false
Xj3D_LocationPosition	Where to position the location bar	String	Top	Top,Bottom
Xj3D_LocationReadOnly	Whether the location is read only	Boolean	false	true,false
Xj3D_ShowConsole	Whether to show the console	Boolean	false	true,false
Xj3D_OpenButtonShown	Whether to show a content Open button	Boolean	false	true,false
Xj3D_ReloadButtonShown	Whether to show a content Reload button	Boolean	false	true,false
Xj3D_StatusBarShown	Whether to show a status bar	Boolean	false	true,false
Xj3D_FPSShown	Whether to show a Frames Per Second meter	Boolean	false	true,false
Xj3D_ContentDirectory	The initial directory to load content from	String	Current Directory	All
Xj3D_AntialiasingQuality	How many multisamples to use for antialiasing. Must be enabled to matter.	String	low	low,medium,high
Xj3D_PreferredDimensions	Preferred size of the rendering surface in pixels Contains both width and height. Required when the interface type is "offscreen"	String	640x480
Xj3D_Culling_Mode	What sort of visual culling to do	String	frustum	none, 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();
        requestedParameters.put("Xj3D_ShowConsole",Boolean.TRUE);

        // 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

        System.setProperty("x3d.sai.factory.class", "org.web3d.ogl.browser.X3DOGLBrowserFactoryImpl");
        X3DComponent x3d_comp = BrowserFactory.createX3DComponent(requestedParameters);

Using Multiple 3D Windows

Xj3D Specific Options

Xj3DBrowser

You can find the complete example in Xj3DSpecificDemo.java.

Skins

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);

Sensor Cursors

• touchSensor.cursor
• dragSensor.cursor
• anchor.cursor

Navigation Mode Cursors

• WALK.cursor
• EXAMINE.cursor
• PAN.cursor
• FLY.cursor
• TILT.cursor

Location Buttons

• GO.button
• OPEN.button
• RELOAD.button

Navigation Buttons

• EXAMINE.button
• FLY.button
• PAN.button
• TILT.button
• WALK.button
• HOME.button
• FITWORLD.button
• LOOKAT.button
• NEXTVIEW.button
• PREVIOUSVIEW.button

Other

• CONSOLE.button

Input Devices

Heavyweight Swing Issues

Java Webstart deployment

Java WebStart Example

Professional Training