Extensible 3D (X3D)
Part 2: Scene access interface (SAI)
5 Data type reference
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, not the text functionality described in 15 Text component in part 1 of ISO/IEC 19775 (see 2.[I19775-1]).
SAIAction is a single valued field representing a qualifier for a more general service type. Each use of the SAIAction type shall define the range of acceptable values.
SAIAction represents a TRUE or FALSE value.
SAIBrowserApp is a data type that represents the complete browser application. This is different from 5.2.4 SAIBrowserRef because it defines the browser application itself whereas the SAIBrowserRef defines a reference to the standardised interface to the browser's functionality. The data type shall contain some method for obtaining an SAIBrowserRef.
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.
TSAIBrowserRef 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.
SAIBrowserVersion 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.
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.
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.
SAIEncoding specifies an identifier for an encoding type.
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.
This data type defines the type of access that is permitted to a field. The valid values are initializeOnly, inputOnly, outputOnly, and inputOutput.
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 could be considered a wrapper data type that includes SAIFieldAccess, SAIFieldName and SAIFieldType data types.
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.
SAIFieldName represents a name for a field.
SAIFieldType specifies the type of data a field represents. In some cases (where the field type represents an MFString or SFString), this field type may correspond to an SAINode. Valid types of the field are defined in 5 Field and event reference in part 1 of ISO/IEC 19775 (see 2.[I19775-1]).
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 and event reference in part 1 of ISO/IEC 19775 (see 2.[I19775-1]) shall be supported.
SAIFrameRate represents the rate in frames per second that is currently being achieved by the browser.
SAILoadState represents the load state of a node or EXTERNPROTO instance. The state shall be one of NOT_STARTED, IN_PROGRESS, COMPLETE or FAILED.
SAIMatrix specifies an identifier for a matrix 3×3 or 4×4 matrix.
SAINavSpped represents the navigation speed of the user in metres per second.
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.
SAINodeType represents the type of a node.
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.
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.
SAIPropertyList is an abstract data type defining a set of key/value pairs for the provision of properties.
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 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.
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.
SAIRoute represents a ROUTE construct. A ROUTE is not a node in the scene graph and does not represent a concrete structure.
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 or string, or be programmatically constructed through this API.
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.
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 an parameter to or return type of to any service definition.
SAIStream represents X3D content arriving continuously.
SAIString represents a string formatted with the UTF-8 universal character set. (see 2.[I10646-1]).
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.[RFC1738].
NULL represents the empty value. It contains no data or reference to any data type as a valid value to return from a service when nothing can be returned and yet no error is generated.
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.
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.
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.
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.
An operation was attempted that used an imported node when it is not permitted as defined in 4.4.6 Import/Export semantics in part 1 of ISO/IEC 19775 (see 2.[I19775-1]). For example, adding the imported node as a child to another node in the current scene.
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.
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.
The instance of SAIBrowserRef data type provided as part of the parameters to the service request has been disposed of prior to this request.
When the user has attempted to import a W3C 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. Examples are - an invalid document structure or not having the correct root element.
The instance of SAIExecutionContext data type provided as part of the parameters to this service request has been disposed of prior to this request.
The instance of SAIField data type provided as part of the parameters to this service request has been disposed of prior to this request.
The name provided to a service request is invalid or cannot be found in the context of that object.
The instance of SAINodeID data type provided as part of the parameters to this service request has been disposed of prior to this request.
The user is attempting to make a service request that is performed outside of the context that such operations are permitted in. 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.
The instance of SAIURL data type provided as part of the parameters to this service request is 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.
The 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.
Indication that a named node handling action has attempted to re-use a name that is already defined elsewhere in this current scene. For 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 are currently in use in another scene. It is an error to share a single node instance across multiple scenes simultaneously.
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.
A service request was made that assumed the browser was currently participating in a shared scene graph when it was not.
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.
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.5 getWorldURL) or getNode (6.4.6 getNode) service request.
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.
The data 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).
The data type that represents the general class of events produced by each browser service. (see 4.5.3 Browser to external application)
The data type representing the browser having completed the initialisation process of loading X3D content (see 4.5.3.2 Initialize).
The data 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).
The data type representing an error condition when no URLs could be processed to form valid X3D content (see 4.5.3.4 No URLs Available).
The data type used to represent the notification of a change in a field value that the external application has registered interest in.