6.1 Introduction and topics

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 Topics

See Table 6.1 for the topics for this clause.

6.2 Data type definitions

6.2.1 SAIAction

6.2.2 SAIBoolean

The data type is implemented as the primitive built-in bool type.

6.2.3 SAIBrowserApp

The data type is implemented as the interface X3DComponent data type. The capability to obtain a SAIBrowserRef is implemented in the getBrowser() function which returns an instance of the ExternalBrowser data type.

6.2.4 SAIBrowserName

6.2.5 SAIBrowserRef

The data type is implemented as a reference to an instance of the Browser data type.

6.2.6 SAIBrowserVersion

6.2.7 SAIComponent

The data type is implemented as a constant reference to an instance of the ComponentInfo. This presents a read-only view of a component and its information.

6.2.8 SAIComponentDeclaration

The data type is implemented as a data type with two members. The first member represents the name of the component and is defined as a reference to a null terminated array of the primitive built-in type char. The second member represents the support level and is defined using the primitive built-in type unsigned int.

6.2.9 SAIEncoding

The data type is implemented as an enumeration. Create the list of values for the SAIEncoding enumeration type.

6.2.10 SAIExecutionContext

The data type is represented by the X3DExecutionContext.

6.2.11 SAIField

The field identifier is represented as an instance of the data type that is appropriate to the field type. For each specific X3D field type, there shall be a data type that represents the field type, and includes strong type checking for the values. An implementation is not required to return the same data type instance for every query, but shall ensure that equivalence checking is correct through the implementation of the equals() function.

6.2.12 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 writable (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 SAIField 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.2.13 SAIFieldDeclaration

The data type is represented by the X3DFieldDefinition data type. This data type has a number of read-only properties defined. The definition of the properties available are described in 7.6.2 Field definition.

6.2.14 SAIFieldName

The name of the field is implemented as a char array type.

6.2.15 SAIFieldType

The field type may be represented in two alternative fashions.

The first alternative is provided through getType() function provided in the X3DField data type. 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 data types themselves. Field data types 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.2.16 SAIFieldValue

The field value is defined on a per data type 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 C primitive types using the mapping in Table 6.4.

In C for SFNode the data type is a reference (or pointer) to the X3DNode data type. Similarly for MFNode the data type is an array of references (or pointers) to the X3DNode data type.

6.2.17 SAIFrameRate

The data type is implemented as the built-in numeric type float. A null value is defined as the value 0.0f.

6.2.18 SAILayerID

The data type is implemented as the built-in int type.

6.2.19 SAILoadState

The load state is implemented as an enumeration. The values for each state are defined in Table 6.5.

It is strongly recommended thar the end user does not use the integer values. They should be using the defined enumerations names.

6.2.20 SAIMatrix

The data type is implemented as the Matrix data type.

6.2.21 SAINavSpeed

The data type is implemented as the built-in numeric float type. A null value is defined as the value 0.0f.

6.2.22 SAINode

   myShape.appearance = someNewAppearanceNode;

6.2.23 SAINodeType

EXAMPLE  The following two constants define the X3DGroupingNode and X3DUrlObject abstract node types:

X3DConstants.X3DGroupingNode
X3DConstants.X3DUrlObject

6.2.24 SAIParameterList

6.2.25 SAIProfileDeclaration

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

6.3.26 SAIPropertyList

The data type is implemented as an array of char types. Key/Value pairs are declared in a single char array 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.2.27 SAIProtoDeclaration

The component declaration is represented by two separate data types for PROTO and EXTERNPROTO. For PROTO, the data type is X3DProtoDeclaration. For EXTERNPROTO, the data type is X3DExternProtoDeclaration.

6.2.28 SAIRequester

The requester is represented as an instance of one of two data types depending on what information is being requested.

The requester is an instance of the data type representing the interface BrowserListener when the service request is registerBrowserInterest as specified in 6.3.20 registerBrowserInterest of ISO/IEC 19775-2.

The requester is an instance of the data type representing the interface X3DEventListener when the service request is registerFieldInterest as specified in 6.7.7 registerFieldInterest of ISO/IEC 19775-2.

6.2.29 SAIRoute

Routes are represented by the data type 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 data type that allow direct modification of the route.

6.2.30 SAIScene

The scene is represented by the X3DScene data type. 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.4 Scene Services.

6.2.31 SAIStream

6.2.32 SAIString

6.2.33 SAIUnitDeclaration

The unit declaration is represented by the UnitInfo data type. This data type presents a read-only view of a unit declaration and its information.

6.2.34 null

Null is implemented as the standard type NULL.

6.3 Error types

6.3.1 SAIError

All exceptions (errors) defined in this specification shall be derived from X3DException.

6.3.2 SAI_BROWSER_UNAVAILABLE

6.3.3 SAI_CONNECTION_ERROR

6.3.4 SAI_DISPOSED

The error type is implemented as five different exception classes error functions, depending on their context.

InvalidBrowserException is used to indicate that an SAIBrowserRef has been disposed.

InvalidExecutionContextException is used to indicate that an SAIExecutionContext has been disposed.

InvalidNodeException is used to indicate that an SAINode has been disposed.

InvalidRouteException is used to indicate that an SAIRoute has been disposed.

InvalidProtoException is used to indicate that an SAIProtoDeclaration has been disposed.

6.3.5 SAI_IMPORTED_NODE

6.3.6 SAI_INSUFFICIENT_CAPABILITIES

6.3.7 SAI_INVALID_ACCESS_TYPE

The error type is implemented as two separate exceptions based on the implementation of SAINode and the rules defined in Table 6.2.

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

6.3.8 SAI_INVALID_BROWSER

6.3.9 SAI_INVALID_DOCUMENT

6.3.10 SAI_INVALID_EXECUTION_CONTEXT

6.3.11 SAI_INVALID_FIELD

6.3.12 SAI_INVALID_NAME

6.3.13 SAI_INVALID_NODE

6.3.14 SAI_INVALID_OPERATION_TIMING

6.3.15 SAI_INVALID_URL

6.3.16 SAI_INVALID_X3D

6.3.17 SAI_NODE_IN_USE

6.3.18 SAI_NODE_NOT_AVAILABLE

6.3.19 SAI_NOT_SHARED

6.3.20 SAI_NOT_SUPPORTED

6.3.21 SAI_URL_UNAVAILABLE

6.4 Event types

6.4.1 Overview

6.4.2 SAI_Browser_Connection_Error

6.4.3 SAI_Browser_Event

6.4.4 SAI_Browser_Initialized

6.4.5 SAI_Browser_Shutdown

6.4.6 SAI_Browser_URL_Error

6.4.7 SAIFieldEvent