Extensible 3D (X3D)
Part 2: Scene access interface (SAI)
Extensible 3D (X3D)
Part 2: Scene access interface (SAI)
This annex provides a detailed description of how an X3D compliant application may provide support for backwards compatibility for scripting code originally designed and implemented for ISO/IEC 14772-1 Virtual Reality Modeling Language (VRML) Functional specification and UTF-8 encoding (see [2.[I14772-1]). It is provided for backwards-compatibility purposes only and shall not be required for any browser to implement if they do not conform to part 1 of ISO/IEC 14772.
The VRML event and scripting model had a number of flaws and incompatibilities even between languages. It is strongly recommended that this annex not be implemented by browsers that do not claim to support VRML in addition to X3D.
Table A.1 lists the topics for this annex.
|
|
This annex specifies the requirements for browsers that wish to conform to this specification and also support the ability to run scripts written for the programmatic interfaces and event model semantics defined in part 1 of ISO/IEC 14772 (see 2.[I14772-1]), within an X3D environment. That is, the URL in the Script node specified in 29.4.1 Script in part 1 of ISO/IEC 19775 (see 2.[I19775-1]) defines content that uses one of the interfaces defined in this part of ISO/IEC 19775.
A browser shall not be conformant to this specification if it only supports scripting interface defined in part 1 of ISO/IEC 14772 (see 2.[I14772-1]). A conformant browser to this Annex shall also support the full requirements of this part of ISO/IEC 19775 including all required language bindings.
[ Basic drift here is we are not going to allow a browser to call itself conformant to the X3D spec if it only supports the VRML97 APIs and not the new APIs defined for the SAI. They must support the SAI first before they can claim they are backwards compatible too. This is to stop browsers only partially supporting the X3D spec by just completely ignoring the SAI. It would be a very bad situation if this were to happen. ]
The main difference between VRML and this specification is the definition of the event model. The VRML specification left many decisions up to the browser implementer and therefore a lot of content was incompatible. The major issue was dealing with the way scene graph changes were propagated when the user code wrote to the field. In the Java language annex values would need to be delivered immediately, yet the ECMAScript language annex said they are to be deferred until the user code has exited execution. Such incompatibilities mean supporting direct backwards compatibility is an optional-only feature.
Determination of the supported script capabilities shall follow the rules specified in 9 Networking Component in part 1 of ISO/IEC 19775 (see 2.[I19775-1]). The browser shall attempt to load the URIs in the required order, determining whether an individual script file is supported. Rejection of unsupported script types shall be based on the rules defined in the annexes defined in this Part. A browser shall not preferentially support one specification over another beyond the preference order defined by the script node definition. For example, if the user content defines a VRML97 conformant script code in the url field before a X3D conformant script code, and the browser implementation supports backwards compatibility in a language as defined in this Annex, then the VRML97 script shall be executed.
When user content defines internal interaction code that includes VRML-conformant scripts and the browser implementation does not support backwards compatibility, or does not support backwards compatibility in that language, the browser shall ignore that script and move to the next item in the url listings. This is the same behaviour as not being able to locate a file or the code is not in a language supported by the browser.
The VRML specification does not permit the use of read and write fields (i.e., exposedFields). The use of such fields is permitted in this specification. It is possible, though a highly discouraged practice, to define a scripting node with an exposedField and define the user code conformant to part 1 of ISO/IEC 14772.
In this situation, the browser shall treat the exposedField as a separate set of eventIn, eventOut and field objects. When the exposedField is written from the event model, the user code shall be notified like a normal eventIn notification. After this point, the rules for reading and writing the value of the exposedField semantics defined in 4.8.3.8 inputOutput fields and the containing node shall be followed.
If a browser intends to support VRML backwards compatibility for the ECMAScript language in the script node, it shall do so in conformance with Annex C ECMAScript language binding in part 1 of ISO/IEC 14772 (see 2.[I14772-1]).
A browser shall determine which version of the specification is supported through the use of the protocol definition or MIME type given with the external file. No other indicators shall be used.
Browsers supporting the ECMAScript backwards compatibility shall support the use of inlined script nodes through the use of the customize protocol definition javascript. The support specified in 7 Conformance and minimum support requirements in part 1 of ISO/IEC 14772 (see 2.[I14772-1]) is required in addition to the other required protocols for the ECMAScript specification as specified in Annex A ECMAScript language binding in Part 1 of ISO/IEC 14772 (see 2.[I14772-1]). An example of the inlined script definition is:
Script {
url "javascript: function foo() { ... }"
}
The url field may contain multiple URL's referencing either a remote file or
in-line code as shown in the following example:
Script {
url [
"http://foo.com/myScript.js",
"javascript: function foo( ) { ... }"
]
}
The use of the javascript protocol shall require the browser to support the objects and semantics defined in the VRML97 specification. It shall be an error for a browser that conforms to this specification to support the javascript protocol with script content that uses Objects defined in Annex A of this specification.
The use of the ecmascript: protocol shall indicate the script conforms to Annex A of this specification. A browser shall not provide VRML97 defined objects to a script that uses the ecmascript: protocol.
The MIME type for VRML ECMAScript source code is defined as follows:
application/javascript
For backwards compatibility with old web servers, it is recommended browsers also support the following mime type:
application/x-javascript
The use of the application/ecmascript or
application/x-ecmascript MIME types shall indicate the script
conforms to Annex A of this specification. A browser shall not provide VRML-defined
objects to a script that uses these MIME types.
If a browser intends to support VRML97 backwards compatibility for the Java language in the script node, they shall do so in conformance with Annex B Java platform scripting reference in part 1 of ISO/IEC 14772 (see 2.[I14772-1]).
As it is impossible to pre-determine which set of classes and interfaces a Java
class file implements through the use of the URL protocol or MIME type, a browser
shall determine which version of the specification is supported
by examining the base class or interfaces implemented by the user code.
Determination of this may be made through the language introspection capabilities
or using the instanceof operator.
A Java script that claims to support part 1 of ISO/IEC 14772 (see
2.[I14772-1]) shall extend the base
class vrml.node.Script. If a script class file extends the
VRML97 base class and implements the
org.web3d.x3d.sai.X3DScriptImplementation interface then the browser
shall use the X3D SAI semantics and execution and is not required to support
part 1 of ISO/IEC 14772 or objects that conform to part 1 of ISO/IEC 14772. It is recommended that a browser issue a warning
when it detects such a situation.