Extensible 3D (X3D)
Part 2: Scene access interface (SAI)

5 Data type reference

--- X3D separator bar ---

5.1 Introduction and topics

5.1.1 Introduction

This clause describes the language independent data types used in the definition of 6 Services reference.

5.1.2 Topics

Table 5.1 specifies the topics for this clause.

Table 5.1 — Topics

5.1.3 Concepts

All data types in this clause are language binding independent. They represent single value information that is passed as parameters, return values or error conditions that can be generated through the external authoring interface. Each language binding shall define implementations of each of these data types.

These data types represent the specific implementation of each type; that is, how the X3D browser would represent them internally.

--- X3D separator bar ---

5.2 Data type definitions

5.2.1 SAIAction

SAIAction is a single value representing a qualifier for a more general service type. Each use of the SAIAction type shall define the range of acceptable values.

5.2.2 SAIBoolean

SAIBoolean represents a TRUE or FALSE value.

5.2.3 SAIBrowserApp

SAIBrowserApp is a data type that represents the complete browser application. This is different from 5.2.5 SAIBrowserRef because SAIBrowserApp defines the browser application itself whereas the SAIBrowserRef defines a reference to the standardized interface to the browser's functionality. The data type shall contain some method for obtaining an SAIBrowserRef.

5.2.4 SAIBrowserName

SAIBrowserName defines a representation of the name of the browser. If the browser implementation does not support this information, a NULL value is considered a legal representation of this data type.

5.2.5 SAIBrowserRef

SAIBrowserRef represents a browser reference. This is a unique identifier per browser instance. Individual language bindings may place conditions on uniqueness allowing other methods for checking equivalent references to the same browser.

The browser concept is further defined in 4.4.6 Browser.

5.2.6 SAIBrowserVersion

SAIBrowserVersion defines a representation of the version of the browser. If the browser implementation does not support this information, a NULL value is considered a legal representation of this data type.

5.2.7 SAIComponentDeclaration

SAIComponentDeclaration defines all the information about a component and its declaration. It may be used to represent both the component information declared in a file, and the available components from the browser.

5.2.8 SAIComponent

SAIComponent specifies an identifier of a component when used in a request. Components consist of a name and a level and both are encapsulated in this identifier.

5.2.9 SAIEncoding

SAIEncoding specifies an identifier for an encoding type.

5.2.10 SAIExecutionContext

SAIExecutionContext is a data type for a representation of a subscene piece of information relating to the current name space as a run-time entity.

5.2.11 SAIFieldAccess

This data type defines the type of access that is permitted to a field. The valid values are initializeOnly, inputOnly, outputOnly, and inputOutput.

5.2.12 SAIFieldDeclaration

SAIFieldDeclaration represents the abstract declaration of a field for a node. The declaration is constant for all instances of that node and does not include the field value. It can be considered a wrapper data type that includes SAIFieldAccess, SAIFieldName and SAIFieldType data types.

5.2.13 SAIField

SAIField represents an identifier for a particular field of a node. It is guaranteed to be unique within the scope of an individual node reference. It is not guaranteed to be unique in terms of all field references generated. To uniquely define a field within the scene graph, a combination of node and field identifiers is needed.

The field concept is further defined in 4.4.9 Field.

5.2.14 SAIFieldName

SAIFieldName represents a name for a field.

5.2.15 SAIFieldType

SAIFieldType specifies the type of data a field represents. In some cases (where the field type represents an MFNode or SFNode), this field type may correspond to an SAINode. Valid types of the field are defined in 5 Field type reference in ISO/IEC 19775-1.

5.2.16 SAIFieldValue

SAIFieldValue represents the value to be set or to be returned of an SAIFieldType in language specific terms. A table may be constructed mapping each SAIFieldType represented to at least one language specific entry. This data type contains an item of class SAIFieldType and an item of the field type specified by the value of the first item. All field types defined in 5 Field type reference in ISO/IEC 19775-1 shall be supported.

5.2.17 SAIFrameRate

SAIFrameRate represents the rendering rate in frames per second that is currently being achieved by the browser.

5.2.18 SAILayerID

SAILayerID is an identifier of the target layer for an operation. The ordering of the layers is the ordinal position of the layer in the layers field of the LayerSet node defined in 35.4.2 LayerSet in ISO/IEC 19775-1.

5.2.19 SAILoadState

SAILoadState represents the load state of a node or EXTERNPROTO instance. The state shall be one of NOT_STARTED, IN_PROGRESS, COMPLETE or FAILED.

5.2.20 SAIMatrix

SAIMatrix specifies an identifier for a 3×3 or 4×4 matrix.

5.2.21 SAINavSpeed

SAINavSpeed represents the navigation speed of the user in base speed units.

5.2.22 SAINode

SAINode specifies an identifier for a node. Individual language bindings may place conditions on uniqueness allowing other methods for checking equivalent references to the same node. The node reference is not required to be part of the active scene graph.

A NULL value is a legal value for this data type. It is used to indicate that no node identifier is to be used. For example, for the field service setValue (see 6.7.6 setValue), a value of NULL on an SFNode field type is used to clear the node that may have previously been set as the value.

The node concept is further defined in 4.4.8 Node.

5.2.23 SAINodeType

SAINodeType represents the type of a node.

5.2.24 SAIParameterList

SAIParameterList is the abstract data type used to represent a list of parameters that may be passed to a service request. Each language binding shall be required to define the exact listing of parameters and their mapping to language-specific types. This may be used to represent more than one list of parameters where a binding provides multiple overloaded implementations of a single service.

5.2.25 SAIProfileDeclaration

SAIProfileDeclaration specifies all the information about a profile and its declaration. It may be used to represent both the profile information declared in a file, and the available profiles from the browser.

5.2.26 SAIPropertyList

SAIPropertyList is an abstract data type defining a set of key/value pairs for the provision of properties.

5.2.27 SAIProtoDeclaration

SAIProtoDeclaration represents the declaration of a PROTO or EXTERNPROTO. It does not represent an instance created from the declaration. The declaration cannot be changed at runtime and is only constructed from a file, stream or string. This allows a browser to build optimized internal storage mechanisms that may not be traversable using normal scene graph traversal mechanisms. Each language binding shall define its own representation and methods for creating instances of the PROTO declaration.

5.2.28 SAIRequester

SAIRequester represents the identifier of a client application or part thereof that is requesting a service to be performed. Variables of this data type are usually used to identify a particular client piece of code that is interested in listening for changes in some information in either the scene graph or browser state that functions as a callback device.

5.2.29 SAIRoute

SAIRoute represents a ROUTE construct. A ROUTE is not a node in the scene graph and does not represent a concrete structure (see 4.4.8.2 Routes in ISO/IEC 19775-1).

5.2.30 SAIScene

SAIScene represents a complete world and all the information that defines it including nodes, routes, protos and exports. A scene may come from parsing of a file, stream or string, or be programmatically constructed through this API.

5.2.31 SAIScript

SAIScript represents the containing node for user code that performs internal interactions. It is an X3DNode object that exists as part of the X3D scene graph.

5.2.32 SAIScriptImplementation

SAIScriptImplementation is a marker data type used by user code to mark the entrance point for the user code execution. It shall provide the lifecycle methods that the browser calls during user code execution such as initialize() and shutdown(). It shall not be used as a parameter to, or return type of, any service definition.

5.2.33 SAIStream

SAIStream represents X3D content arriving continuously.

5.2.34 SAIString

SAIString represents a string formatted with the UTF-8 universal character set. (see ISO/IEC 10646).

5.2.35 SAIUnitDeclaration

SAIUnitDeclaration defines all the information about units and its declaration. It is used to represent the unit information declared for a file, either explicitly or by default.

5.2.36 SAIURL

SAIURL is a data type which references a single URL. The URL may be any valid URL representation but is usually defined as a human-readable string that conforms to 2.[RFC4248].

5.2.37 NULL

NULL represents the empty value. It contains no data or reference to any data type but serves as a valid value to return from a service when nothing can be returned and yet no error is generated.

--- X3D separator bar ---

5.3 Error types

5.3.1 SAIError

This section defines the error types that may be generated in response to service requests. Errors are generated as synchronous values from a service request and returned as variables of type SAIError. These error types appear in the errors definition of a service request (see 6.1.3 Conventions used). A language binding shall define the representation for the SAIError data type and assign values for each of the errors defined below but may also define additional error data types to these.

5.3.2 SAI_BROWSER_UNAVAILABLE

This error indicates that the request to gain a reference to a SAIBrowserApp has failed. Examples may be that a network connection is down or that the type of reference required is not supported by the vendor-specific implementation of a language binding.

5.3.3 SAI_CONNECTION_ERROR

An error has occurred that resulted in the connection between the browser and external application becoming non-functional. Therefore, the service request could not be executed. This is a different error condition from SAI_BROWSER_UNAVAILABLE as it assumes that a valid reference has already been obtained and the error occurred at a later time.

5.3.4 SAI_DISPOSED

The request made of the current SAINode, SAIField or SAIBrowserRef reference is being made to an object that has already been disposed prior to this service request.

5.3.5 SAI_IMPORTED_NODE

An operation was attempted that used an imported node when it is not permitted as defined in 4.4.6 Import/Export semantics in ISO/IEC 19775-1. For example, adding the imported node as a child to another node in the current scene.

5.3.6 SAI_INSUFFICIENT_CAPABILITIES

The user is attempting to add a node to an execution context that is greater than the capabilities defined by the profile and components definition for that scene.

5.3.7 SAI_INVALID_ACCESS_TYPE

The attempt to perform an operation of a field failed because it is an invalid action for that field type. For example, an attempt made to read the value of an inputOnly field would generate this error.

5.3.8 SAI_INVALID_BROWSER

The instance of SAIBrowserRef data type provided as part of the parameters to the service request has been disposed of prior to this request.

5.3.9 SAI_INVALID_DOCUMENT

When the user has attempted to import a World Wide Web Consortium Document Object Model (DOM) document into an X3D scene and the document cannot be completely resolved to an X3D scene graph. There are many cases where this error might be generated, including the following:

Example 1  an invalid document structure

Example 2  not having the correct root element

5.3.10 SAI_INVALID_EXECUTION_CONTEXT

The instance of SAIExecutionContext data type provided as part of the parameters to this service request has been disposed of prior to this request.

5.3.11 SAI_INVALID_FIELD

The instance of SAIField data type provided as part of the parameters to this service request has been disposed of prior to this request.

5.3.12 SAI_INVALID_NAME

The name provided to a service request is invalid or cannot be found in the context of that object.

5.3.13 SAI_INVALID_NODE

The instance of SAINodeID data type provided as part of the parameters to this service request has been disposed of prior to this request.

5.3.14 SAI_INVALID_OPERATION_TIMING

The user is attempting to make a service request that is performed outside of the context within which such operations are permitted (see 4.8.3.7 User code lifecycle). Where a service defines this as being a possible error type, this shall only be thrown by internal interactions. External interactions shall never generate this error.

5.3.15 SAI_INVALID_URL

An instance of SAIURL data type provided in one or more of the parameters to this service request are invalid due to a syntax error. Errors due to the requested URL not being available shall generate either an SAI_URL_UNAVAILABLE error or an asynchronous event notifying of such a problem.

5.3.16 SAI_INVALID_X3D

The SAIStream, SAIString or X3D file (for example, as a result of the fetching of a URL reference) passed to this service request contains invalid syntax and cannot be parsed to produce legal data types for use in other service requests.

5.3.17 SAI_NODE_IN_USE

Indication that a named node handling action has attempted to re-use a name that is already defined elsewhere in this current scene.

EXAMPLE  A user is attempting to import a node as a name that is already described by a DEF.

An alternative use of this error shall be to indicate that the node, or one of its children, is currently in use in another scene. It is an error to share a single node instance across multiple scenes simultaneously.

5.3.18 SAI_NODE_NOT_AVAILABLE

An error condition used for IMPORTed nodes. The user has described a node that the IMPORT statement has said is valid, but the underlying Inline has not yet been loaded to verify that it is a correctly EXPORTed node.

5.3.19 SAI_NOT_SHARED

A service request was made that assumed the browser was currently participating in a shared scene graph when it was not.

5.3.20 SAI_NOT_SUPPORTED

Generalised error for when a service request is made for a capability that is not available in this browser implementation. For example, if the user requests a profile declaration for a profile that is not supported by the browser, this error may be generated.

5.3.21 SAI_URL_UNAVAILABLE

The service request requiring the browser to have a world URL set cannot be completed because no URL has been set. This error is typically generated from a getWorldURL (6.4.6 getWorldURL) or getNode (6.4.7 getNode) service request.

--- X3D separator bar ---

5.4 Event types

5.4.1 Overview

Browser event types are asynchronous events that are generated in response to changes in the status of the browser implementation. The following event types shall be implemented by each language binding. Additional implementation dependent events may be defined to supplement the provided event types.

5.4.1.1 SAI_Browser_Connection_Error

The event type representing an error condition has occurred in the internal connection between the browser and the external application (see 4.5.3.5 Connection Lost).

5.4.1.2 SAI_Browser_Event

The event type that represents the general class of events produced by each browser service (see 4.5.3 Browser to external application).

5.4.1.3 SAI_Browser_Initialized

The event type representing the browser having completed the initialisation process of loading X3D content (see 4.5.3.2 Initialize).

5.4.1.4 SAI_Browser_Shutdown

The event type representing the browser being shutdown. That is the execution model is no longer running or content is displayed (see 4.5.3.3 Shutdown).

5.4.1.5 SAI_Browser_URL_Error

The event type representing an error condition when no URLs could be processed to form valid X3D content (see 4.5.3.4 No URLs Available).

5.4.2 SAIFieldEvent

The event type used to represent the notification of a change in a field value that the external application has registered interest in.

--- X3D separator bar ---