6.1 Introduction and table of contents

6.1.1 Introduction

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.

6.1.2 Table of contents

See Table 6.1 for the table of contents for this clause.

6.2 X3D field to ECMAScript variable conversion

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 are 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.

6.3 Data type definitions

6.3.1 SAIAction

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.

6.3.2 SAIBrowserApp

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.

6.3.3 SAIBrowserName

The data type is implemented as the String standard object type.

6.3.4 SAIBrowserRef

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.

6.3.5 SAIBrowserVersion

The data type is implemented as the String standard object type. The NULL value is defined as the ECMAScript null value type.

6.3.6 SAIComponentDeclaration

The component declaration is represented by the ComponentInfo host object. This object presents a read-only view of a component and its information.

6.3.7 SAIComponentID

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 is anything but a positive integer, the browser shall generate an error.

6.3.8 SAIExecutionContextID

The execution content is represented by an instance of the X3DExecutionContext host object type.

6.3.9 SAIFieldAccess

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.

6.3.10 SAIFieldDefinition

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 .

6.3.11 SAIFieldID

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.

6.3.12 SAIFieldName

The name of the field is implemented as a String standard object type.

6.3.13 SAIFieldType

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.

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.

6.3.14 SAIFieldValue

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.

6.3.15 SAIFrameRate

The data type is implemented as the numeric standard object type. A null value is defined as the value 0.0f.

6.3.16 SAILoadState

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.

6.3.17 SAINavSpeed

The data type is implemented as the numeric standard object type. A null value is defined as the value 0.0f.

6.3.18 SAINodeID

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 = someNewAppearanceNode;

6.3.19 SAINodeType

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

6.3.20 SAIParameterList

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.

6.3.21 SAIProfileDeclaration

The profile declaration is represented by the ProfileInfo host object type. See 7.8.1 ProfileInfo for a detailed definition of this object.

6.3.22 SAIPropertyList

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"

6.3.23 SAIProtoDeclaration

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.

6.3.24 SAIRequesterID

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.

6.3.25 SAIRoute

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.

6.3.26 SAIScene

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.

6.3.27 SAIScript

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.

6.3.28 SAIScriptImplementation

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

6.3.29 SAIStream

TO DO

6.3.30 SAIString

The string is implemented as a String standard object type.

6.3.31 SAIUnitDeclaration

The SAIUnitDeclaration is represented as three separate primitive values. The category is defined using an ECMAScript String, the name of the new default base unit is defined using an ECMAScript String, and the conversion factor from the new default base unit to the initial default base unit is represented using the numeric primitive type.

6.3.32 SAIURL

The URL is implemented as the String standard object type.

6.4 Error data types

6.4.1 SAIError

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.

6.4.2 SAI_BROWSER_UNAVAILABLE

The error type is implemented as the object NoSuchBrowserException.

6.4.3 SAI_CONNECTION_ERROR

The error type is implemented as the object ConnectionException.

6.4.4 SAI_DISPOSED

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.

6.4.5 SAI_IMPORTED_NODE

The error type is implemented as the object InvalidImportedNodeException.

6.4.6 SAI_INSUFFICIENT_CAPABILITY

The error type is implemented as the object InvalidInsufficientCapabilityException.

6.4.7 SAI_INVALID_ACCESS_TYPE

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.

6.4.8 SAI_INVALID_BROWSER

The error type is implemented as the object InvalidBrowserException.

6.4.9 SAI_INVALID_DOCUMENT

The error type is implemented as the object InvalidDocumentException.

6.4.10 SAI_INVALID_EXECUTION_CONTEXT

The error type is implemented as the object InvalidExecutionContextException.

6.4.11 SAI_INVALID_NAME

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.

6.4.12 SAI_INVALID_NODE

The error type is implemented as the object InvalidNodeException.

6.4.13 SAI_INVALID_FIELD

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.

6.4.14 SAI_INVALID_OPERATION_TIMING

The error type is implemented as the object InvalidOperationTimingException.

6.4.15 SAI_INVALID_URL

The error type is implemented as the object InvalidURLException.

6.4.16 SAI_INVALID_X3D

The error type is implemented as the object InvalidX3DException.

6.4.17 SAI_NODE_NOT_AVAILABLE

The error type is implemented as the object NodeUnavailableException.

6.4.18 SAI_NODE_IN_USE

The error type is implemented as the object NodeInUseException.

6.4.19 SAI_NOT_SHARED

The error type is implemented as the object BrowserNotSharedException.

6.4.20 SAI_URL_UNAVAILABLE

The error type is implemented as the object URLUnavailableException.

6.5 Event types

6.5.1 General concepts

The ECMAScript design philosophy does not always 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.

6.5.2 SAIBrowserEvent

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

6.5.3 SAIFieldEvent

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.