BS Contact J Specification
| previous next contents |
|
BS Contact J Specification |
|
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
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.
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.
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.
In creating an API that satisfies the above functional requirements, the following design goals should be considered:
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.
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.
The API should be easy to read, understand, and remember.
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.
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.
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.
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.
Members:
PROPERTY_NAME, PROPERTY_VERSION, PROPERTY_HEADLIGHT, PROPERTY_BOUNDVIEWPOINT
Methods: 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
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.
Methods: 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
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.
Members:
EVENTIN, EVENTOUT, EXPOSEDFIELD
SFBool, SFColor, SFFloat, SFImage, SFInt32, SFNode, SFRotation, SFTime, SFVec2f, SFVec3f
MFColor, MFFloat, MFInt32, MFNode, MFRotation, MFTime, MFVec2f, MFVec3f, UNKNOWN_FIELD
Methods: 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 3getName 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
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().
Members:
ANCHOR_CLICKED, FIELD_CHANGED, INITIALIZED, LAST_IDENTIFIER, SHUTDOWN, URL_ERROR, URL_LOADED
Methods: 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.
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.
Members:
PICK_MATRIX, PICK_MOUSE, PICK_NODE, PICK_PATH, PICK_RAY
Members: 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
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.