6.1 Introduction and table of contents

6.1.1 Introduction

This clause provides a detailed definition of the semantics of the services that a browser shall provide to external applications as defined in this part of ISO/IEC 19775-18:200x.

6.1.2 Table of contents

Table 6.1 is a Table of Contents for this clause.

6.1.3 Conventions used

Each of the services in this clause defines a particular request that can be made through the Scene Authoring Interface. Each request is defined by a number of characteristics. In Table 6.1 the first column defines each characteristic type and the second defines the properties of that characteristic.

Parameters shown in square brackets [] are optional and not required to be passed with that service request.

All characteristics defined for every service shall be implemented for each language binding. At the end of each table, some explanatory text will follow which includes extra information pertinent to the implementation of that service.

6.2 Establishing a Connection

6.2.1 Introduction

The following services can be used to establish a session and an obtain a browser reference. Individual browser implementations may support one or both of these methods. At least one shall be required to be supported.

6.2.2 getBrowser

This is a blocking call. No further requests from this external application will be processed until an SAIBrowser value has been generated (which may include the need to start a new instance of a X3D browser) or an error condition is generated.

If an application makes a request for the same browser twice in the same session then the same browser identifier shall be returned.

An implementation may define more than one variant of this service with different parameter types. For example there may be alternate forms to access a browser embedded in a HTML page and one for remote access from another machine within the same language binding.

Additional error types may be added by individual language bindings to deal with platform specific issues.

6.2.3 createBrowser

Create a new instance of a browser application. The browser shall start with no URL set (that is no active X3D scene graph). The URL may be set at a later time using the loadURL (see 6.3.14 loadURL) or replaceWorld (see 6.3.12 replaceWorld) service requests.

The property list is used to define the properties of the browser application itself. The service request shall use the same property list definitions as those defined in loadURL. It is not required to support exactly the same capabilities, but the property list format shall be identical and any behaviours are identical.

This is a blocking request. No further requests from this external application will be processed until an SAIBrowser value has been generated (which may include the need to start a new instance of a X3D browser) or an error condition is generated.

Each request of this service shall produce a new browser application instance in accordance with the supplied parameter values.

An implementation may define more than one variant of this service with different parameter types. For example there may be alternate forms to start a browser on a remote machine or to create a new window within a running application.

Additional error types may be added by individual language bindings to deal with platform specific issues.

Individual language bindings may add extra calls to the EAIBrowserApp to get the language and platform-specific low-level handle. For example, it may allow the access to the raw image pixel data for an offline image renderer so that a user may use platform-specific calls to make extra drawing and compositiong actions.

6.3 Browser services

6.3.1 Introduction

The following services can be requested from a browser. Although not specified, all services are capable of throwing an SAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

Note: The data representation of the parameters or return values are not specified. It could be equally valid to represent all parameters as strings as it is for binary representations.

6.3.2 getName

The name of the browser is implementation dependent. If this service is not supported a NULL value shall be returned.

6.3.3 getVersion

The version number of the browser is implementation dependent. If this service is not supported then a NULL value shall be returned.

6.3.4 getCurrentSpeed

The current speed is the average navigation speed for the currently bound NavigationInfo node in metres per second in the coordinate system of the currently bound viewpoint.

6.3.5 getCurrentFrameRate

Get the current frame display rate of the browser. If this is not supported the value returned is zero.

6.3.6 getSupportedProfiles

Get the list of all profiles that are supported by this browser. All browsers shall support at least one profile.  It shall be an error if the browser returns a declaration for a profile that it does not fully support.

6.3.7 getProfile

Get the declaration of the named profile. The SAIString parameter is the name of a profile to fetch the declaration from and shall conform exactly to the naming conventions used in the file format. It shall be an error if the user provides a name with wrong case, bad spelling or anything other than an exact match. The browser is only required to return a SAIProfileDeclaration if it supports the named profile. If it does not support the named profile then SAI_NOT_SUPPORTED is generated.

6.3.8 getSupportedComponents

Get the list of all components that are supported by this browser. All browsers shall support at least one component, as required to support profiles.

6.3.9 getComponent

Get the declaration of the named component. The SAIComponentID parameter is the name of a profile to fetch the declaration from and shall conform exactly to the naming conventions used in the file format. It shall be an error if the user provides a name with wrong case, bad spelling or anything other than an exact match. The browser is only required to return a SAIComponentDeclaration if it supports the named component and the requested level. If it does not support the component at the level desired then SAI_NOT_SUPPORTED is generated.

6.3.10 getExecutionContext

Get the execution context that this node exists in. The execution context is the base form of a scene, but only provides access to the local nodes, protos and routes as defined by the X3D name scoping rules as defined in 4.4.7 Run-time name scope of ISO/IEC 19775-1 (see 2.[I19775-1]). Depending on the place in the scene graph, the returned type may be a SAISceneID allowing the user to use the greater capabilities.

6.3.11 createScene

Create a new empty scene that conforms to the given profile and component declarations. Although the specification does not require either be provided, it shall be an error to provide neither profile nor component definitions. A user shall provide at least one valid profile or component identifier to this request.

A scene created this way will always have its specification version set to "3.0" and the encoding set to "Scripted".

6.3.12 replaceWorld

The SAI_B_Shutdown event is generated immediately upon receiving this service request.

The SAI_B_Initialized event is generated when the new nodes have been set and all browser specific initialization has taken place but before the first time driven event cascade has been started (event cascades may have previously resulted due to the initialization process through internal scripts).

Replace the current world with the SAISceneID that contains the list of nodes, routes and exports. If another replaceWorld or loadURL request is made during the processing of the current request, the current request is terminated and the new one started. In this case, no extra shutdown event shall be generated. The initialize event shall be generated at the point where the world is ready to be run. The scene is not required to contain any valid content. Setting a value of NULL shall clear the currently set scene and leave a blank browser with no renderable content and no current scene.

6.3.13 importDocument

A utility request to import a W3C DOM document or document fragment and convert it to an X3D scene. The input allows any form of Node as defined by the W3C DOM Level 2 specification []. Although all derived types are available, it shall only be required that DOCUMENT, DOCUMENT_FRAGMENT, and ELEMENT types are required to be supported for the conversion process.  The method only performs a conversion process and does not display the resulting scene. The scene may then be used as the argument for the replaceWorld service. When the conversion is made, there is no lasting connection between the DOM and the generated scene. Each request shall be a one-off conversion attempt (the conversion may not be successful if the DOM does not match the X3D scene graph structure).

Support for this method is optional and shall be dependent on the browser support for the XML encoding (see 2.[I19776-1]). If the browser implementation supports the XML encoding it shall support this service. If the browser does not support the XML encoding, the implementation may support this service. User code may check that this service is supported through the checking the browser properties with the getBrowserProperties service. If this service is not supported by the browser implementation, SAI_NOT_SUPPORTED error is generated.

6.3.14 loadURL

The SAI_B_Shutdown event is generated immediately upon receiving this service request if the parameter list is such that the browser is about to be shutdown (for example replaces a HTML Frame where the browser was embedded).

The SAI_B_Initialized event is generated when the new nodes have been set and all browser specific initialization has taken place but before the first time driven event cascade has been started (event cascades may have previously resulted due to the initialization process through internal scripts).

The property list definition shall include at least one property that defines loading the URL supplied as a new world in the supplied SAIBrowserRef. If the property list is empty then the action is to replace the world of the current browser with the new world if the successful URL is a X3D file.

If another replaceWorld or loadURL request is made during the processing of the current request, the current request is terminated and the new one started. In this case, no extra shutdown event shall be generated. The initialise event shall be generated at the point where the world is ready to be run if replaceWorld was called.

6.3.15 setDescription

If the browser supports a description title, it shall be set to the new description. Typically, this will be the title in a window title bar. In cases where there may be multiple browsers on a single window, the result is implementation dependent.

6.3.16 createX3DFromString

This service creates nodes from a string. The string shall contain valid X3D syntax; otherwise an error is generated. If any relative URLs are encountered in this string, the base is assumed to be the current browser location. The string is not required to contain the X3D file header. If it is present, it shall be treated as an indicator to the version of X3D contained. If absent, the default version assumed shall be that specified in ISO/IEC 19775-18:200x 4.2.2 Header. A browser is not required to support any versions prior to ISO/IEC 19775-18:200x.

If the string contains legal X3D statements but does not contain any node instances,  a valid scene ID shall still be returned containng no root nodes, but with the appropriate declaration IDs. For example the string may contain EXTERNPROTO declarations but no instances of any node. If the SAIString provides the content in an encoding format that the browser implementation does not support, then the browser shall generate an SAI_NOT_SUPPORTED error.

6.3.17 createX3DFromStream

This service creates nodes from an arbitrary, user-provided stream of input data. The stream shall contain valid X3D syntax from the first character; otherwise, an error is generated. If any relative URLs are encountered in this string, the base is assumed to be the current browser location. The stream is required to include the X3D File Header in accordance with the encoding requirements for the format.

If the string contains legal X3D statements but does not contain any node instances,  a valid scene ID shall still be returned containing no root nodes, but with the appropriate declaration IDs. For example, the string may contain EXTERNPROTO declarations but no instances of any node. If the SAIStream provides the content in an encoding format that the browser implementation does not support, the browser shall generate an SAI_NOT_SUPPORTED error.

6.3.18 createX3DFromURL

This service creates nodes from the contents of the file represented by the URL. The URL may be a relative URL which is considered to be using the browser location as the base document. The scene described by that URL shall be the returned ID.

6.3.19 updateControl

The SAIAction parameter specifies the actions that may be applied against the buffer. Other actions may be added, such as to query the number of items, or the state of the buffer and are implementation dependent. Table 6.3 defines the actions specified in this part of ISO/IEC 19775.

Table 6.3 — updateControl SAIAction values

The timestamp of events generated at the call to endUpdate are implementation dependent but should be consistent with the time within the current world. That is, timestamps cannot be in the "past" relative to the other current events generated internally with event model at the time when they are generated.

Begin update and End update are not nesting calls. Once begin update has been called, it may be called any number of times, but only a single end update call is needed to release the buffered events into the scene graph. A call to end update without a previous matching begin update has no effect.

6.3.20 registerBrowserInterest

This service nominates the requester as the receiver of all SAIBrowserEvents. The act of making this service request itself does not imply any events shall be generated.

The parameter of type SAIRequesterID could be inferred from the source of the input and may not need to be part of the parameters and is implementation dependent. Each binding to this service shall specify this requirement.

The parameter of type SAIAction specifies whether this is a request to add interest in events, or to remove interest in the events.  Table 6.4 defines the actions specified in this part of ISO/IEC 19775.

Table 6.4 — registerBrowserInterest SAIAction values

Any change to the current browser shall be notified to the listener that has registered interest in these events. These event notifications must be made independent of the method of communicating with the browser.

As a minimum, a conforming implementation shall provide the events defined in 4.5.3, Browser to External Application.

6.3.21 shareWorld

Control the state of this browser instance as a shared situation.

The first SAIBrowserRef parameter is the current browser that will be participating in the sharing ie the Dependent Browser.

The second SAIBrowserRef parameter is the target, source browser. It shall not be NULL when the action is to start sharing. If it is a reference to the same browser as the dependent browser then an error shall be generated. If the reference is to another dependent browser an error shall be generated.

The SAIAction is used to control whether to start sharing or to stop it.  Table 6.5 defines the actions specified in this part of ISO/IEC 19775.

Table 6.5 — shareWorld SAIAction values

The first SAINode parameter is the Viewpoint node instance or a Prototype instance thereof. It shall not be null. If it is not a Viewpoint node, an error shall be generated.

The second SAINode parameter is the optional NavigationInfo node instance or a Prototype instance thereof. It may be null. If if is not a NavigationInfo node or null, an error shall be generated.

The shutdown event shall only be issued by the dependent browser when the action is to start sharing. No events shall be issued when the browser stops sharing.

6.3.22 setSharedViewpoint

Set a new Viewpoint node instance, or Prototype instance thereof, in this dependent browser.

If the node reference is null or not a Viewpoint an error shall be generated. If the browser reference is not a dependent browser or is not participating in a shared scene, an error shall be generated.

6.3.23 setSharedNavigation

Set or clear the NavigationInfo node instance, or Prototype instance thereof, in this dependent browser.

If the node reference is not a NavigationInfo an error shall be generated. If the node reference is NULL it shall clear the currently set node instance and use the correct instance defined by the shared scene graph and the binding stack rules.

If the browser reference is not a dependent browser or is not participating in a shared scene, an error shall be generated.

6.3.24 getRenderingProperties

Used to query for the rendering capabilities of the browser. This gives a list of the low-level hardware capabilities of the browser rather than what X3D Components are supported. For example, it will give the user an idea of how many multi-texture units can be handled and allows the end user to customize the number of nodes to use in the MultiTexture node. The keys and values in the property list are implementation dependent and are for informative purposes only. Table 6.6 lists the properties that are returned by this service.

The user shall not be able to directly effect the rendering properties of the browser by modifying the properties returned by this service.

6.3.25 getBrowserProperties

Used to query for the capabilities of the browser reference itself. This gives a list of the expanded interfaces that this browser reference is capable of supporting. For example it may be used to query for the existance of browser implementation-specific extensions to the defined browser class or future extensions as provided by this specification.

Table 6.7 defines some standard property names that are reserved by part of ISO/IEC 19775. Where a browser implementor chooses to add additional capabilities, the naming convention of these additional properties shall follow the guidelines defined in 4.1.3 Conventions used of ISO/IEC 19775-1 (see 2.[I19775-1]).

6.3.26 changeViewpoint

Change the currently bound X3DViewpointNode instance to the instance defined by the action. Valid action types are previous, next, first and last. When the viewpoint is changed using this service request, the browser shall first unbind the current instance and then bind the new instance. That is, the number of items on the bindable stack bindable nodes shall not increase as a result of making this service request. Table 6.8 defines the actions specified in this part of ISO/IEC 19775.

Table 6.8 — changeViewpoint SAIAction values

This service request implies that there is a standard, well known ordering of the X3DViewpointNode instances so that consistent visual behaviour shall be observed. The order shall be based on the following rules:

1. The order declared in the originally parsed file or stream, including resolution of PROTO instances, but not including EXTERNPROTO or X3DInlineNode instances
2. Dynamically created node instances are always appended
3. Instances located in X3DInlineNode instances and EXTERNPROTO instances shall be in the order that the external scene is resolved in, and appended to the list. The inclusion of these external instances is also dependent on the browser property LIST_INLINE_VIEWPOINTS

If the world only contains the default X3DViewpointNode instance this request has no effect in the visual output. (Is this the behaviour we want, or should it be like re-binding the viewpoint back to the original position?)

Need reference to part 1 wording on this about the UI actions and recommendations

Recommendation for global browser property to allow/disallow the inclusion of inlined viewpoints.

6.3.27 print

Print a message to the browser's console. The langauage-specific bindings may provide overloaded variations on this service that do not take a SAIString, but take other data types. Other variants may include the ability to automatically add line-feed/newline characters without the need to explicitly declare it in the SAIString. A binding shall provide at least the base SAIString variant.

User code may call this service at any time, without restriction, unless the browser reference has been disposed of.

6.3.28 dispose

The client is about to exit this session and the browser is free to dispose of any resources that this client may have consumed. An SAI_B_Shutdown event is sent only to this client and may be generated internally by the language implementation on the client machine (that is, it is not required that the browser itself generate this event, just that the event is generated). If any events have been held because begin update has been called, disposing of the browser shall also call end update to release those events to the browser.

6.4 Execution Context Services

6.4.1 getSpecificationVersion

Fetch the version string that describes which specification version this scene adheres to. This version represents the appropriate version number as defined in in ISO/IEC 14772-1, ISO/IEC 19775-1:200x or, if optionally supported, the original, non-ISO VRML 1.0c specification.

6.4.2 getEncoding

Get the encoding type that was used for this file. The encoding is one of a fixed set, but may include additional types that are browser implementation specific. The minimum required set of values (but not necessarily supported by the browser implementation) shall be:

1. Scripted: For scenes that are created completely through the SAI and did not originate through a file somewhere.
2. ASCII: For VRML 1.0 specification files.
3. VRML: For VRML97 and the X3D Classic VRML encoding (see 2.[I19776-2]).
4. XML: For X3D XML-encoded files (see 2.[I19776-1]).
5. Binary: For X3D Binary-encoded files (see 2.[I19776-3]).
6. BIFS: For MPEG-4 BIFS-encoded format. (see 2.[I14496])

6.4.3 getProfile

Get the profile that is used to describe this scene. If the specification version is for a specification version prior to X3D, the profile shall be VRML97. If no profile is provided, this shall return NULL.

6.4.4 getComponents

Get the component(s) used to describe the scene. The list given shall represent only explicit component declarations and not the implied components from the profile declaration. If no component definitions are set, then NULL shall be returned.

6.4.5 getWorldURL

Get the fully qualified URL of this scene. This returns the entire URL including  any possible arguments that might be associated with a CGI call or similar mechanism. If the world was created entirely programmatically, the URL shall be NULL.

6.4.6 getNode

The SAIString is to identify the name of the node that has been marked with one of the naming statements DEF, IMPORT or EXPORT in the currently loaded X3D scene or previously added with an named node handling request (see 6.4.9 Named Node Handling).

The SAIAction shall indicate which of the naming types shall be used to find the node. For example, providing an action of "imported node" shall not return a name that may be valid, but describes a node named with the DEF statement.  Table 6.9 defines the actions specified in this part of ISO/IEC 19775.

Table 6.9 — getNode SAIAction values

Access shall only be available to names in this scene. DEFs in Inlined files shall not be accessible in accordance with 4.4.3 DEF/USE Semantics and 4.4.6, Import/Export semantics, both in ISO/IEC 19775-1 (see 2.[I19775-1]).

If the SAIAction is for IMPORTED nodes and the name is valid but the node definition is not yet available from the source Inline node, then SAI_NODE_NOT_AVAILABLE shall be generated.

6.4.7 createNode

Convenience service that creates a new, default instance of the node given by the SAIString. The availablilty of the node is defined by the containing scene's profile and component declarations. The name shall only refer to a built-in node and shall not be used to create instances of PROTOs or EXTERNPROTOs. If the node is not available in the current profile and component spaces, the browser shall generated the SAI_INVALID_NAME error.

6.4.8 createProto

Convenience service that creates a new, default instance of the named PROTO. The naming and scoping rules for creating a proto instance which the current execution context is inside another proto is defined by 4.4.7, Run-time name scope, in ISO/IEC 19775-1 (see 2.[I19775-1]). If there is no PROTO declaration available that matches the given name then the browser shall generated the SAI_INVALID_NAME error.

6.4.9 namedNodeHandling

Request to add, remove or change the node identified by the SAIString where that name is considered to use the DEF, or IMPORT semantics. The add/remove/change shall be described by the first SAIAction. If the name already exists as a mapping, the current mapping is replaced with the new map. When adding a new named node, it is not required to be an part of this scene.

The second SAIAction describes which of the DEF or IMPORT naming facilities shall be the target of this service request. This ensures that correct semantics are applied. If the action is to add and the name is already registered then SAI_NODE_IN_USE is generated. If the action is to replace or update, and the node is not already registered, the implementation may treat this as an add request. Table 6.10 defines the actions specified in this part of ISO/IEC 19775.

Table 6.10 — namedNodeHandling SAIAction values

The first SAIString is to identify a name with a node as it should be known in this scene. The name is not an intrinsic property of the node and this only serves as a mapping function.

The second argument provides an option depending on the action being undertaken. SAINodeID is a reference to the node that you may need for verification of the DEF name addition. For adding IMPORTs, the second string shall be the exported node name in the DEF'd inline and the optional third string shall be the name to store it as in this scene.

6.4.10 getProtoDeclaration

Fetch the named PROTO declaration representation from this scene.  This shall only be used to request for PROTO declarations. A request for an EXTERNPROTO declaration shall generate an error.

6.4.11 protoDeclarationHandling

Request to add, remove or change the ProtoDeclaration identified by the SAIString.

The SAIAction parameter is used to indicate if the service request is an add or removal of the declaration node. If the name already exists as a mapping, then the current mapping is replaced with the new map. When adding a new declaration it may come from another scene. Table 6.11 defines the actions specified in this part of ISO/IEC 19775.

Table 6.11 — protoDeclarationHandling SAIAction values

6.4.12 getExternProtoDeclaration

Fetch the named EXTERNPROTO declaration representation from this scene.  This shall only be used to request for EXTERNPROTO declarations. A request for a PROTO declaration shall generate an error.

6.4.13 externprotoDeclarationHandling

Request to add, remove or change the ExternProtoDeclaration identified by the SAIString.

The SAIAction parameter is used to indicate if the service request is an add or removal of the declaration node. If the name already exists as a mapping, the current mapping is replaced with the new map. When adding a new declaration it may come from another scene. Table 6.12 defines the actions specified in this part of ISO/IEC 19775.

Table 6.12 — externprotoDeclarationHandling SAIAction values

6.4.14 getRootNodes

Get the listing of the current root nodes of the execution context. If the context was generated from a file, the root nodes are in the order they were declared in the file. Any added nodes are then appended to the list in the time order they were received at the browser. If the context was generated programmatically, the nodes are in the order they are received by the browser.

6.4.15 getRoutes

Get the list of the current routes in the scene. The route listing returned will only be the top level routes. Routes contained within a PROTO definition or a prototype instance shall not be included in this list.

6.4.16 dynamicRouteHandling

The parameter of type SAIAction specifies whether this should be an add or delete of this route. Other actions may be added, such as to query the existence of the nominated route. Actions defined by this part of ISO/IEC 19775 are described in Table 6.13. The SAINodeID/SAIFieldID pair parameters are considered as defining the source field and destination fields for the route request.

Table 6.13 — dynamicRouteHandling SAIAction values

Route modification requests are to fit with the general event model scheme as defined in 4.4.8, Event model of ISO/IEC 19775-1 (see 2.[I19775-1]). The end of the event cascade is considered to be the cascade that is initiated by the application sending events into the X3D browser environment. Any new cascades generated as a result of the processing of the initial events are shall not be considered for the determination of the event cascade.

If the action is to delete a route, and the route has previously been deleted, no error should be generated.

6.4.17 dispose

The client has no further interest in the resource represented by this execution context. The browser is now free to take whatever action is necessary to reclaim any resources consumed by this execution context, at any time in the future. If this execution context has already been disposed, further requests have no effect.

6.5 Scene services

6.5.1 Introduction

A scene is an extension of the Execution Context services with the addition services provided. The Scene implementation shall include all of the services from 6.4 Execution Context Services, and include the following additional services.

6.5.2 getMetaData

Get an item of meta data in the scene. Meta data is considered to be represented as SAIString key/value pairs. Each key corresponds to exactly zero or one value. Optionally the browser may provide a sub-service to discover the valid keys for this scene as part of this service.

6.5.3 setMetaData

Set an item of meta data in the scene. Meta data is considered to be represented as SAIString key/value pairs. Each key corresponds to exactly zero or one value. Setting an item with a key that already exists replaces the existing value. If the value is null for the given key then the key is removed from the meta data list.

6.5.4 namedNodeHandling

In addition to the capabilities described in 6.4.9 Named Node Handling, the Scene services expand the capability to also work with exporting nodes. The definition is expanded to the following:

Request to add, remove or change the node identified by the SAIString where that name is considered to use the DEF, or IMPORT or EXPORT semantics. The add/remove/change shall be described by the first SAIAction. If the name already exists as a mapping, then the current mapping is replaced with the new map. When adding a new named node, it is not required to be an part of this scene.

The second SAIAction describes which of the DEF, IMPORT or EXPORT naming facilities shall be the target of this service request. This ensures that correct semantics are applied. If the action is to add and the name is already registered then SAI_NODE_IN_USE is generated. If the action is to replace or update, and the node is not already registered, the implementation may treat this as an add request.

The first SAIString is to identify a name with a node as it should be known in this scene. The name is not an intrinsic property of the node and this only serves as a mapping function.

The second argument provides an option depending on the action being undertaken. SAINodeID is a reference to the node that you may need for verification of EXPORT or DEF name addition. For adding IMPORTs, the second string shall be the exported node name in the DEF'd inline and the optional third string shall be the name to store it as in this scene (this corresponds with the UTF8 Syntax of IMPORT inlined_def.export_name [AS import_name]). For adding EXPORTs the second argument shall be the string, which is the optional name to export the node as. If the first SAIString does not describe a node marked with DEF, it shall generate a SAI_INVALID_NAME error.

6.5.5 rootNodeHandling

Request to add and remove the root nodes of this scene. The root node may contain an entire sub-scene graph below it.

The SAIAction parameter is used to indicate if the service request is an add or removal of the node. If the action is to remove and the node is not a known root node then this shall generate an error. If the action is to add the node, it shall be appended to the current list of root nodes. Table 6.14 defines the actions specified in this part of ISO/IEC 19775.

Table 6.14 — rootNodeHandling SAIAction values

Nodes are bound by the capabilities of the containing scene. No node shall be of greater capabilities than the scene's declared profile and additional components. SAI_INSUFFICIENT_CAPABILITIES shall be generated if the action is to add node to the scene and that node requires greater capabilities than the scene permits.

If the action is to add a node and the node or any of its children is currently part of another scene, generate SAI_NODE_IN_USE.

If the action is to remove a node and the node is not a known value of this field, the request shall be silently ignored.

6.6 Node services

6.6.1 Introduction

The following services can be requested of an individual node. Each service requires that you have an identifier for that node. After a request of an individual node to dispose of their resources, any further request made to a node service shall generate  a disposed error.

Although not specified, all services are capable of throwing an SAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

6.6.2 getTypeName

Request the name of the type of this node. The name is the name as specified in ISO/IEC 19775-1 where the node type is defined (see the Node index in 2.[I19775-1]). If the node represents a PROTO node instance, the type name returned is the name of the PROTO declaration.

6.6.3 getType

The type indicator is either the type defined for the basic node types in the X3D specification, or the PROTO type name if it is a prototyped node. This is not required to be supported for a conforming implementation.

6.6.4 getField

Request a field identifier so that operations can be performed on the node properties. If the field requested is an exposedField then either the field name or the set_ and _changed modifiers may be used to access the appropriate form of the node as required. Access to fields is implementation dependent.

6.6.5 getFieldDefinitions

Request a list of all the field definitions of this node. The definitions provide a limited form of the FieldID that has all the same services except the ability to read or write the value of the field for a specific node instance. This request returns the FieldIDs as generic responses for every instance of this node rather than a for a specific instance.

6.6.6 dispose

The client has no further interest in the resource represented by this node. The browser is now free to take whatever action is necessary to reclaim any resources consumed by this node, at any time in the future. If this node has already been disposed, further requests have no effect.

Disposing of a node does not remove the node from the scenegraph (if it was inserted in the first place) but rather removes any local information per client to it. The underlying X3D node representation is only disposed of if no other applications or scenegraph structures contain references to this node and the responsibility and timing for this action is browser implementation specific.

6.7 Field services

6.7.1 Introduction

The following are services that can be requested of individual fields of a node. If the node that a field was retrieved from has been disposed, field services are still permitted to operate providing that the field reference has been obtained before disposing of the node. If a call is made to a field service after requesting to dispose of the field, a disposed error shalll be generated.

Although not specified, all services are capable of throwing an SAI_CONNECTION_ERROR whenever a request is made if the session between the application and the browser has failed.

6.7.2 getAccessType

The representation of the access type is implementation dependent.

6.7.3 getType

The type of the field is implementation dependent.

6.7.4 getName

If supported by the implementation, this will return the name of the field as it was requested from the node. If the service requested the set_children field of a grouping node, this will return "set_children", but if a different request was for children on the same node, "children" will be returned.

6.7.5 getValue

Get the value represented by this field as it exists in the world. This will represent the current value of the field at the time of the request. If the request is made of a field that has a setValue request buffered through begin update, the value returned shall be the old value prior to the setValue request. The value of the field may be a NODE if the field represents an MFNode or SFNode.

All field types shall support the option to get a single value from multi-valued arrays.

6.7.6 setValue

Set the value of this field. Set requests shall obey the requirements as specified the buffer_events service.

The value of the field may be a SAINodeID if the field represents an MFNode or SFNode. It is permitted to send a null to a node or field in order to clear the value from that field. For example sending a null to the appearance inputOutput field of a Shape node as specified in 12, Shape component, in ISO/IEC 19775-1 (see 2.[I19775-1]), shall result in the appearance field being cleared and set to the default value of NULL.

If the SAINodeID is registered as an IMPORTed node in this file, it shall generate the SAI_IMPORTED_NODE error.

All field setting services implementations shall include the ability to set individual values. Fields that describe multivalue arrays shall also include the ability to append and remove items from the existing field.

6.7.7 registerFieldInterest

This service nominates the requester as the receiver of all SAIFieldEvents. The act of making this service request itself does not imply any events shall be generated.  Table 6.15 defines the actions specified in this part of ISO/IEC 19775.

Table 6.15 — registerFieldInterest SAIAction values

The parameter of type SAIRequesterID could be inferred from the source of the input and may not need to be part of the parameters.

The parameter of type SAIAction specifies whether this is a request to add interest  in events, or to remove interest in the events.

What capabilities are permitted to be listened to are implementation dependent. For example, some implementations may permit listening to eventIn values and eventOut values while others will only permit eventOut values to be listened to.

For SFNode and MFNode field types, the following additional behaviour is specified:

Nodes are bound by the capabilities of the containing scene. No node shall be of greater capabilities than the scene's declared profile and additional components. SAI_INSUFFICIENT_CAPABILITIES shall be generated if the action is to add node to the scene and that node requires greater capabilities than the scene permits.

If the action is to add a node and the node or any of its children is currently part of another scene, generate SAI_NODE_IN_USE.

If the action is to remove a node and the node is not a known value of this field, the request shall be silently ignored.

6.7.8 dispose

The client has no further interest in the resource represented by this field. The browser is now free to take whatever action is necessary to reclaim any resources consumed by this field, at any time in the future. If this field has already been disposed, further requests have no effect.

6.8 Route Services

6.8.1 getSourceNode

Get the source node of this ROUTE.

6.8.2 getSourceField

Get the name of the source field of this ROUTE.

6.8.3 getDestinationNode

Get the destination node of this ROUTE.

6.8.4 getDestinationField

Get the name of the destination field of this ROUTE.

6.8.5 dispose

The client has no further interest in the resource represented by this route. The browser is now free to take whatever action is necessary to reclaim any resources consumed by this route, at any time in the future. If this route has already been disposed, further requests have no effect.

Disposing of a route does not remove the route from the scene graph (if it was inserted in the first place) but rather removes any local information per client to it. The underlying X3D node representation is only disposed of if no other applications or scene graph structures contain references to this route and the responsibility and timing for this action is browser implementation specific.

6.9 Prototype Services

6.9.1 isExternproto

A check to see if the prototype declaration represents a PROTO or EXTERNPROTO. If it is an EXTERNPROTO a true value shall be returned, and PROTO declarations shall return false.

6.9.2 createInstance

From the declaration of either a PROTO or EXTERNPROTO, create a new instance. An EXTERNPROTO instance may fail with SAI_INVALID_NODE if the definition has not been loaded yet.

6.9.3 getFieldDefinitions

Request a list of all the field definitions of the PROTO or EXTERNPROTO declaration. The definitions provide a limited form of the FieldID that has all the same services except the ability to read or write the value of the field for a specific node instance.

6.9.4 checkLoadState

Check on the current load state of the EXTERNPROTO definition. The state shall be one of NOT_STARTED, IN_PROGRESS, COMPLETE or FAILED.  If this is called on a PROTO a SAI_INVALID_NODE error shall be generated.

6.9.5 requestImmediateLoad

If this represents an EXTERNPROTO then request that the browser start immediate loading of that definition now. If the definition is already loaded or the load is already in progress, this request shall be silently ignored.

6.10 Services Provided by Script Content

6.10.1 General

When an author provides the executable content of a script, certain conventions are required to be met. This allows the browser to communicate unambiguously status information regardless of the type of content language. This clause defines services that are required to be defined by the individual language bindings in a manner that script content may be informed in a consistent, unambiguous manner. Script content shall be required to run identically regardless of language used to author the content. In a contrast to the other services specification, the browser shall make these service requests of the user's code, and therefore the user code must provide implementations of these, where necessary. All services are defined at the user's discretion and if the user does not define the service implementation, the browser shall silently continue on.

6.10.2 Creation Phase

During the creation phase, the script content is downloaded and an instance of the content created in the appropriate execution engine. Some content may require separate interpreters, while others may be created in the same address and execution space as the browser code (eg scripts created in the same language as the browser itself was written in). Apart from the instantiation process, which is language dependent, the browser shall not require any services.

6.10.3 Setup Phase

6.10.2.1 setBrowser

Pass to the script implementation code the reference to the SAIBrowserRef to be used.  There is no other way of acquiring the SAIBrowserRef during the lifetime of the script, so if the user code needs to know about it, it should store it now. This service shall be performed before any other service requests are made. The browser is free to call this service at any time between the creation phase and before the initialize service request is made. The browser is not required to request it during the initialization process as defined by the X3D Event model, (;">see Part1 4.XYZ) although Browser implementers are encouraged to.

6.10.2.2 setFields

Pass the list of fields declared in this script node instance. Also pass in the external view of the containing script node so that the user may add and remove ROUTEs to the script directly. The SAIFieldIDs represent all of the custom fields of the script, but shall not include the list of pre-defined fields (i.e., mustEvaluate, directOutput and url for a Script node). This request shall be performed between setBrowser.

6.10.2.3 initialize

Notification to the script that all basic initialization has been completed and that the user code is active in the scene graph.  At this point in time, the user code may access script field values and change at will.

6.10.3 Realized Phase

6.10.3.1 prepareEvents

Notification that the browser is about to start the event cascade processing in accordance with step 4 of the event execution model as described in 4.4.8.3, Execution model, of ISO/IEC 19775-1 (see 2.[I19775-1]). All values changed during this call shall have the current time stamp, but events shall not be immediately propagated upon return from the user code. This service request shall be called every frame regardless of whether the containing node received any events or not. If the containing node provides directOutputs, these shall be passed immediately to the underlying nodes.

6.10.3.2 eventsProcessed

Notification that the current event cascade processing has finished and that the containing node is allowed to make updates to the scene graph now. Useful for user code that wishes to be more efficient and only generate new events after a collection of field changes are received. Within a given frame, user code may have this service called more than once. User code cannot guarantee that all changes to the containing node will be received by this time and should take appropriate precautions. This service request shall only be called after the containing node has received one or more events in this timestamp. If the containing node has received no events in the current timestamp it shall be an error for the browser to request this service.

6.10.4 Disposed Phase

6.10.4.1 shutdown

Notification that the user code has been disposed of by the containing node. This may be due to the complete shutdown of the browser, the loaded world changing or the containing node changing the user code to another implementation. After this service request has been completed, user code will no longer be functional or executed.

6.11 General Utility Services

6.11.1 Matrix

6.11.1.1 General Information

Matrix objects represent the standard mathematic matrix capabilities using double precision numbers and column-major order. All services here shall be interpreted using standard mathematical definitions of matrices.

Implementations shall provide matrices that are 3x3 and 4x4. They are may define other orders of matrices. Implementations may also define additional convenience services in addition to this minimum subset - for example, the ability to individually.  Implementations may allow direct access to the individual row and column values of the matrix.

In the following service definitions, the parameters describe single precision inputs. An implementation shall also provided overloaded definitions that include double precision input.

6.11.1.2 set

Set the matrix to the new value calculated from the parameters. The parameters are defined to represent, in order: translation, rotation, scale, scaleOrientation and center. If the end user does not specify a value for a parameter, the default value for that parameter shall be the default value for the equivalent field of the Transform node defined in 10.4.4, Transform, of ISO/IEC 19775-1 (see 2.[I19775]).

6.11.1.3 get

Compute and fetch the transformation values from the matrix. The parameters are defined to represent, in order: translation, rotation, scale, scaleOrientation and center.

6.11.1.4 inverse

Calculate the inverse of this matrix in place.

6.11.1.5 transpose

Transpose this matrix in place.

6.11.1.6 multiply

Multiply this matrix by the passed matrix instance. Implementations shall define multiplication operations in both directions: left and right.

6.11.1.7 multiplyWithVector

Multiply this matrix and a vector together. Implementations shall define multiplication operations in both directions: left and right.