4 Concepts
4.1 Introduction and table of Contents
4.1.1 Introduction
This clause describes key concepts in this part of ISO/IEC 14772. This
includes describing the various components of the browser and how the interactions
with the browser may be consummated. It does not define what the individual
interactions are. Those descriptions can be found in 6
Services reference.
4.1.2 Table of contents
See Table 4.1 for the table of contents for this
clause.
4.2 Overview
An application may interact with a VRML scene graph through use of the
interface defined in this part of ISO/IEC 14772. This interface is a protocol
for manipulating the VRML scene graph while not directly part of the scene
graph itself.
This specification is aimed at providing a language neutral representation
of all actions that can be performed by an external application across
this interface. Bindings
to specific languages are defined in the annexes. The EAI forms this interface by giving access to the top-level
named nodes in the system to the external environment. Top level named nodes are those nodes at the outermost layer of name
scope which have an associated DEF name. The interface mimics
the access of the Script node with a reference to the named node. To facilitate
the sending of events to the external environment, a new mechanism
is made available. To receive notification when an event is sent to an eventOut, the external environment registers interest in it. This mechanism
is similar in concept to the processEvents
functionality in ISO/IEC 14772-1, but differs due to the asynchronous
nature of the external environment.
Conceptually, the External Authoring Interface allows four types of
access into the VRML scene:
-
Accessing the functionality of the Browser Script Interface (see
ISO/IEC 14772-1 4.12.10 Browser
Script Interface).
-
Sending events to eventIns of nodes inside the scene.
-
Reading the last value sent from eventOuts of nodes inside the scene.
-
Getting notified when events change values of node fields inside the scene.
As with scripts within the VRML scene, the EAI allows access to the full
functionality of the Browser
Script Interface. Browser state can be queried, routes can be added
and deleted, and new nodes can be created. The EAI extends the basic browser
interface with a number of extra capabilities including retrieving node
references and registering interest in browser events.
4.3 Implementation dependencies
Implementation dependence is defined in terms of the language binding or
protocol encoding of the services defined in this specification. If a service
is defined to be implementation dependent, it is a requirement of each
binding and encoding to specify how that service is to be implemented,
if at all.
Bindings and encodings to these services may define their own implementation
dependent parts within that specification.
4.4 Interface components
4.4.1 Concepts
There are three main items in a VRML browser that can be accessed from
an external application: The browser, nodes within the scene graph, and
fields within nodes. The definition and specifications are framed in terms
of services. A VRML browser exposes a set of services which allow external
applications to interact with it.
4.4.2 Application
An application is the external process that is not implicitly part of the
VRML browser. This application makes some form of connection to the VRML
browser along which requests are made of the browser. The application does
not exist as part of the VRML browser as defined in ISO/IEC
14772-1 Figure 4.1 nor forms part of the ISO/IEC
14772-1 4.10.3 VRML execution model. An application may reside on another
machine from the VRML browser.
4.4.3 Session
A session defines the life of a single connection between the application
and the VRML browser. It is possible for a single browser to be servicing
multiple sessions simultaneously. It is also possible that a single application
may contain a number of separate sessions to multiple browsers. Multiple
simultaneous sessions between external applications and multiple VRML browsers
is permissible. However, individual implementations may place some restrictions
on such multiple simultaneous sessions.A session is not an implementable part of this specification. It is
purely a conceptual mechanism by which the services can make requests for
services. It may exist prior to any connection being established between
a browser and external application or is established simultaneously
with the request for a browser connection.
4.4.4 Browser
The browser is the basic encapsulation mechanism for an active VRML scene
graph (that is one where time is progressing - not as a file stored on
disk). As it contains the entire scene graph, it also provides a
core set of capabilities for dynamically manipulating that scene graph
at a coarse level. For
example, new content may be dynamically generated from a string of characters.
A user may have many VRML browsers running simultaneously on their machine.
Therefore, each browser shall be represented by a unique identifier within
that session. This identifier is required to be identical for multiple
requests of a single browser instance. This is to enable two applications
that have access to the one browser instance to share information in an unambiguous
way.
Any action that requires use of the browser functionality shall identify
the service request with a browser identifier.
4.4.5 Node
The smallest unit of interaction with the elements in the scene graph is
the node. A node is equivalent to the VRML nodes that are defined in ISO/IEC
14772-1. A node can be removed as a unit from the scene graph, stored and
then re-inserted at another position at some later time in the same session
without detrimental effect.
Each node is defined by a unique identifier. This identifier is unique
for that session. That is, it is possible that a single browser may be
servicing multiple applications simultaneously and therefore all node identifiers
are unique and invariant for the life of the session. This allows two external
applications to potentially share data between themselves unambiguously and still have either make service requests of the browser with that shared
data.
It is not possible to directly manipulate a node's properties as separate
entities to the node itself.
Most operations in the EAI begin by obtaining a reference to a node.
To reference a node it must be named using the DEF construct. Once a reference
is obtained, the eventIns and eventOuts of that node can be accessed. Since
an exposedField implicitly contains an eventIn and an eventOut, these are
accessible as well using the field name or with the set_ and _changed
modifiers.
Node identifiers may also be used to represent an empty node. An
empty SFNode or MFNode field value is represented by a NULL value. For empty
MFNode fields, the count of available nodes shall be zero when the field value
is NULL.
4.4.6 Field
Individual fields are within nodes. While it is not possible to directly
manipulate a node, a field is the method of direct manipulation of individual
properties.
The access granted to individual fields is defined by Part 1 of this
standard.
For example, it is not possible to change the value of a "field" field. "exposedField"s may have values written to them and values read from them.
A field is assigned a field identifier. This is non-unique and requires
a node identifier plus the field identifier to specify a particular field with which to interact.
Fields may be read or written at any time during the course of the session.
An application may register and unregister to receive notification of
when values of the field changes. During the registration process the application
can supply a token that will be returned along with the data value of the
event. This token can be used by the application to uniquely identify this
event in cases where events are not implicitly unique. The token is not
required to be passed along with the service request and may be kept as
part of the internals of the implementation on the application interface.
Any eventOut of a node to which the application has a reference can
be read. The value read is the last value sent to that eventOut or the
default value for that eventOut type if no event has ever been sent. The
data read is specific to the field type of that eventOut and is formatted
appropriate to the language or protocol used.
4.5 Events
4.5.1 Concepts
Any transient variant data is carried around the VRML scene graph through
the use of events. The application may register to receive events from
the VRML scene graph, and may initiate new events. Events are considered
transient and generated only at the time when the specific action occurs.
Events shall not be stored and have the delivery deferred to parties who
have not expressed interest in the event at the time it occurred. For example
an application that connects to a browser after the world has loaded shall
not be delivered an Initialize event.
4.5.2 Internal to browser
In many cases, fields and events are used interchangeably as terms to describe
the changing of the properties of a field. In this specification, there
is a difference.
An application may write a value to a field or read a value from a field.
This value does not become an event until that value is internally represented
within the VRML browser. The border of the browser to the application is
where an event stops. Events cannot exist externally from the VRML browser;
that is, the application cannot be inserted in the middle of an event cascade.
The application may be notified of events, initiate new events, but cannot
process and pass on events while holding up processing of the current timestamp
event cascades within the browser when it is notified of an event.
4.5.3 Browser to external application
4.5.3.1 Overview
The browser may directly communicate to external applications with its
own set of events. These events are used to indicate the status of the
browser or of some asynchronous problem. The number and type of events
available shall be implementation dependent. At a minimum, the following
events shall be provided in all implementations of this specification.
Event delivery from the browser to the external application shall be
guaranteed.
4.5.3.2 Initialize
The initialize event is used to indicate that the browser has had a world
loaded where it has run through the initialization process (where the browser
has loaded the world and just before it is about to issue its first time-related
event). At this point in time, node identifiers shall be available from
the getNode service of the browser (see 6.3.15,
getNode).
The initialize event shall be generated immediately at the browser and
delivered to the application. The event is considered to be asynchronous.
That is, the delivery of the event (and any implementation dependent acknowledgement
scheme) shall not delay the browser in starting the execution model evaluation.
4.5.3.3 Shutdown
The shutdown event is used to indicate that the browser is about to stop
running the world. This may occur under a number of different conditions:
The world is being replaced (See 6.3.14, replaceWorld
and 6.3.12, loadURL), the browser itself
is exiting, or the client application has disposed of its connection to
the browser (see 6.3.4, Dispose).
The shutdown event shall be generated immediately at the browser and
delivered to the application. The event is considered to be asynchronous.
That is, the delivery of the event (and any implementation dependent acknowledgement
scheme) shall not delay the browser in halting the execution model evaluation
and closing down of the browser resources except where needed to ensure
the delivery of the event to the application.
4.5.3.4 No URLs available
The no URL event is used to notify the application that the browser was
not able to load any of the URL/URNs in one of the asynchronous invocations
of the loadURL service (See 6.3.12,
loadURL) or the createVrmlFromString service (see 6.3.3,
createVrmlFromURL) indicating that no valid content was able to be
loaded from any of the URLs specified in these calls. Other calls that
may involve other asynchronous loads such as replaceWorld (see 6.3.14,
replaceWorld) and createVrmlFromString (see 6.3.2,
createVrmlFromString) may also use this event to indicate loading problems
for items such as Inlines and EXTERNPROTOs although it shall not be required
and shall be implementation dependent.
4.5.3.5 Connection lost
The connection lost error is used to notify the application that the underlying
implementation has lost the connection between the browser and the application
that would result in service requests not being able to be honoured. An
example would be a TCP network connection timing out or other similar problem.
An implementation may delay sending an event that the connection has
been lost if it implements some automatic reconnection attempt. It shall
only be sent at the point where it is deemed no longer possible to connect
to the browser. There shall be no requirement for the implementation to
attempt to re-establish the connection after this event has been generated
or to attempt any form of automatic reconnection capability.
4.6 Identifiers
What constitutes an identifier is implementation dependent. In some cases
it may be more efficient to represent a node identifier as the entire node
which includes all field information. Requests for field information are
then made on the local node. In other implementations an identifier may
be only a simple integer. The job of ensuring unique identifiers is the
sole responsibility of the browser such that applications may share data
within reasonable constraints of the environment. The constraints on that
environment may be specified as part of the individual implementation as
defined in the attached appendicies.
It is not considered reasonable that two applications using different
service implementations
be able to exchange data outside of the browser environment.
4.7 Relative URLs
ISO/IEC
14772-1 4.5.3 Relative URLs (RURL) defines the rules for dealing with
relative URLs within a browser environment. The declaring file shall be
defined as the base URL of the currently loaded world in the browser. The
currently loaded world can be obtained by a request of the getWorldURL
service(see 6.3.11, getWorldURL). In the
case where a browser does not yet have a VRML file loaded, the base document
directory shall be taken to be the current working directory of the browser.
Where the browser is part of a web page, the current working directory
shall be treated as the base URL of the page in which the web browser is
embedded.
When nested relative URLs are generated (such as an EXTERNPROTO containing
a reference to a script file) the top level RURL base is then resolved
in accordance with ISO/IEC 14772-1.
4.8 Execution model
4.8.1 Updating the scene graph
A characteristic of external applications is that they will make a lot
of changes in bursts to the VRML browser. It is also possible that a single
browser may have a number of applications connected to it, all making requests
of the browser.
Events can be batched to aid in performance of the application. The
mechanism provided by this is a simple gate mechanism to hold all requests
(beginUpdate) to update the currently loaded world until the gate
is released (endUpdate).
When beginUpdate is invoked, all requests to modify the contents
of the current world are buffered and not passed to the browser. This buffering
effects all requests to modify the current world including calls to loadURL
and replaceWorld. Once a call to beginUpdate has been made,
any further beginUpdate requests are ignored until the next call to endUpdate
at which time endUpdate releases all of the currently buffered updates
to the browser for processing.
If a modification service request is made on the scene after an endUpdate
and before a beginUpdate, it shall be passed to the scene immediately
with the timestamp at the discretion of the browser.
beginUpdate/endUpdate requests shall be limited to the
individual session. A request by one application to beginUpdate
shall only buffer the requests made by that application and not any others
that may be connected to that same browser instance.
When endUpdate is invoked, the following order of execution of
requests shall be applied
-
node setValues
-
event cascade evaluation as per ISO/IEC
14772-1 4.10.3 Execution Model
loadURL/replaceWorld service requests are not affected by the update control
process. As soon as the browser receives these requests their execution
is begun. The service definitions define the complete behaviour of these
requests.
Buffered requests from the application shall be processed before processing
any more requests either through another buffered queue or individual requests.
4.8.2 Synchronizing multiple applications
When multiple applications make requests of the browser, the requests shall
be serviced in order of arrival time at the browser. The browser shall
determine the arrival time. Buffered updates to the scene graph shall have
their arrival time determined to be at the time that endUpdate is
requested. The arrival time is not necessarily the same as the timestamp
at which the browser chooses to send events into the scene graph. The timestamp
that the events are sent to the scene graph shall be determined by the
browser but shall be no earlier than the time that endUpdate is
requested. The arrival time is used to sort out conflicting requests from
multiple applications to ensure consistent results in the application of
events in the correct order.
Should the browser determine that two requests arrive simultaneously
the result is implementation dependent. Note that it is permissible for
the external applications to send new values to a given eventIn simultaneously.
For such situations the browser shall obey ISO/IEC
14772-1 4.10.5 Fan-in and Fan-out.
Should the browser receive a request to loadURL or replaceWorld
while currently processing a similar request, the old request is immediately
terminated and the new one begun. See 6.3.14,
replaceWorld and 6.3.12, loadURL for more information.
4.8.3 Service guarantees
All requests for services shall be guaranteed to be honoured where the underlying
implementation supports that service. Once the application has made a service
request, that request shall be transmitted to the browser assuming that
a connection is still available. That is, all communications are assumed
to be reliable. Delivery is not guaranteed if the connection between the
browser and application has been broken (for example, a TCP connection
fails). Implementations shall define an error condition that notifies the
user that the connection has failed for each service request. Also, the
browser interface may include an event that provides asynchronous notification
to the user of the failure.