previous   next  contents

BS Contact J Specification

5 Programming API

5.1 Introduction and Contents

5.1.1 Table of contents

5.1 Introduction
    5.1.1 Table of contents
    &5.1.2 Description
5.2 Functional Requirements
5.3 Design Goals
    5.3.1 Completeness
    5.3.2 Clarity
    5.3.3 Extensibility
    5.3.4 Speed
5.4 Functional Description
    5.4.1 Browser Interface
    5.4.2 Node Interface
    5.4.3 Field Interface
    5.4.4 EventObserver Interface
    5.4.5 PickInfo Class
    5.4.6 X3DException

5.1.2 Description

This document describes an application programmer interface, or API, for the Core X3D specification. The API is designed to meet a set of functional requirements and design goals.

Three descriptions of the API are provided:

Functional requirements and design goals are copied from ShoutInteractive's proposal for X3D.

5.2 Functional Requirements

The following is the set of tasks that the API must support. This set is necessary and sufficient for enabling programmers to write applications that create and interact with scene graphs, windows and devices.

  1. Access Nodes and Fields:
    1. Create nodes
    2. Access and modify fields within nodes
    3. Arrange nodes in a hierarchy
    4. Access nodes by name
  2. Operate on Scene Graphs:
    1. Load scenes into the application
    2. Control rendering of scene graphs
    3. Intersect rays with objects in scene graphs
    4. Search for nodes within scene graphs
  3. Communicate:
    1. React to external events (device events, window events)
    2. Find out when the implementation has completed requests (rendering, asset loading, file reading)
    3. React to field changes (field changed events)
  4. Extend:
    1. Use additional VRML 97 nodes

Extend: An extended profile might want to support additional VRML 97 nodes. A Core X3D browser might be enhanced with additional parsing and rendering capabilites by just adding additional classes for these nodes. <TBD> whether that should extension mechanism must be provided by every Core X3D browser and whether the methods the interfaces should be standardized.

5.3 Design Goals

In creating an API that satisfies the above functional requirements, the following design goals should be considered:

5.3.1 Completeness

The API should meet all of the functional requirements. Programmers should be able to access all the functionality without requiring additional support from a given implementation. This does not mean that the API should contain a way to do everything. But the API must be enabling: programmers should feel that they have access and control of all aspects of the Core.

5.3.2 Compactness

Only functionality that is required from every implementation is to be included in the Core API. Every interface, class, method and public member variable in the API must support one of the functional requirements. A compact API has the following benefits:

Ease of Implementation: If the set of Core field and node types is small, and the API is compact, there are fewer methods, classes, and interrelationships to implement. Any capable 3D programmer should be able to comprehend the entirety of the specification and imagine a clear path for implementation.

Flexibility: Each required class or method in an API reduces the number of paths toward implementation. There is at least some small implementation bias inherent in any such decision. The more compact the API is, the smaller the bias and the greater the flexibility for those implementing it to use their own special approaches and techniques.

Small Code Footprints: Only if the API is compact can implementations be compact. By keeping the requirements to a bare minimum, the API allows for tiny implementations. Additionally the number of classes and interfaces is kept as small as possible to avoid code overhead.

5.3.3 Clarity

The API should be easy to read, understand, and remember.

5.3.4 Extensibility

The Core API is minimal, yet far more complex profiles are to built upon it; hence, the API must provide straightforward ways to add extensions. It should be easy to add new classes of nodes that work with the rest of the system.

5.3.5 Speed

The API must accommodate implementations that wish to run as quickly as possible. This means that the API must provide fast access to the data in scene graphs, avoiding extra layers of accessor methods wherever possible. It also means that the API must not force implementations to use particular patterns of node traversal or access in performing operations on scene graphs.

5.4 Functional Description

The Core X3D API is comprised of the following sets of classes and interfaces. Alternate, but equivalent, definitions of the API may be found in the IDL and JavaDoc sections.

It uses mainly interfaces to avoid dependencies of particular X3D browsers when compiling the API. In addition each X3D browser can be implemented in any way, e.g. as applet, as plugin, COM object.

5.4.1 Browser Interface

This is the main interface that a Core X3D browser must implement. It can be used to control loading and rendering of a scene. This interface "owns" and renders the scene. The scene may be set either by loading an URL or by passing in the scene root. Programmers may ask for nodes in the current scene by DEF name, update the scene, register for events and pick information. I also provides string based methods for fields of nodes that can be used directly from Javascript.

Members: The Browser interface defines some constant strings that can be used in the getProperty() method.

addAWTObserver Add an observer for AWT events
addBrowserObserver Add an observer for browser events
addRoute Add a route between two nodes
beginUpdate Lock the output from the external interface to the browser as the code is about to begin a series of update
bindNode Set a bindable node, e.g. Viewpoint
createX3DFromString Parse the given string and turn this into a list of X3D nodes
createX3DFromURL Create and load X3D from the given URL
deleteRoute Delete a route between two nodes
endUpdate Release the output of events from the external interface into the X3D browser
getCamera Get the current position and orientation of the camera
getNode Get a DEF node by name
getNodeField get node eventout by string, usable from script
getProperty Get a browser property
getWorld Get the current root nodes
getWorldURL Get the fully qualified URL of the currently loaded world.
loadURL Load the URL as the new root of the scene
pick Send a ray and get information about the closest geometry that was hit by the ray specified by a mouse position.
pick Send a ray and get information about the closest geometry that was hit by the ray specified by start point and direction.
removeAWTObserver Remove an observer for AWT browser events
removeBrowserObserver Remove an observer for browser events
replaceWorld Replace the current world with the given nodes
setNodeField set node eventin from string, usable from script

5.4.2 Node Interface

There is only one interface for all types of nodes. This allows to extend it in other profiles. Fields store the data that parameterize nodes. The node interface provides access to its fields.
A node can be identified by its type. The type is the name exactly as it is used in the X3D file.

getField Get any field for this node, either EventIn, EventOut or exposedField.
getName Get the name this node.
getType Get the type of this node

5.4.3 Field Interface

The interface to any X3D field. Provides all methods available on fields.

Members: The Field interface defines constants for the access type, e.g. EVENTIN and type, e.g. SFBool of the field. The X3D browser will set these types for each field.

SFBool, SFColor, SFFloat, SFImage, SFInt32, SFNode, SFRotation, SFTime, SFVec2f, SFVec3f
MFColor, MFFloat, MFInt32, MFNode, MFRotation, MFTime, MFVec2f, MFVec3f, UNKNOWN_FIELD
addObserver Add an observer for a field with read capability (EventOut or ExposedField) the observer object will be notified of any changes to this field
getAccessType Get the access type of this field, e.g. EVENTIN
getLength get the number of values in this field, returns the number of single values,
e.g. an SFVec3f has the length 3
getName Get the name of this field
getType Get the basic type of this field
getValueBool get the value of an SFBool
getValueDouble get the value of an SFTime
getValueDoubleArray get the value of an MFTime implementations may return a reference instead of a copy of the data of the field if the applications changes data in the returned array, the field must be notified using setValue(array)
getValueFloat get the value of an SFFloat
getValueFloatArray get the value of an SFVec3f, MFFloat, etc.
getValueInt get the value of an SFInt32
getValueIntArray get the value of an MFInt32 implementations may return a reference instead of a copy of the data of the field if the applications changes data in the returned array, the field must be notified using setValue(array)
getValueNode get the value of an SFNode
getValueNodeArray get the value of an MFNode
getValueString get the value of an SFString
getValueStringArray get the value of an MFString implementations may return a reference instead of a copy of the data of the field if the applications changes data in the returned array, the field must be notified using setValue(array)
removeObserver Remove a observer for changes in this field. the observer has been added before with addObserver
setValueBool set the value of an SFBool
setValueDouble set the value of an SFTime
setValueFloat set the value of an SFFloat
setValueInt set the value of an SFInt32
setValueNode set the value of an SFNode
setValueString set the value of an SFString
setValueDoubleArray set the value of an MFTime
setValueFloatArray set the value of an SFVec3f, MFFloat, etc.
setValueIntArray set the value of an MFInt32
setValueNodeArray set the value of an MFNode
setValueStringArray set the value of an MFString

5.4.4 EventObserver Interface

Interface that must be implemented by applications that are registered for browser or field events.
An X3D browser will use the interface to notify an observer whenever one of the defined events occurs.

Members: The EventObserver interface defines constants for event type, e.g. FIELD_CHANGED. The X3D browser will set the type when triggering onEvent().

onEvent This method is called from the X3D browser whenever an AWT event happens, see Component.handleEvent.
onEvent This method is called from the X3D browser whenever one of the X3D or browser events happens.

5.4.5 PickInfo Class

The pick method always picks the closest object that is hit by a ray or picked using the mouse position. Objects "behind" the closest object can be picked by repeating the pick with the closest node as start.

The object with the pick information. The member variables that hold the information can be accessed directly without specific methods.

Members: The PickInfo class defines constants for the type of information that was requested, e.g. PICK_CLOSEST and PICK_NODE. The X3D browser will set the information.

hitGlobal the closest point that was hit in global coordinates.
hitLocal the closest point that was hit in local coordinates.
info the info which information was retrieved
matrix the 4x4 matrix that transforms from local to parent space
nodePath the path from the hit node to the top of the hierarchy ordered front to back

5.4.6 X3DException Class

The API must provide at least minimal support for error checking. A standard way to check for errors while executing methods is through exceptions. To keep the API lightweight, only one exception class is required. Implementations are free to extend X3DException to provide finer-grain error feedback. The X3DException class has no methods or member variables.