The Virtual Reality Modeling Language Specification

B. External Programming Interface Reference

Version 2.0, Official Draft #3, ISO/IEC 14772

July 15, 1996


*** IMPORTANT NOTE ***

This annex of the specification is under discussion. It is not officially accepted as part of the specification. If consensus can be reached, it may be official by the August 4th deadline. Otherwise, it will be in the next revision of the spec ...

Also. note that this section needs to be written in a language-neutral manner. The specific language bindings for Java and JavaScript belong in separate appendices.

B.1 Introduction

For communication between a VRML world and "the outside" an external API for VRML is needed. By "the outside" I mean whatever environment the VRML browser is running in. In this proposal the interface internal to the VRML world (the internal interface)is separated from the interface on the outside (the external interface). The external interface must be bound to the environment, whether this is Java or some other language, or some sort of network aware socket interface. I will describe the internal interface here and give semantics (but not syntax) for the external interface. A separate document will explore some potential external bindings.

B.2 VRML 2.0 API

Nodes in VRML can be named using the "DEF" construct. This naming gives a convenient mechanism for accessing nodes from an external interface. Any node named with the DEF construct can be accessed from outside the VRML world. A node so named is referred to as an accessible node. Access to the node's internal data structures from the external API is limited to the eventIns and eventOuts of that node. The external API can send an eventIn to a accessible node and that node will receive that event just as if that event had come through a ROUTE. When an eventOut is sent from an accessible node that event is sent through the external API for handling.

B.2.1 Language Access

External access to the VRML world will typically be done with an API on some scripting language. An example of this would be Netscape's JavaScript interface known as LiveConnect. This interface allows a plug-in (such as a VRML browser) to expose a set of methods callable from JavaScript or Java on the HTML page. The syntax for such an implementation is outside the scope of this document. The details on the implementation of bindings for a few languages see the VRML External API Bindings document.

For consistency this document contains a C-like language independent syntax for the external bindings. This syntax is to be used as a guide for creating a binding to a particular language. Some languages may be able to use this syntax as is, while others will have to change it to meet language requirements. But all implementations should match the methods and parameterization given, regardless of final syntax.

B.2.2 Member Functions

Conceptually, the external API provides an interface to the eventIns and eventOuts of accessible nodes, and an interface to the Browser API. One of the Browser API calls allows a pointer to a node to be obtained, given a DEF name string. Once this node pointer is gotten the eventIns and eventOuts of that node can be accessed. Three operations are required on the events of a node. The external language must be able to send a typed eventIn to the given node. It must also be able to be activated (have a method called) when an eventOut is generated from a given node. Finally, it must be able to read the current value of an eventOut of a given node.

Once obtained, a node pointer contains member functions which are equivalent to the eventIn and eventOut names of that node. For instance, given this node:

SomeNode {
    eventIn  SFTime startTime
    eventOut SFBool isActive
}

When a pointer to SomeNode is obtained it has 3 member functions:

void   startTime(SFTime value);
void   isActive(void *callback, SFInt32 id);
SFBool get_isActive();

The first function sends an eventIn to startTime. The second sets an implementation specific callback, called when the isActive eventOut is generated by the node. This could be a string of JavaScript statements to be executed, a Java method, or a data structure containing network access information. The id is sent to the callback method for unique identification of the event. The last function gets the current value of the isActive eventOut. For every eventOut foo there is a get_foo which gets the current value of the eventOut.

B.2.3 Browser API

The VRML world has an externally accessible API which provides functionality in addition to the event access described above. This gives access to the scene, some browser functions and, most importantly, a way to get node pointers. The functions listed here are all methods on the browser object, which is the external language's interface to the VRML world. This may be an embedded frame in JavaScript, a class instance in Java, or a network accessible process containing a VRML world.

SFNode getNode(SFString name) Get a pointer to the node with the passed DEF name.
SFString getName() Get a string with the name of the VRML browser.
SFString getVersion() Get a string containing the version of the VRML browser.
SFFloat getCurrentSpeed() Get the floating point current rate at which the user is traveling in the scene.
SFFloat getCurrentFrameRate() Get the floating point current instantaneous frame rate of the scene rendering, in frames per second.
SFString getWorldURL() Get a string containing the URL of the currently loaded world.
void replaceWorld(MFNode nodes) Replace the current world with the passed list of nodes.
void createVRMLFromURL(MFString url, SFNode node, SFString event) Parse the data in url into a VRML scene. When complete send event to node. The event is a string with the name of an MFNode eventIn in the passed node. For instance, if node were a Transform, event would be "add_children". When the url is loaded and scene parsed, the resulting nodes would be added as children of the Transform.
MFNode createVRMLFromString(SFString str) Parse string into a VRML scene and return the list of root nodes for the resulting scene.
void addRoute(SFNode fromNode, SFString fromEventOut, SFNode toNode, SFString toEventIn) Add the route fromNode.fromEventOut TO toNode.toEventIn.
void deleteRoute(SFNode fromNode, SFString fromEventOut, SFNode toNode, SFString toEventIn) Remove the route fromNode.fromEventOut TO toNode.toEventIn, if one exists.

 Contact rikk@best.com, cmarrin@sgi.com, or gavin@acm.org with questions or comments.
This URL: http://vrml.sgi.com/moving-worlds/spec/part1/external_API.html.