Xj3D 2.0 VRML/X3D Code API

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

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.


Xj3D 2.0 VRML/X3D Code API

Copyright © 2001 - 2006 Web3D Consortium