Extensible 3D (X3D) language bindings
Part 1: ECMAScript
6 Type definitions
The X3D Scene Authoring Interface defines a set of fundamental abstract data types. This clause gives the mapping from those data types to the data types defined in this binding. All implementation-dependent data types are defined after all implementation independent data types in each category.
See Table 6.1 for the table of contents for this clause.
Table 6.1 — Topics in this clause
ECMAScript native datatypes consist of boolean, numeric and string. The language is not typed, so datatypes are implicit upon assignment. The VRML SFBool is mapped to the ECMAScript boolean. In addition to the ECMAScript true and false constants, the X3D TRUE and FALSE values may be used. The X3D SFInt32, SFFloat and SFTime fields are mapped to the numeric datatype and will be maintained in double precision accuracy. These types are passed by value in function calls. All other X3D fields are mapped to ECMAScript objects. ECMAScript objects are passed by reference.
The ECMAScript boolean, numeric and string are automatically converted to other datatypes when needed. See ISO/IEC 16262 for more details.
In ECMAScript, assigning a new value to a variable gives the variable the datatype of the new value, in addition to the value. Scalar values (boolean and numeric) are assigned by copying the value. Other objects are assigned by reference.
When assignments are made to writable fields, the values are converted to the X3D field type. Values assigned are always copied. This contrasts with normal assignment in ECMAScript where all assignments except for scalar are performed by reference.
For write-only objects within an internal interaction, assignment copies the value to the field, which will be sent upon completion of the current function in accordance with 4.8.3.3 Responding to events of part 2 of ISO/IEC 19775. Assigning a write-only field object to an internal variable copies by reference. Subsequent assignments to that internal variable will behave like assignments to the write-only field (i.e., an event will be sent at the end of the function). InitializeOnly field objects behave identically to write-only objects, except that no event is sent upon completion of the function.
Assigning an element of a multi-valued field object to an internal variable creates a reference to that element. The type shall be the corresponding single valued object type. If the multi-valued object is an write-only field and an assignment is made to the internal variable, an event will be sent at the end of the function. Assigning a single valued field object to an element of a multi-valued field object object which is an initialize-only field or write-only field (which shall be of the corresponding type) copies the value of the single-valued field object into the multi-valued field object element. If the multi-valued field object is a write-only field an event will be sent at the end of the function.
The action type is dependent on the method used. Table 6.2 defines the mapping between each service, the valid action types for that service and the Java implementation of that action. Actions are mapped as method names describing the action rather than strict primitive types.
Table 6.2 — SAIAction to ECMAScript implementation mapping
Service | Action Type | ECMASCript Implementation |
---|---|---|
Dynamic Route Handling | Add Route | X3DExecutionContext function addRoute() |
Delete Route | X3DExecutionContext function deleteRoute() |
|
Update Control | Begin Update | ExternalBrowser function beginUpdate() |
End Update | ExternalBrowser function endUpdate() |
|
Register Browser Interest | Add | Browser function addBrowserCallback() |
Remove | Browser function removeBrowserCallback() |
|
Register Event Interest | Add | FieldObject function addFieldCallback() |
Remove | FieldObject function removeFieldCallback() |
|
Share World | share | ExternalBrowser function shareBrowser()
|
unshare | ExternalBrowser function unshareBrowser() |
|
getNode | DEF node | X3DExecutionContext function getNamedNode() |
IMPORT node | X3DExecutionContext function getImportedNode() |
|
EXPORT node | X3DScene function getExportedNode() |
|
Named Node Handling | add/update DEF node | X3DExecutionContext function updateNamedNode() |
remove DEF node | X3DExecutionContext function removedNamedNode() |
|
add/update IMPORT node | X3DExecutionContext function updateImportedNode() |
|
remove IMPORT node | X3DExecutionContext function removeImportedNode() |
|
add/update EXPORT node | X3DScene function updateRemovedNode() |
|
remove EXPORT node | X3DScene function removeImportedNode() |
|
PROTO Declaration Handling | add/update Proto | X3DExecutionContext function updateProtoDeclaration() |
remove Proto | X3DExecutionContext function removeProtoDeclaration() |
|
EXTERNPROTO Declaration Handling | add/update ExternProto | X3DExecutionContext function updateExternProtoDeclaration() |
remove ExternProto | X3DExecutionContext function removeExternProtoDeclaration() |
|
Root Node Handling | add root node | X3DScene property rootNodes
(MFNode object type) |
remove root node | X3DScene property rootNodes
(MFNode object type) |
The data type is not provided by this specification as it is assumed
the surrounding scripting context will make this information available in
its own fashion. The capability to obtain an SAIBrowserRef is implemented
in the getBrowser()
function of that environment-specific
object which returns an instance of the ExternalBrowser
object.
The data type is implemented as the String standard object type.
The browser reference type is defined to be an instance of the Browser
host object. This is the base representation used for both internal and external
interaction. For external-only interactions, extra functions are available through the ExternalBrowser
host object that corresponds
with capabilities in addition to those of the basic Browser
object. For
external interactions, the Browser
object shall not be defined.
The data type is implemented as the String standard object type.
The NULL value is defined as the ECMAScript null
primitive type.
The component declaration is represented by the ComponentInfo
host object. This object presents a read-only view of a component and it is
information.
The component ID is represented as two separate primitive values. The name of the component is defined using an ECMAScript String and the level is represented using the numeric primitive type. If the user provides a level value that has a fractional component, the browser shall generate an error.
The execution content is represented by an instance of the X3DExecutionContext host object type.
Field access is driven by the state of the field object. It shall have two
read-only Boolean properties to determine if it is readable
(readable
) and writeable (writable
)
These properties shall be true
if the field is readable or writable
respectively at the current point in time. Note that for a given field the
value of the properties for a particular SAIFieldID may change over time
dependent on the node's current state in the life cycle as specified in 4.4.3.5
Object life cycle of part 1 of ISO/IEC
19775.
The field declaration is represented by the X3DFieldDefinition
host object. This object has a number of read-only properties defined. The
definition of the properties available are described in
7.6.2 Field services and objects
.
The field identifier is represented as an instance of the object that
is appropriate to the field type. For each specific X3D field type, there
shall be a derived object that represents the field type, and includes strong
type checking for the values. An implementation is not required to return
the same object instance for every query, but shall ensure that equivalence
checking is correct through the implementation of
the equals()
function.
The name of the field is implemented as a String standard object type.
The field type may be represented in two alternative fashions.
The first alternative is provided through getType()
function
provided in the field object. This returns a numeric value which
has one of the values defined by the defined in
Table 6.3.
Table 6.3 — Mapping of X3D Field type to ECMAScript representation
X3D Field type | Value |
---|---|
SFBool | X3DConstants.SFBool |
MFBool | X3DConstants.MFBool |
SFColor | X3DConstants.SFColor |
MFColor | X3DConstants.MFColor |
SFColorRGBA | X3DConstants.SFColorRGBA |
MFColorRGBA | X3DConstants.MFColorRGBA |
SFDouble | X3DConstants.SFDouble |
MFDouble | X3DConstants.MFDouble |
SFFloat | X3DConstants.SFFloat |
MFFloat | X3DConstants.MFFloat |
SFImage | X3DConstants.SFImage |
MFImage | X3DConstants.MFImage |
SFInt32 | X3DConstants.SFInt32 |
MFInt32 | X3DConstants.MFInt32 |
SFNode | X3DConstants.SFNode |
MFNode | X3DConstants.MFNode |
SFRotation | X3DConstants.SFRotation |
MFRotation | X3DConstants.MFRotation |
SFString | X3DConstants.SFString |
MFString | X3DConstants.MFString |
SFTime | X3DConstants.SFTime |
MFTime | X3DConstants.MFTime |
SFVec2d | X3DConstants.SFVec2d |
MFVec2d | X3DConstants.MFVec2d |
SFVec2f | X3DConstants.SFVec2f |
MFVec2f | X3DConstants.MFVec2f |
SFVec3d | X3DConstants.SFVec3d |
MFVec3d | X3DConstants.MFVec3d |
SFVec3f | X3DConstants.SFVec3f |
MFVec3f | X3DConstants.MFVec3f |
The second alternative is provided by the objects themselves. Field objects are derived to provide implementations of the exact field type. A list of all the objects for each field type and access type is provided in 7.5.4 Field Services.
The field value is defined on a per object and per field type instance. See the definitions of the individual field type objects for the exact definition of each type. As a general rule, the X3D data type maps the the equivalent ECMAScript primitive type using the mapping in Table 6.4.
Table 6.4 — Mapping of X3D data types to ECMAScript data types
X3D Field Type | ECMAScript Type |
---|---|
SFBool | Boolean |
SFColor, SFColorRGBA | Object |
SFFloat, SFDouble | Numeric |
SFImage | Object |
SFInt32 | Numeric |
SFRotation | Object |
SFString | String |
SFTime | Numeric |
SFVec2f, SFVec3f, SFVec2d, SFVec3d | Object |
All MF fields | Object |
The data type is implemented as the numeric standard object type. A
null value is defined as the value 0.0f
.
The load state is implemented as a numeric primitive type. The values for each state are defined in Table 6.5. If a component defines new field types, the numerical values assigned shall not override the values already defined.
Table 6.5 — Load state type value defintions
State | Value |
---|---|
NOT_STARTED | X3DConstants.NOT_STARTED_STATE |
IN_PROGRESS | X3DConstants.IN_PROGRESS_STATE |
COMPLETE | X3DConstants.COMPLETE_STATE |
FAILED | X3DConstants.FAILED_STATE |
The data type is implemented as the numeric standard object type.
A null value is defined as the value 0.0f
.
The node identifier is represented as an instance of the SFNode
object. This object is used for the dual purpose of representing an individual
node as well as the single value node field type. The identifier of a node field
may be accessed directly as a property of the parent node. In the following
example, the value of the appearance field of the Shape node is assigned a new
value.
myShape.appearance = someNewValue;
The node type is represented as a numeric constant value in the host object
X3DConstants
. The host object contains a collection of read-only
numeric propeties named for each abstract node type defined in
part 1 of ISO/IEC 19775. The naming convention
shall be to use the exact naming specified in part 1 of ISO/IEC 19775, maintaining
case.
EXAMPLE The following two constants define the X3DGroupingNode and X3DUrlObject abstract node types:
X3DConstants.X3DGroupingNode X3DConstants.X3DUrlObject
The createBrowser and getBrowser services are not implemented by this language binding. Therefore, there is no requirement to define valid values for this abstract type.
The profile declaration is represented by the ProfileInfo
host
object type. See 7.8.1 ProfileInfo for
a detailed definition of this object.
The data type is implemented as an array of String
standard
object types. Key/Value pairs are declared in a single string in the
following format with the '=' character as the separator. Whitespace
surrounding the key and value are ignored although whitespace inside the
key and value are legal.
The following are considered valid values (as well as permutations of the given examples):
"key=value" "key = value" "key= value" "a key = some value" "a key =some value"
The component declaration is represented by two separate object types: PROTO and
EXTERNPROTO. For PROTO, the object is
X3DProtoDeclaration
. For EXTERNPROTO, the object is
X3DExternProtoDeclaration
.
The requestor ID is represented as the ECMAScript execution context of the code that is being evaluated. In addition, the calls shall pass in a String object instance that represents the name of the function to be called in the same execution context when the desired callback needs to be made. If the user does not provide the string, or the name is not valid in the context, the browser may ignore the request.
Routes are represented by the immutable object X3DRoute
.
This allows fetching of all the route information, but it may not be changed.
Browsers shall not expose to the end user extended versions of this object
that allow direct modification of the route.
The string is implemented as a String standard object type.
This is the external, containing node representation of the script that is
passed to the script implementation object during the initialisation phase.
It shall be represented by an SFNode host object (see
7.5.4 SFNode) with the node type of
X3DConstants.X3DScriptNode
. This represents the abstract node type
as there may be more than one script node type.
The SAIScriptImplementation abstract type corresponds to the ECMAScript concept of the Execution Context (not to be confused with the X3D definition). The ECMAScript Execution Context is a construct created by the browser implementation that wraps the user-provided code in the Script node's url field.
Standard functions are defined for scripts in order to receive important information during its lifecylce. These standard functions are described in 4.3.5 Internal Interactions and 7.9 Script Implementation Details
The scene is represented by the object X3DScene. The scene interface holds all the functions that represent the Scene Services. A full definition of the interface and all its functions is in 7.3 Scene Services.
The URL is implemented as the String standard object type.
ECMAscript implementations of the errors rely on a derived object based on
the SAIError type.
The error types are implemented using the host object X3DException. All
exceptions(errors) defined in this specification shall be implemented as integer
constant properties of the X3DException object. A user may catch exceptions
using the try/catch keywords.
The error type is implemented as the object
NoSuchBrowserException
.
The error type is implemented as the
object ConnectionException
.
The error type is implemented as two separate dual purpose exception objects depending on their scope.
InvalidBrowserException
is used to indicate the disposal of an SAIBrowserRef.
InvalidNodeException
is used to indicate the disposal of an SAINodeID.
The error type is implemented as two separate exceptions based on the implementation
of SAINodeID and the rules defined in
Table 6.3.
These objects also derive from InvalidFieldException
.
InvalidEventInException
is used to indicate the named field is not accessible as a writable field when
attempting to create a route with the X3DExecutionContext.addRoute()
function.
InvalidEventOutException
is used to indicate the named field is not accessible as a readable field when
attempting to create a route with the X3DExecutionContext.addRoute()
function.
The error type is implemented as the
object InvalidBrowserException
.
The error type is expressed as different exceptions dependent on the situation.
The X3DExecutionContext.getNamedNode()
,
X3DScene.getExportedNode()
and
X3DExecutionContext.getImportedNode()
functions use the
InvalidNodeException
. When accessing fields of a node, the error
is expressed as an InvalidFieldException
.
The error type is implemented as the
object InvalidNodeException.
.
The error type is implemented as the object InvalidFieldException
.
Note that there are two derived objects from this object (InvalidEventInException
and InvalidEventOutException)
that may be used at times where
this error may be generated.
The error type is implemented as the
object InvalidURLException
.
The error type is implemented as the
object InvalidX3DException
.
The error type is implemented as the
object NodeUnavailableException
.
The error type is implemented as the
object NodeInUseException
.
The error type is implemented as the
object BrowserNotSharedException
.
The error type is implemented as the
object URLUnavailableException
.
The ECMAScript philosophy does not mesh well with the idea of event object
representations. As a consequence, this annex does not define event type
objects for the SAIBrowserEvent
and SAIFieldEvent
object types. Instead a series of constants are defined and standard function
calls are used.
A function that is to act as a callback for browser events shall consist of two optional parameters. A reference to the browser object will be the first parameter and a numeric primitive value that represents the event type. will be the second parameter The mapping of the numeric value to the error types defined by the abstract specification is defined in Table 6.6
Table 6.6 — Mapping of SAI event types to ECMAScript constants
Type | value |
---|---|
SAI_BROWSER_Initialized |
X3DConstants.INITIALIZED_EVENT |
SAI_BROWSER_Shutdown |
X3DConstants.SHUTDOWN_EVENT |
SAI_BROWSER_ConnectionError |
X3DConstants.CONNECTION_ERROR |
SAI_BROWSER_URLError |
X3DConstants.INITIALIZED_ERROR |
The event type is implemented as a set of parameters passed to the user defined callback function. The user function shall have parameters that are the pointer to the field, the timestamp of when the event happened and the user data that may have been registered with the field.