Xj3D Architecture

Author: Justin Couch
Last updated: $Date: 2004-04-30 04:50:26 $
Revision: $Revision: 1.3 $


Xj3D is a collection of code that implements the X3D specification to provide a VRML and X3D browser. There are also many other goals in producing this codebase. The motivation for the design decisions and architecture of the underlying codebase is explained here.


The basic codebase started with a donation from Sun Microsystems' Java 3D group in 1999. This code was a basic VRML 97 capable browser and simple viewer. Slow progress on the codebase was aimed at providing more complete capabilities.

With the start of the X3D specification it was decided to use this codebase as the basis for experimentating with how the specification could be implemented. The new specification, having both the traditional UTF-8 encoding and an XML encoding, had a lot more flexibility. With XML, it would provide the ability to access it using the web browser using the Document Object Model. At the same time, there was a desire to merge the internal scripting and external authoring interface with a more complete system. Both had strengths, but also suffered significant weaknesses.


Although the original codebase was aimed at just providing a browser to see content with. While this is an acceptable goal, it was felt by some of the developers that a wider set of goals for the code would also be useful to help adoption of the new coming specification. Also, because the code was to aid an experimental role of an unknown specification, it would pay to be as flexible as possible.

In the architecture you see here, there are three primary goals:

  1. Provide proof that the full X3D specification can be implemented.
  2. Build code to encourage working groups to experiment with extensions.
  3. Encourage adoption of the specification by dividing the code into a lot of smaller reusable components that can be incorporated into other applications.
From this, you can see that performance is not a goal of this codebase. We do attempt to provide efficient implementation of algorithms, but it is not the primary motivator of the architecture. We do not pretend to present a high performance browser implementation. If you require this, then we suggest that you purchase one of the commercial browsers available.

Structural Overview

The structural overview will provide a description of the basic components, why they are this way and how they relate to each other. A description of each component with more detail is found in the Component Summary section.

Figure 1 presents the UML component diagram of the main parts of the architecture. Each component represents something that could be taken as a separate piece and used within an application. Although it would be possible to use smaller parts of a given component, the design does not cater to this use as it is prefered to use the larger parts.

Figure 1: UML Component Diagram of the Xj3D Architecture

We break the components into areas that represent a distinct set of functionality that may operate standalone. There is no real central component, although the functionality revolves around the X3D abstract specification and therefore our abstract internal model of the same. This component represents the core of the scene graph as presented by VRML and the abstract model.

The basic goal of the architecture is to provide separated components that are not interdependent. You should be able to build a heirarchical set of relationships amongst the components starting from a minimal set and expanding outwards. In order to do this, the majority of the functionality is designed as a set of interfaces, over which an implementation is provided. Thus the abstract required functionality is described by the interface and one component only makes use of another component's services through the interface. A user can then replace piecemeal parts of the implementation with thier own custom functionality should the desire arise.

The structure of interfaces and implementations is mirrored right through the design - down to the lowest level. As you look into each component, the interactions between parts of the component are described in the same way. The goal is that no piece of code shall contain circular compilation dependencies. If there is a need for this, the design is wrong or not correctly abstracted, and the changes are made. Thus, you will see cases where there is an interface used to define something that is effectively a private communication between two separate classes.

Around the core set of components, there are more components that either make direct use of a renderer or provide a shell to it. These components are the way that a typical end-user of the toolkit would interact with the codebase. For example, in the Java3D world, they like to use a system called a loader, which provides a common abstraction of the file loading process that is independent of the file format. However, a user in a Web browser, may want to interact with an XML Document and through the DOM model, so we need to provide components that deal with the DOM-specific integration issues.

Component Summaries

In the following sections we give a brief outline of each component and what it does. In a future revision of this document, it will include links to much more detailed documentation for each component.

Browser Core

The VRML model assumes a core set of functionality that a browser must provide. These are simple things like details about the browser implementation, status information and the functionality represented by the various objects known as Browser in the specifications. This component presents the abstract representation and some basic implementation of this capability. Some parts are, by definition, renderer-specific and so interfaces are used to represent the required functionality.

VRML Abstract Node Model

The abstract model is the representation of the abstract model defined by the X3D specification (ISO/IEC 19775-1). These describe all of the functionality that would be needed to implement a runtime model regardless of the renderer used.

External Interaction

Both VRML97 and X3D define APIs to create and manage a browser. Despite the different APIs, there is a great deal of commonality required and this component provides the needed infrastructure and implementation.

Scripting Interaction

Both VRML97 and X3D define scripting APIs. Scripting is progammatic access to the scene graph using a number of languages. The functionality is similar regardless of language and this component represents and manages all of the scripting interactions.

Event Model Evaluation

The runtime handling of the VRML event model is provided by this package. All aspects are at least represented here, but not all implemented. Some parts of the event model require intimate knowledge of the rendering engine being used so where this is required, interfaces are defined. All functionality is defined as interfaces, and where it can be renderer-independent, it will provide a default implementation that is specification compliant.


Taking a basic file or stream of bytes and turning it into a running scene graph is the job of the parsing component. In this design, the parsing is a standalone process that has no idea about the nodes. The component's only role is to process the stream and issue a series of events that describe the structure to a listener. It is up to the rendering component and others to make use of the event information to build a live, running scene graph.


VRML, as file format and runtime system is very heavily dependent on networking interaction. Anything but the most trivial file will reference at least one external file, in the form of a texture, script, externproto or inline. In order to support the more advanced extensions to VRML, such as the Universal Media Library, we need to support URNs as well as the more common URLs. These are not supported in the core JDK toolkits, so this component provides all of the low-level interfaces for dealing with fetching and processing content at the lowest level.


At the lowest level of 3D graphics rendering, there is a rendering API. This has the job of taking the instructions provided by the VRML scene graph and turning it into something real. As figure 1 shows, there are a number of different renderers, so this section will break down the design of each renderer and explain how it operates in the global context.

Java3D Loaders

One of the most popular extensions to the core Java3D rendering API, is the Loader interface. This interface, as part of the utilities toolkit provided by Sun, is an abstraction of the file loading process that is independent of the file format to load. VRML is just one of many (see the J3D loader archive for more details). This component is our implementation of the Loader interface to load VRML97 and X3D files.

Vector Maths

3D graphics requires a lot of vector maths. This component provides an efficient, standalone representation of the code that performs this function.


Many applications don't want to restrict X3D information to just 3D land. In applications like editors and data visualisers, a 2D view of the data is wanted as well. This component provides a number of useful utility classes for use within a Swing environment.

Within the current code, we are staying to the lower level DOM classes. That is, all the components presented here will work with any DOM tree passed to it. There is no requirement to use X3D trees. In is envisaged that in the future X3D specific components will be added to the mix here.


[ Xj3D Homepage | Xj3D @ Web3d | Screenshots | Dev docs | Dev Releases | Contributors | Getting Started ]
Last updated: $Date: 2004-04-30 04:50:26 $