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

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 C# implementations of that action. Actions are mapped as method names describing the action rather than strict primitive types.

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 class X3DComponent. The capability to obtain an SAIBrowserRef is implemented in the getBrowser() method which returns an instance of the ExternalBrowser class.

6.2.4 SAIBrowserName

6.2.5 SAIBrowserRef

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

6.2.6 SAIBrowserVersion

6.2.7 SAIComponentDeclaration

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

6.2.8 SAIComponent

The data type is implemented as a structure 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

6.2.10 SAIExecutionContext

The data type is represented by the X3DExecutionContext class.

6.2.11 SAIField

The field identifier is represented as an instance of the class that is appropriate to the field type. For each specific X3D field type, there shall be a derived class that represents the field type, and includes strong type checking for the values. An implementation is not required to return the same class 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 class. This class 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

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 class. 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 classes themselves. Field classes 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 class 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.

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

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

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 class. See 7.8.1 ProfileInfo for a detailed definition of this class.

6.3.26 SAIPropertyList

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 classes for PROTO and EXTERNPROTO. For PROTO, the class is X3DProtoDeclaration. For EXTERNPROTO, the class is X3DExternProtoDeclaration.

6.2.28 SAIRequester

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

The requester is an instance of the class 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 class 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 class 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 class that allow direct modification of the route.

6.2.30 SAIScene

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

6.2.31 SAIStream

6.2.32 SAIString

6.2.33 SAIUnitDeclaration

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

6.2.34 SAIFile

6.2.35 null

Null is implemented as the standard type NULL.

6.3 Error data types

6.3.1 SAIError

The error types are implemented as the exception class X3DException. 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

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

InvalidNodeException is used to indicate that an SAINode 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

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() method.

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.4 Event types

6.4.1 Overview

Browser event types are distinguished by an enumeration. The values for each type are defined in Table 6.6.

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 SAIFieldEvent