Xj3D 2.0 VRML/X3D Code API

Xj3D is a series of libraries that form a toolkit that can be used to load and render VRML97 and X3D files.

See:
Description

Packages

org.web3d.browser	Renderer independent interfaces and classes that represent a VRML/X3D browser.
org.web3d.image	UI Toolkit independent image representation.
org.web3d.net.content	Content handler implementation code to allow the Xj3D code to load inline data or run as a standalone system without needing to use other loader interfaces.
org.web3d.net.protocol	Protocol handler implementation code to allow the Xj3D code to load inline javascript and ecmascript scripts.
org.web3d.net.resolve	URN resolver implementation code to allow the Xj3D code to load any item that defines a URN in it's URL field (eg EXTERNPROTO and ImageTexture).
org.web3d.parser	Parser bootstrapping implementations for all available file formats from the Web3d consortium.
org.web3d.sai.util	Utility classes for working with X3D through the SAI.
org.web3d.util	Utility classes that may be useful across a number of the packages.
org.web3d.vrml.export	Writes VRML and X3D worlds out to other encodings or formats.
org.web3d.vrml.export.compressors	Tools for compressing 3D content.
org.web3d.vrml.lang	Classes and interfaces to represent core components of the language structure.
org.web3d.vrml.nodes	Contains the interface definitions for the VRML standard These are seperated into directories based on the proposed X3D profiles mechanism.
org.web3d.vrml.nodes.proto	Utility classes to load and represent PROTO and EXTERNPROTO nodes.
org.web3d.vrml.parser	Abstract representations of parsers for both the file format and individual field values, regardless of encoding.
org.web3d.vrml.renderer	Common code between all renderers in the system.
org.web3d.vrml.renderer.common.browser	Classes for augmenting a full VRML browser implementation without being renderer-specific.
org.web3d.vrml.renderer.common.geospatial	Common classes for handling geospatial issues.
org.web3d.vrml.renderer.common.input	Classes that handle the VRML user interaction with a scenegraph but are independent of the renderer in use.
org.web3d.vrml.renderer.common.input.dis	DIS networking implementation.
org.web3d.vrml.renderer.common.input.movie
org.web3d.vrml.renderer.common.nodes	Generic classes for describing common renderer-independent extensions to the base interfaces in the org.web3d.vrml.nodes package.
org.web3d.vrml.renderer.norender	Generic classes for null renderer implementation of the interfaces speced in the org.web3d.vrml.nodes package.
org.web3d.vrml.renderer.norender.browser	Classes needed to create a full VRML browser implementation based on the nodes and other structures available in the API.
org.web3d.vrml.renderer.norender.nodes	Generic classes for describing null renderer-specific extensions to the base interfaces in the org.web3d.vrml.nodes package.
org.web3d.vrml.renderer.ogl	General classes to allow the construction of a VRML scene graph that uses OpenGL as the rendering mechanism.
org.web3d.vrml.renderer.ogl.browser	Classes needed to create a full VRML browser implementation based on the nodes and other structures available in the API.
org.web3d.vrml.renderer.ogl.input	Classes that handle the VRML user interaction with a scenegraph.
org.web3d.vrml.renderer.ogl.nodes	Generic classes for describing OpenGL renderer-specific extensions to the base interfaces in the org.web3d.vrml.nodes package.
org.web3d.vrml.sav	Simple API for VRML Parsing Similar in design to SAX.
org.web3d.vrml.scripting	Abstract representations of information needed to implement scripting.
org.web3d.vrml.scripting.browser	Common representation of the functionality needed to implement the Browser class in its various incarnations for the different specifications and language bindings.
org.web3d.vrml.scripting.ecmascript	Implementation of glue code for scripts written in ECMAScript and Javascript.
org.web3d.vrml.scripting.external.buffer	This package serves the common needs of the EAI and external SAI classes.
org.web3d.vrml.scripting.external.eai	The classes in this package provide the implementations for the EAI 2.0 classes.
org.web3d.vrml.scripting.external.sai	The classes in this package provide the implementations for the external version of the SAI interfaces.
org.web3d.vrml.scripting.jsai	Implementation of glue code for scripts written in Java.
org.web3d.vrml.scripting.sai	Implementation of glue code for X3D SAI internal scripts written in Java.
org.web3d.vrml.util	Utility classes that are specifically useful for the internals of a VRML node implementation.
org.web3d.x3d.dom.swing	Classes to represent the X3D DOM information with Swing components.
org.web3d.x3d.jaxp	Classes used to build parsers of the XML-encoding to be used with the JAXP optional package.
org.web3d.x3d.sai	The core classes for defining access through both external and internal means to an X3D browser and its contents through the X3D SAI (ISO/IEC 17775-2) interface.
org.web3d.x3d.sai.cadgeometry	Concrete node interfaces of the cadgeometry package.
org.web3d.x3d.sai.core	Concrete node interfaces of the core package.
org.web3d.x3d.sai.dis	Concrete node interfaces of the dis package.
org.web3d.x3d.sai.environmentaleffects	Concrete node interfaces of the environmentaleffects package.
org.web3d.x3d.sai.environmentalsensor	Concrete node interfaces of the environmentalsensor package.
org.web3d.x3d.sai.eventutilities	Concrete node interfaces of the eventutilities package.
org.web3d.x3d.sai.geometry2d	Concrete node interfaces of the geometry2d package.
org.web3d.x3d.sai.geometry3d	Concrete node interfaces of the geometry3d package.
org.web3d.x3d.sai.geospatial	Concrete node interfaces of the geospatial package.
org.web3d.x3d.sai.grouping	Concrete node interfaces of the grouping package.
org.web3d.x3d.sai.hanim	Concrete node interfaces of the hanim package.
org.web3d.x3d.sai.interpolation	Concrete node interfaces of the interpolation package.
org.web3d.x3d.sai.keydevicesensor	Concrete node interfaces of the keydevicesensor package.
org.web3d.x3d.sai.layering	Concrete node interfaces of the layering package.
org.web3d.x3d.sai.lighting	Concrete node interfaces of the lighting package.
org.web3d.x3d.sai.navigation	Concrete node interfaces of the navigation package.
org.web3d.x3d.sai.networking	Concrete node interfaces of the networking package.
org.web3d.x3d.sai.particlesystems	Concrete node interfaces of the particlesystems package.
org.web3d.x3d.sai.pickingsensor	Concrete node interfaces of the pickingsensor package.
org.web3d.x3d.sai.pointingdevicesensor	Concrete node interfaces of the pointingdevicesensor package.
org.web3d.x3d.sai.rendering	Concrete node interfaces of the rendering package.
org.web3d.x3d.sai.rigidbodyphysics	Concrete node interfaces of the rigidbodyphysics package.
org.web3d.x3d.sai.scripting	Concrete node interfaces of the scripting package.
org.web3d.x3d.sai.shape	Concrete node interfaces of the shape package.
org.web3d.x3d.sai.sound	Concrete node interfaces of the sound package.
org.web3d.x3d.sai.text	Concrete node interfaces of the text package.
org.web3d.x3d.sai.texturing	Concrete node interfaces of the texturing package.
org.web3d.x3d.sai.texturing3d	Concrete node interfaces of the texturing3d package.
org.web3d.x3d.sai.time	Concrete node interfaces of the time package.
org.xj3d.core.eventmodel	Interface definitions that provide abstract representations of the runtime processing of the X3D/VRML scenegraph (The event model).
org.xj3d.core.loading	Implementation of a load manager interfaces for externally referenced file within a scene.
org.xj3d.device	Input devices.
org.xj3d.impl.core.eventmodel	Default implementations of the event model implementations defined in the package org.xj3d.core.eventmodel.
org.xj3d.impl.core.loading	Implementations of various content loading strategies that work with the interfaces and structures defined in the package org.xj3d.core.loading.
org.xj3d.io	IO classes that are specifically useful for the internals of the Xj3D runtime implementation.
org.xj3d.loaders.ogl	Implementations of Aviatrix3D file loaders for Web3D file formats.
org.xj3d.sai	Proprietary Xj3D Extension interfaces above the normal X3D specification defined SAI interfaces.
org.xj3d.ui.awt.browser.ogl	Classes that are used to create or be a full browser panel embedded within an application using the OpenGL renderer.
org.xj3d.ui.awt.device	Device classes dependent upon the AWT ui toolkit.
org.xj3d.ui.awt.device.keyboard	Generic keyboard input device.
org.xj3d.ui.awt.device.ogl.mouse	Generic mouse input device.
org.xj3d.ui.awt.net.content	AWT UI Toolkit dependent content handling.
org.xj3d.ui.awt.widgets	A collection of AWT and Swing components that can be used in browser interfaces.
org.xj3d.ui.construct	Classes that are used to build and provide basic functionality to an Xj3D browser instance.
org.xj3d.ui.construct.event	Event objects and listeners for the Xj3D browser constructs.
org.xj3d.ui.construct.ogl	Classes that are used to build and provide basic functionality to an OGL Xj3D browser instance.
org.xj3d.ui.swt.browser.ogl	Classes that are used to create or be a full browser panel embedded within an application using the OpenGL renderer.
org.xj3d.ui.swt.device	Device classes dependent upon the SWT UI toolkit.
org.xj3d.ui.swt.device.keyboard	Generic keyboard input device.
org.xj3d.ui.swt.device.ogl.mouse	Generic mouse input device.
org.xj3d.ui.swt.net.content	SWT UI Toolkit dependent content handling.
org.xj3d.ui.swt.util	SWT UI Toolkit specific utility functions.
org.xj3d.ui.swt.view	An Eclipse View plugin of the Xj3D Browser.
org.xj3d.ui.swt.widgets	A collection of SWT widgets that can be used in browser interfaces.
vrml	Classes defined by the VRML97 specification Annex C that provide integration of Java-based scripts into the VRML runtime environment.
vrml.eai	The core classes for defining access to a VRML browser and its contents through the EAI2 (ISO VRML97 Part 2) interface.
vrml.eai.event	The classes and interfaces for events that can be generated by and EAI2 capable browser.
vrml.eai.field	The classes for defining field interfaces to nodes.
vrml.field	Classes defined by the VRML97 specification Annex C that define the types of field access that can be given to a node.
vrml.node	Classes defined by the VRML97 specification Annex C that define the types of nodes that can be available in the scripting.

Xj3D is a series of libraries that form a toolkit that can be used to load and render VRML97 and X3D files.

The aim of the codebase is to provide a series of easily separable components to enable VRML and X3D content either as a full browser, static geometry or even as a component of a bigger application. The major goal of the code is to provide a highly flexible set of libraries that you may take and use to generate renderable content. If you combine them all together you could create a complete browser that we intend to be spec-conformant. The codebase itself is not a VRML/X3D browser, although you can create one from this code (see some of the example and apps directories along with this distribution for an idea how).

The code is broken into 5 major sections:

1. Low level VRML and X3D lexical parsers with a callback based API
2. Definitions of VRML and X3D content, structure and generators
3. Various renderer implementation of the internal structured scenegraph (OpenGL, Java3D, null and mobile)
4. Various utilties built over the frame work, such as compression systems and format transformation
5. Implementations of the EAI and external SAI to allow access to X3D/VRML content in a browser-independent, spec-conformant manner without you needing to get caught up in the details of Xj3D's internals.

Using the Code

When you start to use the code in an application, it will not automatically allow you to do everything. For example, standard Java 3D loaders do not support the idea of scripting or of Inline content. To deal with this, you must also perform some auxillary support work so that everything works as expected.

Note: In general, we recommend that you only use the SAI classes to interact with Xj3D. By far the majority of the applications do not need anything more complex than that interface.

Loading External Content

To make life easier for our implementation, we have made use of quite a number of 3RD party libraries to build a fully capable browser. The major reason for this is that the inbuilt Java libraries are pretty terrible for the requirements of a VRML browser. Firstly we need full URI support - Java does not handle URNs that are used by the Universal Media libraries. Next, the image loading of standard Java is very bloated, consuming way too much memory. Then, to transport them across to the texture mapping used we have to make several copies of the image each time, so we bring in a library for more efficient image handling.

The next step is to use local libraries for specific areas such as Java 3D support. These libraries make a lot of things simpler by allowing us to not have to code them again. There are many similarities between VRML and the 3D graphics scenegraph APIs and these libraries act as the translator between the two systems.

Preparation Work

Internally the code does not connect a lot of the parts together. For example, Inlines are not automatically loaded as there are cases where you don't want the code to handle them. You may also want to specifically handle different content. Therefore, the Inlines are only loaded once you register the appropriate handlers with the URI system. We won't detail that here, but refer you to the applicable packages - org.web3d.net.content and org.web3d.vrml.nodes.loader. There are a collection of properties and factories that need to be set if you want loading of external files like textures, scripts and Inlines to work correctly.

XML Integration

Xj3D can process X3D content that exists as part of a larger multinamespace XML document. The exising X3D spec is currently not well defined about this, so we have taken a few liberties until a firm specification is defined.

In the case where X3D is the containing document, and is the unnamespaced portion of the XML elements, we handle this transparently. You need to do nothing special. Any elements that have a namespace prefix are ignored and disposed of during the parsing process by the Xj3D browser.

If you wish to apply a namespace to the X3D nodes, then we use a fixed URI to detect this. If there is a xmlns: attribute on the X3D root element, we look at the value of that attribute to determine if you are declaring the namespace to be the X3D namespace. If we see the exact value of

  http://www.web3d.org/specifications/x3d-namespace

Then we take the pre-defined prefix to be the X3D namespace prefix. For example:

<X3D version='3.1' profile='Interchange'
 xmlns:x3dns='http://www.web3d.org/specifications/x3d-namespace'
 xmlns:foo='http://www.foo.com/mynamespace'
 >
 <x3dns:head>
 ...

and

<X3D version='3.1' profile='Interchange'
 xmlns:bar='http://www.web3d.org/specifications/x3d-namespace'
 xmlns:foo='http://www.foo.com/mynamespace'
 >
 <bar:head>
 ...

will both generate valid and identical X3D content for viewing.

System Properties

There are two ways of controlling the runtime configuration of Xj3D. Apart from providing your own implementation of the various toolkits, the standard Java mechanisms of properties files and system properties also apply.

Property Files

Property files are used to control large collections of properties. The following properties files are used by the system (path information is relative to the CLASSPATH as per System.getProperty()):

config/2.0/spec/vrml.properties

Defined by the EAI to control various items of configuration. Principally used to set the default factory class to use for BrowserFactory

config/3.x/spec/x3d.properties

Defined by the EAI to control various items of configuration. Principally used to set the default factory class to use for BrowserFactory

config/3.x/XMLcontainerfields.props

Mapping of node element names to the default containerField attribute value. Used when the XML parsing is not validating and so we don't get the values directly passed to us.

Configuration files are all kept in a directory config/spec_version with separate sub directories. These can be overridden by the user as needed by providing their own replica directory structure that is locatable within the CLASSPATH.

System Properties

The codebase makes reasonable use of system properties to allow the modification of its behaviour. These properties are sprinkled liberally about the code, making them sometimes hard to find. This is a summary of all those properties. Please be aware that these will need to be set before you run any code from this library because most of them will be used during the construction phase of any class.

org.web3d.vrml.nodes.loader.threads

The number of concurrent threads to be started to do loading. There are two areas which use this - script loading and all other files. Each loader creates this number of threads in the pool.

org.web3d.vrml.parser.field.factory

The name of the class that implements the FieldParserFactory interface, which is used for parsing individual field values.

org.web3d.vrml.parser.file.factory

The name of the class that implements the VRMLParserFactory interface, which is used for parsing files.

org.web3d.xj3d.script.loader.class

The name of the class that implements the org.web3d.vrml.nodes.loader.ScriptLoader interface, which is used for loading scripts.

org.web3d.xj3d.script.manager.class

The name of the class that implements the org.web3d.vrml.nodes.runtime.ScriptManager interface, which is used for managing scripts.

org.web3d.xj3d.file.loader.class

the name of the class that implements the org.web3d.vrml.nodes.loader.ExternalLoadManager interface, which is used for loading content other than scripts.

org.web3d.xj3d.router.manager.class

The name of the class that implements the org.web3d.vrml.nodes.runtime.RouteManager interface, which is used for managing routes.

org.web3d.xj3d.router.factory.class

The name of the class that implements the org.web3d.vrml.nodes.runtime.RouterFactory interface, which is used for creating routers.

org.web3d.xj3d.frame.state.class

The name of the class that implements the FrameStateManager interface, which is used for managing per-frame state.

org.web3d.xj3d.sensor.manager.class

The name of the class that implements the org.web3d.vrml.renderer.j3d.input.J3DSensorManager interface, which is used for managing sensors. There are renderer-specific sub-interfaces of this interface which the implementing class must also adhere to.

org.web3d.xj3d.eventmodel.evaluator.class

The name of the class that implements the org.web3d.vrml.nodes.runtime.EventModelEvaluator interface, which is used for runing the event model.

org.web3d.vrml.nodes.staticgroup.dispose

Boolean value describing whether the static group should dispose of the VRML node children. This is an efficiency measure that will allow an implementation to remove unneeded memory. However, it also means that they can no longer be traversed, so if your application is trying to traverse the scene graph, it will not be able to use the nodes later on. Useful for a runtime optimisation, no good if you are writing an editor. Defaults to false.

org.web3d.vrml.nodes.staticgroup.compact

Boolean value describing whether the static group should compact the VRML scenegraph below this node or leave it in an expanded state. This is an efficiency measure that will allow an implementation to flatten the scene graph if desired. Useful for debugging but also means the runtime scene graph will probably be different from the original loaded from file. Defaults to false.

org.web3d.vrml.nodes.fontstyle.font.size

The font size in points. The default value is 36 point font.

org.web3d.vrml.renderer.common.nodes.shape.rescale

The method to use for rescalling textures. Valid values are "NEAREST_NEIGHBOR, BILINEAR"

org.web3d.vrml.renderer.common.nodes.shape.useTextureCache

Whether to cache textures for later reuse. This caches by URL which might be incorrect for some dynamic systems. It improve performance for files which don't use DEF/USE for textures.

org.web3d.vrml.renderer.common.nodes.shape.maxTextureSize

The maximum texture size to use. By default texture sizes are unlimited. Textures with a dimension over this value will be resized. The resizing will try to preserve the aspect ratio. This must be a power of two.

org.web3d.vrml.renderer.common.nodes.shape.useMipMaps

Set to a value of "true" in order to generate mip maps for textures.

org.web3d.vrml.renderer.common.nodes.shape.anisotropicDegree

Sets the anisotropic filtering degree. Values above 1 cause mip mapping to be turned on as well.

org.web3d.vrml.renderer.ogl.nodes.hanim.allowHardwareHumanoid

Set to a value of "true" in order to allow the use of hardware-accelarated rendering of the HAnim humanoid. Otherwise, always uses software rendering.

Further Reading

• This software is released under the GNU LGPL
• The Xj3D Homepage
  • Node implementation status
  • Extensions that are added to Xj3D
  • Development Snapshots to be downloaded if you don't want to build from source.
• The VRML97 ISO Specification International Standard ISO/IEC 14772-1:1997 and VRML97 EAI Specification ISO/IEC 14772-2:2002.
• The X3D FCD ISO Specification text. There are 3 specifications in various stages of development:
  • 19775 - The main X3D abstract spec
  • 19776 - The file format (encodings) spec
  • 19777 - The programming language bindings to the SAI
• For details on URIs see the IETF working group: URN

External Code

Xj3D is a huge project that is a collborative effort in more ways than one. Where possible, we like to build on top of the work of others. These are the projects and libraries that we make use of in order to build this toolkit.

• JOGL (Java OpenGL) bindings
• JOAL (Java OpenAL) bindings
• JInput Abstract Java bindings to the HID specification.
• Sun's Java 3D
• Sun's JavaCOMM for abstract serial port handling (so we can interface to older devices like gloves, wands, HMDs etc).
• j3d.org The Java 3D Community Site
• J3D.org's Code Library for Java 3D specific code features.
• J3D.org's Aviatrix3D Project for an OpenGL scenegraph written in Java.
• Geotools2 project provides the coordinate transformation services for implementing the Geospatial component. Most of the code uses the abstract GeoAPI that is an implementation of the OpenGIS Consortium specifications.
• JSR 108 Unit-Handling specification code
• NPS DIS-Java library for the DIS implementation.
• ODE-java Java bindings to the Open Source Open Dynamics Engine that provides our rigid body physics capabilities.
• Rhino ECMAScript Engine for providing VRML97 Annex C and X3D ECMAscript support. Rhino is a product of the Mozilla project licensed under the NPL/GPL dual license.
• GNU Regexp library (v1.0.8)
• HTTPClient v0.3-3
• Justin Couch's URI Library home page:
• For better image format support than the defaults provided by Java 3D, try Justin Couch's ImageLoader library. The codebase does not use this directly, but it fits with the URI handling code to expand and produce much, much more efficient texture loading support (also uses native code!)