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.

6.1.2 Topics

Table 6.1 specifies the topics 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 SAI. Each request is defined by a number of characteristics. In Table 6.2 the first column defines each characteristic type and the second defines the properties of that characteristic.

Parameters shown in square brackets [] indicate optional additional values of the data type specified within the brackets may be specified or returned.

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

The getBrowser service returns a reference to an instance of an X3D browser through which other service requests may be processed.

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

The createBrowser service creates 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 (see 6.3.14 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 compositing 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 getName service returns the name of the browser. This name is implementation dependent. If this service is not supported a NULL value shall be returned.

6.3.3 getVersion

The getVersion service returns the current version of the browser application. 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 getCurrentSpeed service returns the navigation speed of the current world. 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

The getCurrentFrameRate service returns the current frame display rate of the browser. If this is not supported, the value returned is zero.

6.3.6 getSupportedProfiles

The getSupportedProfiles service returns 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

The getProfile service returns the declaration of the named profile. The value of the SAIString parameter is the name of a profile from which to fetch the declaration and shall conform exactly to the name specified in part 1 of ISO/IEC 19775-1 (see 2.[I19775-1]). It shall be an error if the a name with wrong case, bad spelling or anything other than an exact match. The browser is only required to return an SAIProfileDeclaration value if it supports the named profile. If it does not support the named profile, SAI_NOT_SUPPORTED shall be generated.

6.3.8 getSupportedComponents

The getSupportedComponent service returns a 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

The getComponent service returns the declaration of the named component. The value of the SAIComponent parameter is the name of a component and level from which to fetch the declaration 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 value if it supports the named component and the requested level. If it does not support the component at the level desired, SAI_NOT_SUPPORTED shall be generated.

6.3.10 getExecutionContext

The getExecutionContext service returns the current execution context. If used in an internal interaction, this service returns the execution context in which the containing node exists (see 4.4.3 Containing Node). When used in an external interaction, this service returns the current top-level scene.

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 in Part 1 of ISO/IEC 19775 (see 2.[I19775-1]). Depending on the place in the scene graph, the returned type may be an instance of SAIScene allowing the user to use the greater capabilities.

6.3.11 createScene

The createScene service creates 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 shall always have its specification version set to "3.0" and the encoding set to "Scripted".

6.3.12 replaceWorld

The replaceWorld service replaces the current world with the world specified by the SAIScene parameter. If another replaceWorld or loadURL (see 6.3.14 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.

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

The SAI_Browser_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).

6.3.13 importDocument

The importDocument service is 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 DOM Node as defined by 2.[W3CDOM2]. 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 (see 6.3.12 replaceWorld) service. When the conversion is made, there is no lasting connection between the DOM and the generated scene. Each request shall be a single 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 shall be generated.

6.3.14 loadURL

The loadURL service inserts the content identified by the URL(s) in the current world under control of the contents of the SAIPropertyList instance.

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

The SAI_Browser_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, 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 (see 6.3.12 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 SAI_Browser_Initialized 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

The createX3DFromString 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 7.2.4.2 Header statement in part 1 of ISO/IEC 19775 (see 2.[I19775_1]). A browser is not required to support any versions prior to ISO/IEC 19775.

If the string contains legal X3D statements but does not contain any node instances,  a valid SAIScene value shall still be returned containing no root nodes, but with the appropriate declaration identifiers. 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, the browser shall generate an SAI_NOT_SUPPORTED error.

6.3.17 createX3DFromStream

The createX3DFromStream 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 SAIScene value shall still be returned containing no root nodes, but with the appropriate declaration identifiers. For example, the string may contain EXTERNPROTO declarations but no instances of any node. If the stream identified by 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

The createX3DFromURL 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 identified by the returned SAIScene value.

6.3.19 updateControl

The updateControl species the manner in which buffered updates are processed.

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.

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

6.3.20 registerBrowserInterest

The registerBrowserInterest 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 SAIRequester 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 sent to the listener that has registered interest in these events. These event notifications shall 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 getRenderingProperties

The getRenderingProperties service is 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 multitexture 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.5 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.22 getBrowserProperties

The getBrowserProperties service is 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 existence of browser implementation-specific extensions to the defined browser class or future extensions as provided by this specification.

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

6.3.23 changeViewpoint

The changeViewpoint service changes 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.7 defines the actions specified in this part of ISO/IEC 19775.

Table 6.7 — 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 in which the external scene is resolved, and appended to the list. The inclusion of these external instances is also dependent on the browser property ListInlineViewpoints.

If the world only contains the default X3DViewpointNode instance this request has no effect in the visual output.

6.3.24 print

The print service prints a message to the browser's console. The language-specific bindings may provide overloaded variations on this service that do not take an SAIString value, but take other data types. Other variants may include the ability to automatically add linefeed/newline characters without the need to explicitly declare them in the SAIString value. 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.25 dispose

The dispose service indicates that 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_Browser_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 BeginUpdate has been called, disposing of the browser shall also call EndUpdate to release those events to the browser.

6.4 Execution context services

6.4.1 getSpecificationVersion

The getSpecificationVersion returns the version string that describes to which specification version this scene adheres. This version represents the appropriate version number as defined in part 1 of ISO/IEC 14772 (see 2.[I14772-1]), part 1 of ISO/IEC 19775 (see 2.[I19775-1]), or has value 1.0 for versions of VRML that precede the specification in part 1 of ISO/IEC 14772-1 that are supported by the implementation.

6.4.2 getEncoding

The getEncoding service returns the encoding type that was used for to produce the portion of the scene represented by the specified execution context. 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 VRML 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 (reserved for future specification)
6. BIFS: For MPEG-4 BIFS-encoded format. (see 2.[I14496-1])

6.4.3 getProfile

The getProfile service returns 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 VRML. If no profile is provided, this shall return NULL.

6.4.4 getComponents

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

6.4.5 getWorldURL

The getWorldURL service returns 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 getNode service searches for a node based on specified criteria and returns an identifier for the node.

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 namedNodeHandling request (see 6.4.9 namedNodeHandling).

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

Table 6.8 — 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 in part 1 of ISO/IEC 19775 (see 2.[I19775-1]).

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

6.4.7 createNode

The createNode service creates a new default instance of the node given by the SAIString value containing the name of an X3D node type. The availability 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

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

6.4.9 namedNodeHandling

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

The second SAIAction value 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, 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.9 defines the actions specified in this part of ISO/IEC 19775.

Table 6.9 — namedNodeHandling SAIAction values

The first SAIString value identifies 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. SAINode value is a reference to the node that may be needed 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

The getProtoDeclaration service returns the named PROTO declaration representation from this scene. This shall only be used to request PROTO declarations. A request for an EXTERNPROTO declaration shall generate SAI_INVALID_NAME.

6.4.11 protoDeclarationHandling

The protoDeclarationHandling service is a request to add, remove or change the ProtoDeclaration identified by the SAIString value.

The SAIAction parameter specifies whether 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.10 defines the actions specified in this part of ISO/IEC 19775.

Table 6.10 — protoDeclarationHandling SAIAction values

6.4.12 getExternProtoDeclaration

The getExternProtoDeclaration service returns the named EXTERNPROTO declaration representation from this scene.  This shall only be used to request an EXTERNPROTO declaration. A request for a PROTO declaration shall generate SAI_INVALID_NAME.

6.4.13 externprotoDeclarationHandling

The externprotoDeclarationHandling service is a request to add, remove or update the ExternProtoDeclaration identified by the SAIString value.

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.11 defines the actions specified in this part of ISO/IEC 19775.

Table 6.11 — externprotoDeclarationHandling SAIAction values

6.4.14 getRootNodes

The getRootNodes service returns a 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 were received by the browser.

6.4.15 getRoutes

The getRoutes service gets 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 dynamicRouteHandling service is a request to process a route according to the action specified by the SAIAction value.

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.12. The SAINode/SAIField pair parameters are considered as defining the source field and destination fields for the route request.

Table 6.12 — dynamicRouteHandling SAIAction values

Route modification requests are to fit with the general event model scheme as defined in 4.4.8 Event model in part 1 of ISO/IEC 19775 (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 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 dispose service specifies that the client has no further interest in the resource represented by this execution context. The browser may now take whatever action is necessary to reclaim any resources consumed by this execution context, now or 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 additional services provided. The Scene services implementation shall include all of the services from 6.4 Execution context services, and include the following additional services.

6.5.2 getMetadata

The getMetadata service returns an item of metadata from the scene that was specified using the META statement defined in 7.2.5.5 META statement of Part 1 of ISO/IEC 19775 (see 2.[I19775-1]). Metadata specified in the META statement is represented as an SAIString key/value pair. Each key corresponds to exactly zero or one value.

Optionally, the browser may provide a subservice to discover the valid keys for this scene as part of this service.

Metadata defined by metadata nodes as defined in Part 1 of ISO/IEC 19775 can be manipulated using 6.6 Node services.

6.5.3 setMetadata

The setMetadata service inserts an item of metadata in the scene in the form of a META statement as defined in 7.2.5.5 META statement of Part 1 of ISO/IEC 19775 (see 2.[I19775-1]). Metadata is represented as a SAIString key/value pair. 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, the META statement associated with that key is removed from the scene.

Metadata defined by metadata nodes as defined in Part 1 of ISO/IEC 19775 can be manipulated using 6.6 Node services.

6.5.4 namedNodeHandling

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

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

The second SAIAction parameter value 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 value specifies 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. The SAINode value is a reference to the node that may be needed for verification of an 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 Classic VRML 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

The rootNodeHandling service is a 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, 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.13 defines the actions specified in this part of ISO/IEC 19775.

Table 6.13 — 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 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

The getTypeName service returns the name of the type of the referenced node. The type name is the name as specified in ISO/IEC 19775-1 where the node type is defined (see Node index in part 1 of ISO/IEC 19775 (2.[I19775-1]) for easy access to a node definition). If the node represents a PROTO node instance, the type name returned is the name of the PROTO declaration.

6.6.3 getType

The getType service returns the type indicator for the referenced node. 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

The getField service returns a field identifier so that operations can be performed on the node properties. If the field requested is an inputOutput field, 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

The getFieldDefinitions service returns a list of all the field definitions of the referenced node. The definitions provide a limited form of the SAIField 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 SAIField values as generic responses for every instance of this node rather than for a specific instance.

6.6.6 dispose

The dispose node service indicates that the client has no further interest in the resource represented by this node. The browser may take whatever action is necessary to reclaim any resources consumed by this node, now or 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 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 if no other applications or scene graph 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 from which a field was retrieved 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 disposal of the field, a disposed error shall 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 getAccessType service returns the access type for the specified field of the referenced node.

6.7.3 getType

The getType field service returns the type for the specified field of the referenced node.

6.7.4 getName

If supported by the implementation, the getName field service returns 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 shall return "set_children", but if a different request was for children on the same node, "children" shall be returned.

6.7.5 getValue

The getValue field service returns the value represented by the specified field as it exists in the world. This represents 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 BeginUpdate, 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 return a single value from multi-valued arrays.

6.7.6 setValue

The setValue field service sets the value of the specified field. Set requests shall obey the requirements as specified for buffered events services.

The value of the field may be an SAINode value 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 part 1 of ISO/IEC 19775 (see 2.[I19775-1]), shall result in the appearance field being cleared and set to the default value of NULL.

If the SAINode value 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 multi-value arrays shall also include the ability to append and remove items from the existing field.

6.7.7 registerFieldInterest

The registerFieldInterest 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.14 defines the actions specified in this part of ISO/IEC 19775.

Table 6.14 — registerFieldInterest SAIAction values

The parameter of type SAIRequester can 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.

Which capabilities are permitted to be listened to are implementation dependent. For example, some implementations may permit listening to inputOnly values and outputOnly values while others will only permit listening to outputOnly values.

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 a 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, an SAI_NODE_IN_USE error shall be generated.

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 dispose field service indicates that the client has no further interest in the resource represented by this field. The browser may take whatever action is necessary to reclaim any resources consumed by this field, now or 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

The getSourceNode service returns the source node of the specified route.

6.8.2 getSourceField

The getSourceField service returns the name of the source field of the specified route.

6.8.3 getDestinationNode

The getDestinationNode service returns the destination node of the specified route.

6.8.4 getDestinationField

The getDestinationField service returns the name of the destination field of the specified route.

6.8.5 dispose

The dispose route service indicates that the client has no further interest in the resource represented by this route. The browser may take whatever action is necessary to reclaim any resources consumed by this route, now or 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

The isExternproto service checks 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

The createInstance service creates a new instance from the declaration of either a PROTO or EXTERNPROTO. An EXTERNPROTO instance may fail with SAI_INVALID_NODE if the definition has not yet been loaded.

6.9.3 getFieldDefinitions

The getFieldDefinitions service returns a list of all the field definitions of the PROTO or EXTERNPROTO declaration. The definitions provide a limited form of the SAIField value 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

The checkLoadState service checks 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 the SAIProtoDeclaration value represents an EXTERNPROTO, the requestImmediateLoad service requests that the browser start immediate loading of that definition. If the definition is already loaded or the load is already in progress, this request shall be silently ignored.

6.10 Configuration services

6.10.1 Introduction

The services specified here allow an application to identify the configuration of the current world.

An SAIComponentDeclaration value specifies a component declaration containing the information specified by the COMPONENT statement as defined by 7.2.5.4 COMPONENT statement in Part 1 of ISO/IEC 19775 (see 2.[I19775-1]). The services defined are the minimum required. An implementation may provide additional informational-only services.

An SAIProfileDeclaration value specifies a profile declaration containing the information specified by the PROFILE statement as defined by 7.2.5.3 PROFILE statement in Part 1 of ISO/IEC 19775 (see 2.[I19775-1]) and by the profile definition contained in the annexes of Part 1 of ISO/IEC 19775. The services defined are the minimum required. An implementation may provide additional informational-only services.

6.10.2 getComponentName

The getComponentName service returns the formal name of the specified component.

6.10.3 getComponentLevel

The getComponentLevel service returns the support level specified for the component. When the SAIComponentDeclaration comes from the browser services, it shall represent the maximum level supported by the browser. When it comes from the scene services, the level represents the requested support level for that scene.

6.10.4 getProfileName

The getProfileName service returns the formal name of the specified profile.

6.10.5 getProfileComponents

The getProfileComponents service returns a list of SAIComponentDeclaration instances specifying the allowed support for each component of which the profile is comprised.

6.10.6 getProviderName

The getProviderName service is an information-only service that returns an SAIString value containing the name of the person or company that implemented this profile.

6.11 Services provided by script content

6.11.1 Introduction

When an author provides the executable content of a script, certain conventions shall be satisfied. This allows the browser to communicate status information unambiguously  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 contrast to the other services specifications, the browser shall make these service requests of the user's code, and therefore the user code shall 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.

6.11.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 (e.g., scripts created in the same language in which the browser itself was written). Apart from the instantiation process, which is language dependent, the browser shall not require any services.

6.11.3 Setup phase

6.11.3.1 setBrowser

The setBrowser service passes to the script implementation code the the SAIBrowserRef value 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 may 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 4.4.8 Event model in part 1 of ISO/IEC 19775 (see 2.[I19775-1]) although that is time when the Browser implementers are encouraged to request this service.

6.11.3.2 setFields

The setFields script service passes in the list of fields declared in this script node instance. It also passes in the external view of the containing script node so that the user may add and remove routes to the script directly. The SAIField instances represent all of the fields of a script, including the pre-defined fields. (See 4.8.3.4 Updating the scene graph for details on the field access restrictions). This request shall be performed between the setBrowser and initialize service requests.

6.11.3.3 initialize

The initialize script service provides 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, the user code may access script field values and change its state.

6.11.4 Realized phase

6.11.4.1 prepareEvents

The prepareEvents service provides 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 in part 1 of ISO/IEC 19775 (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. If the containing node provides directOutputs, these shall be passed immediately to the underlying nodes.

6.11.4.2 eventsProcessed

The eventsProcessed service provides notification that the current event cascade processing has finished and that the containing node is now allowed to make updates to the scene graph. This is 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.11.5 Disposed phase

6.11.5.1 shutdown

The shutdown service provides 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.12 Matrix services

6.12.1 Introduction

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 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 access matrix elements. 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.12.2 set

The set matrix service sets the matrix to the new value calculated from the parameters. The parameters are defined to represent, in order: translation, rotation, and scale. If a value for a parameter is not specified, 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 in part 1 of ISO/IEC 19775 (see 2.[I19775]).

6.12.3 get

The get service computes and returns the transformation values from the matrix. The parameters are defined to represent, in order: translation, rotation, scale, scaleOrientation and center.

6.12.4 inverse

The inverse service calculates the inverse of this matrix in place.

6.12.5 transpose

The transpose service transposes this matrix in place.

6.12.6 multiply

The multiply service multiplies the first matrix by the second matrix instance placing the result in the first matrix. Implementations shall define multiplication operations in both directions: left and right.

6.12.7 multiplyWithVector

The multiplyWithVector service multiplies this matrix and a vector together. Implementations shall define multiplication operations in both directions: left and right.