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