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
Interaction with a VRML scene graph may occur either from Script nodes
within the scene graph (internal access) or from an external application
(external access). Both Script nodes and external applications are considered
examples of an authoring environment. Access from an authoring
environment to the VRML scene graph occurs through use of the
interface defined in this part of ISO/IEC 14772. This interface consists of a
set of services for manipulating the VRML scene graph.
This specification is aimed at providing a language neutral representation
of all actions that can be performed by an authoring environment across
this interface. The SAI forms this interface by giving access to the top-level
named nodes in the system to the authoring environment. The interface mimics
the access of the Script node with a reference to the named node. To facilitate
the sending of events to the authoring environment, a new mechanism
is made available. To receive notification when an event is sent to an
eventOut, the authoring environment registers interest in it.
Conceptually, the Scene Authoring Interface allows four types of
access into the VRML scene:
-
Accessing the functionality of the Browser 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 SAI allows access to the full
functionality of the Browser Interface. Browser state can be queried, routes can be added
and deleted, and new nodes can be created. The basic browser
interface provides additional 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 authoring interface:
- the browser state
- nodes within the scene graph
- fields within nodes
The definition and specifications are framed in terms
of services. A VRML browser exposes a set of services which allow authoring
environments to interact with it.
4.4.2 Application
An authoring environment is an application that is not implictly 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 authoring interface does
not exist as part of the VRML browser as defined in ISO/IEC
14772-1 Figure 4.1. While internal authoring environments form the Script
node part of the ISO/IEC
14772-1 4.10.3 VRML execution model, external authoring environments are
outside the VMRL execution model. An external authoring interface may reside on another
machine from the VRML browser.
4.4.3 Session
A session defines the life of a single connection between the authoring
environment and the VRML browser. It is possible for a single browser to be servicing
multiple sessions simultaneously. It is also possible that a single authoring
environment may contain a number of separate sessions to multiple browsers. Multiple
simultaneous sessions between external authoring environments and multiple VRML browsers
is permissable. 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 authoring environment (e.g., a CORBA ORB) or may be established simulatenously
with the request for a browser connection (e.g., instantiating a Java Browser
object instance). The session for an internal authoring environment is
established when the Script node which contains the authoring environment
is created. The session is terminated when the Script node is deleted
from the scene graph.
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, it allows the dynamic generation of new
content 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
unambigous 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 unambigously
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 SAI 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. Fields
representing nodes (SFNode and MFNode) require the ability to clear the
field setting it to NULL. Representing an empty SFNode field value is with
a NULL value. Representing an empty MFNode field is implementation dependent.
4.4.6 Fields
Within nodes are individual fields. 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 the VRML specification.
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 ID plus field ID 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 authoring environment cannot be inserted in the middle of an event cascade.
The authoring environment 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 authoring environment
4.5.3.1 Introduction
The browser may directly communicate with authoring environments 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
events described in this subclause shall be provided in all implementations of this specification.
Event delivery from the browser to the authoring environment 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 acknowlegement
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.7, replaceWorld
and 6.3.8, loadURL), the browser itself
is exiting, or the client authoring interface has disposed of its connection to
the browser (see 6.3.16, Dispose).
The shutdown event shall be generated immediately at the browser and
delivered to the authoring environment. The event is considered to be asynchronous.
That is, the delivery of the event (and any implementation dependent acknowlegement
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.8,
loadURL) or the createVrmlFromString service (see 6.3.11,
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.7,
replaceWorld) and createVrmlFromString (see 6.3.10,
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 authoring interface that the underlying
implementation has lost the connection between the browser and the authoring
interface 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 authoring environments 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 annexes.
It is not considered reasonable that two authoring environments using different
service implementations (such as a Java applet and a C++ CORBA object)
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.6, 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 authoring environments 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 authoring environments 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 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 authoring environment shall be processed before processing
any more requests either through another buffered queue or individual requests.
4.8.2 Synchronizing multiple applications
When multiple authoring environments 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 permissable for multiple
external authoring environments 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 ISO/IEC 14772-1
6.3.6 replaceWorld and ISO/IEC 14772-1 6.3.7 loadURL
for more information.
4.8.3 Service guarantees
All requests for services shall be guaranteed to be honored 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.