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(使用SAI来载入和操纵X3D场景). 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.

VRML(虚拟现实建模语言，是一种用于建立真实世界的场景模型或人们虚构的三维世界的场景建模语言，也具有平台无关性。) programmers may be familiar with the EAI,

External Authoring Interface. The EAI was

the way to access VRML scenes externally(EAI是访问VRML创建的场景的一种方法). It differed from the method of internal

scripting(它不同于内部脚本). The SAI has merged these

two programming models(SAI融合了这两种编程模型). 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(要把xj3d的各个jar的绝对路径添加到classpath中，但是，如果用Eclipse环境开发，则需要把这些jar导入工程的lib中).

You can find the required jars in the precompiled releases of Xj3D.

The following jars are always required:

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

Xj3D supports multiple renderers(支持多renderer). 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(是行业领域中最为广泛接纳的

2D/3D 图形 API) renderer.

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  (Java3D renderer

必须的jar)

For the OpenGL

renderer you will need JOGL

installed(如果使用OpenGL renderer,则需要安装

JOGL). You can download JOGL here: JOGL

Project. You will also need the following jars from Xj3D in

your classpath:

xj3d-ogl.jar  (OpenGL

renderer 必须的jar)

aviatrix3d-all.jar

vecmath.jar - This is available from the Java3D

project

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

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(默认使用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

Xj3DBrowser

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.

Skins

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：

import

java.awt.*;

import

java.util.HashMap;

import

javax.swing.*;

import

org.web3d.x3d.sai.*;

public class

SimpleSAIDemo extends JFrame {

private

static final long serialVersionUID = 1L;

public

SimpleSAIDemo() {

setDefaultCloseOperation(EXIT_ON_CLOSE);

Container contentPane =

getContentPane();

//

设置浏览器参数

@SuppressWarnings("rawtypes")

HashMap requestedParameters =

new HashMap();

//

创建SAI组件

X3DComponent x3dComp =

BrowserFactory.createX3DComponent(requestedParameters);

//

将SAI组件转换成UI组件

JComponent x3dPanel =

(JComponent)x3dComp.getImplementation();

contentPane.add(x3dPanel,

BorderLayout.CENTER);

//

获取外部浏览器

ExternalBrowser x3dBrowser =

x3dComp.getBrowser();

setSize(800,400);

setVisible(true);

//

通过载入x3d文件创建一个场景。该过程阻塞至完成载入文件

X3DScene mainScene =

x3dBrowser.createX3DFromURL(new String[] { "Billboard.x3d" });

//

将新场景更新到浏览器

x3dBrowser.replaceWorld(mainScene);

}

public

static void main(String[] args) {

@SuppressWarnings("unused")

SimpleSAIDemo demo = new

SimpleSAIDemo();

}

}