Extensible 3D (X3D)
Part 1: Architecture and base components
9 Networking component
9.1 IntroductionThe name of this component is "Networking". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).
This clause describes the Networking component of this part of ISO/IEC 19775. This component defines the node types and other features used to access file-based and streaming resources on the World Wide Web. Table 9.1 lists the major topics in this clause.
9.2 ConceptsA URL (Uniform Resource Locator) , described in [RFC1738], is a form of Universal Resource Identifier (URI) described in [URI] [RFC8089] that specifies a file located on a particular server and accessed through a specified protocol (such as file:, http: or https:). In this part of ISO/IEC 19775, the upper-case term URL refers to a Uniform Resource Locator, while the italicized lower-case version url refers to a field which may contain URLs or in-line encoded data.
Higher levels of this component extend the URL support of a browser to additional forms of URI, such as supporting Uniform Resource Name (URN) definition, which are another form of URI. A URN allows an abstract resolution mechanism to be invoked to locate a resource (see [RFC2141] [RFC8141]). This allows a resource to be located on the local machine or a platform dependent resource to be located using the URN along with platform-specific identifiers.
For levels that support URNs, the url field shall also support the Web3D Consortium URN Namespace (see [RFC3541]) and also support the Universal Media Library that may be accessed using that namespace. A URN allows an abstract resolution mechanism to be invoked to locate a resource (see [RFC2141] [RFC8141]). This approach allows a resource to located on the local machine or a platform dependent resource to be located using the URN along with platform specific identifiers. A component extension can extend the URL support of a browser by supporting other URN naming schemes. More information on the url field may be found in 9.3.2 X3DUrlObject. More general information on URLs is described in [RFC1738].
Relative URLs are handled as described in [IETF RFC1808] [URI]. All name scopes (see 4.4.7 Run-time name scope) maintain a base URI which is used for all relative URLs within that name scope. Whenever a node with a relative URL is defined, that node may only reference assets available within its name scope. It has no advance knowledge of how it may or may not be included by an Inline node or referenced by an external prototype instantiation. The base document for EXTERNPROTO statements or nodes that contain a URL field is:
Components can add scripting support to an X3D browser. An example of this is the Scripting component which introduces a Script node. The Script node's url field may support custom protocols for the various scripting languages. For example, a script url prefixed with ecmascript: (or the deprecated javascript:) shall contain ECMAScript source, with line terminators allowed in the string. The details of each language protocol are defined in the parts of ISO/IEC 19777, which define the bindings for each language. Browsers that conform to a profile that supports scripting are not required to support both the Java and ECMAScript scripting languages. Browsers shall adhere to the protocol defined in the corresponding part of ISO/IEC 19777 for any scripting language that is supported.
EXAMPLE The following illustrates the use of mixing custom protocols and standard protocols in a single url field (order of precedence determines priority):
#X3D V3.0 utf8
Script {
url [ "ecmascript: ...", # custom in-line ECMAScript code
"https://bar.com/foo.js", # ECMAScript file reference
"https://bar.com/foo.class" ] # Java platform bytecode file reference
}
The "..." represents in-line ECMAScript source code.
X3D supports configuring the browser via a set of options. These options are values passed to the browser at start-up time that control its run-time operation. Browser options may be set as HTML PARAM values within an EMBED or OBJECT tag if the X3D browser is running as an embedded control within a World Wide Web browser, or through an application-specific mechanism such as a configuration file or system registry entry if the browser is running within some other containing application.
Support for browser options is not required but is strongly recommended. Some browsers may not support all available options, due to limitations in the underlying rendering system.
Table 9.2 lists the available X3D Browser options.
| Name | Description | Type/valid range | Default |
|---|---|---|---|
| Antialiased | Render using hardware antialiasing if available | Boolean | False |
| Dashboard | Display browser navigation user interface | Boolean | Specified by bound NavigationInfo in content |
| EnableInlineViewpoints | Viewpoints from Inline nodes are included in list of viewpoints if made available by the Inline node. | Boolean | True |
| MotionBlur | Render animations with motion blur | Boolean | False |
| PrimitiveQuality | Render quality (tesselation level) for Box, Cone, Cylinder, Sphere | Low, Medium, High | Medium |
| QualityWhenMoving | Render quality while camera is moving | Low, Medium, High, Same (as while stationary) | Same |
| Shading | Specify shading mode for all objects | Wireframe, Flat, Gouraud, Phong | Phong Gouraud |
| SplashScreen | Display browser splash screen on startup | Boolean | Implementation-dependent |
| TextureQuality | Quality of texture map display | Low, Medium, High | Medium |
The IMPORT statement is used within an X3D file to specify nodes, which are defined within Inline files or programmatically created content, that are to be brought into the namespace of the containing file for the purposes of event routing. Once a node is imported, events may be sent to its fields via ROUTEs, or routed from any fields of the node which have output events. The IMPORT statement has the following components:
The IMPORT statement has the following semantics:
The following example illustrates the use of the IMPORT statement (Classic VRML encoding syntax):
DEF I1 Inline {
url "someurl.x3d"
}
. . .
IMPORT I1.rootTransform AS I1Root
DEF PI PositionInterpolator { ... }
ROUTE PI.value_changed TO I1Root.set_translation
In the above example, rootTransform is defined as a Transform node in the file someurl.x3d and exported via an EXPORT statement (see 4.4.6.3 EXPORT semantics). The optional AS keyword defines an alias for rootTransform so that within the containing scene the node is referenced using the DEF name I1Root.
The EXPORT statement is used within an X3D file to specify nodes that may be imported into other scenes when Inlining that file. Only named nodes exported with an EXPORT statement are eligible to be imported into another file. The EXPORT statement has the following components:
The EXPORT statement has the following semantics:
The following example illustrates the use of the EXPORT statement (Classic VRML encoding):
DEF T1 Transform {
...
}
. . .
EXPORT T1 AS rootTransform
In the above example, node T1 is exported for use by other X3D scenes. The optional AS keyword defines the exported name of T1 as rootTransform (i.e., other scenes may import the node only using the name rootTransform).
9.3 Abstract typesX3DNetworkSensorNode : X3DSensorNode {
SFBool [in,out] enabled TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFBool [out] isActive
}
This abstract node type is the basis for all sensors that generate events based on network activity.
X3DUrlObject {
SFTime [in,out] autoRefresh 0.0 [0,∞)
SFTime [in,out] autoRefreshTimeLimit 3600.0 [0,∞)
SFString [in,out] description ""
SFBool [in,out] load TRUE
SFTime [in,out] refresh 0.0 [0,∞)
MFString [in,out] url [] [URI]
}
This abstract interface is inherited by all nodes that contain data located on the World Wide Web, such as AudioClip, ImageTexture and Inline.
The autoRefresh field defines the interval in seconds that are necessary before an automatic reload of the current url asset is performed. If the preceding file loading fails or the load field is FALSE, no automatic refresh is performed. If performed, a refresh attempts to reload the currently loaded entry of the url list. If an automatic refresh fails to reload the currently loaded url entry, the browser retries the other entries in the url list.
NOTE Automatic refresh is different than query and response timeouts performed by a networking library while sequentially attempting to retrieve addressed content from a url list.
The autoRefreshTimeLimit field defines the maximum duration that automatic refresh activity can occur.
WARNING Automatically reloading content can have security implications and needs to be considered carefully.
The description field specifies a textual description for the url asset. This information may be used by browser-specific user interfaces that wish to present users with more detailed information about the linked content.
The load field allows deferring when the referenced content is read and displayed, in profiles that support that field. In profiles that do not support the load field, url content is loaded immediately.
All url fields can hold multiple string values. The strings in these fields indicate multiple locations to search for data in the order listed. If the browser cannot locate or interpret the data specified by the first location, it shall try the second and subsequent locations in order until a location containing interpretable data is encountered. X3D browsers only have to interpret a single string. If no interpretable locations are found, the node type defines the resultant default behaviour.
EachIf loading an X3D model, each specified URL shall refer to a valid X3D file that contains a list of children nodes, prototypes and routes at the top level as described in 10.2.1 Grouping and children node types. The results are undefined if the URL refers to a file that is not an X3D file, or if the X3D file contains an invalid scene. a supported file type, or if the file contains invalid content.
It shall be an error to specify an X3D file in the URL field that has a set of component definitions that is not a subset of the components of the containing world. In addition, the components shall not be of a higher support level than those used by the containing world, either implicitly or through the PROFILE declaration or additional COMPONENT statements. When the world indicated by the url field requests capabilities greater than its parent, the following actions shall occur:
For more information on URLs, see 9.2.1 URLs, URNs and URIs.
9.4 Node referenceAnchor : X3DGroupingNode,X3DUrlObject {
MFNode [in] addChildren
MFNode [in] removeChildren
SFTime [in,out] autoRefresh 0.0 [0,∞)
SFTime [in,out] autoRefreshTimeLimit 3600.0 [0,∞)
SFBool [in out] bboxDisplay FALSE
MFNode [in,out] children [] [X3DChildNode]
SFString [in,out] description ""
SFBool [in,out] load TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
MFString [in,out] parameter []
SFTime [in,out] refresh 0.0 [0,∞)
MFString [in,out] url [] [URI]
SFBool [in out] visible TRUE
SFVec3f [] bboxCenter 0 0 0 (-∞,∞)
SFVec3f [] bboxSize -1 -1 -1 [0,∞) or −1 −1 −1
}
The Anchor grouping node retrieves the content of a URL when the user activates (such as, clicks) some geometry contained within the Anchor node's children. If the URL points to a valid X3D file, that world replaces the world of which the Anchor node is a part (except when the parameter field, described below, alters this behaviour). If non-X3D data is retrieved, the browser shall determine how to handle that data; typically, it will be passed to an appropriate non-X3D browser.
Exactly how a user activates geometry contained by the Anchor node depends on the pointing device and is determined by the X3D browser. Typically, clicking with the pointing device will result in the new scene replacing the current scene. An Anchor node with an empty url does nothing when its children are chosen. A description of how multiple Anchors and pointing-device sensors are resolved on activation is contained in 20.2 Concepts.
More details on the children, addChildren, and removeChildren fields can be found in 10.2 Concepts.
The description field in the Anchor node specifies a textual description of the Anchor node. This information may be used by browser-specific user interfaces that wish to present users with more detailed information about the Anchor.
The autoRefresh and load fields have no effect.
The parameter field may be used to supply any additional information to be interpreted by the browser. Each string shall consist of "keyword=value" pairs. For example, some browsers allow the specification of a "target" for a link to display a link in another part of an HTML document. The parameter field is then:
Anchor {
parameter [ "target=name_of_frame" ];
...
}
An Anchor node may be used to bind the initial Viewpoint node in a world by specifying a URL ending with "#ViewpointName" where "ViewpointName" is the DEF name of a viewpoint defined in the X3D file.
EXAMPLE
Anchor {
url "https://www.school.edu/X3D/someScene.wrl#OverView";
children Shape { geometry Box {} };
}
specifies an anchor that loads the X3D file "someScene.wrl" and binds the initial user view to the Viewpoint node named "OverView" when the Anchor node's geometry (Box) is activated. If the named Viewpoint node is not found in the X3D file, the X3D file is loaded using the default Viewpoint node binding stack rules (see 23.3.5 Viewpoint).
If the url field is specified in the form "#ViewpointName" (i.e., no file name), the Viewpoint node with the given name ("ViewpointName") in the Anchor's run-time name scope(s) shall be bound (set_bind TRUE). The results are undefined if there are multiple nodes derived from X3DViewpointNode with the same name in the Anchor's run-time name scope(s). The results are undefined if the Anchor node is not part of any run-time name scope or is part of more than one run-time name scope. See 4.4.7 Run-time name scope for a description of run-time name scopes. See 23.3.5 Viewpoint, for the X3DViewpointNode transition rules that specify how browsers shall interpret the transition from the old node derived from X3DViewpointNode to the new one. For example:
Anchor {
url "#Doorway";
children Shape { geometry Sphere {} };
}
binds the viewer to the viewpoint defined by the "Doorway" viewpoint in the current world when the sphere is activated. In this case, if the node derived from X3DViewpointNode is not found, no action occurs on activation.
More details on the url field are contained in 9.2.1 URLs, URNs and URIs.
NOTE Viewpoint functionality is in addition to the X3DUrlObject interface characteristics.
The bboxCenter and bboxSize fields specify a bounding box that encloses the Anchor's children. This is a hint that may be used for optimization purposes. The results are undefined if the specified bounding box is smaller than the actual bounding box of the children at any time. The default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and if needed shall be calculated by the browser. More details on the bboxCenter and bboxSize fields can be found in 10.2.2 Bounding boxes.
Inline : X3DChildNode, X3DBoundedObject, X3DUrlObject {
SFTime [in,out] autoRefresh 0.0 [0,∞)
SFTime [in,out] autoRefreshTimeLimit 3600.0 [0,∞)
SFBool [in out] bboxDisplay FALSE
SFString [in,out] description ""
SFBool [in,out] global FALSE
SFBool [in,out] load TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFTime [in,out] refresh 0.0 [0,∞)
MFString [in,out] url [] [URI]
SFBool [in out] visible TRUE
SFVec3f [] bboxCenter 0 0 0 (-∞,∞)
SFVec3f [] bboxSize -1 -1 -1 [0,∞) or −1 −1 −1
}
The Inline node embeds an X3D scene stored at a location on the World Wide Web into the current scene.
Exactly when the Inline scene is read and displayed is defined by the value of the load field The load field controls when the Inline scene is read and displayed, in profiles that support that field. In profiles that do not support the load field, exactly when the scene is read and displayed is not defined (such as, reading the scene may be delayed until the Inline node's bounding box is visible available to the viewer).
The run-time system can support any number of 3D model resource types as long as those follow the abstract model definition (see 2.[RFC2077]), provide a registered content type (e.g. model/x3d-xml, model/gltf-bin, model/stl, etc.), and can be determined with some form of content negotiation (see 2.[RFC2616]). The run-time system must support at least one X3D type (e.g. model/x3d-xml) but can also support and negotiate any number of X3D encodings and (optionally) non-X3D representation formats. Support for loading glTF assets (see 2.[GLTF]) also requires support for Shape component level 2 and Lighting component level 4.
Once the Inline scene is loaded, its children are added to the current scene and are treated as children of the Inline for rendering and interaction; however the children are not exposed to the current scene for routing and DEF name access unless their names have been explicitly imported into the scene using the IMPORT statement (see 4.4.6.2 IMPORT semantics).
NOTE When Inline is used to load a child scene, processing of the Inline content is as specified in the respective PROFILE, COMPONENT, UNIT, IMPORT, and EXPORT statements.
The visible field specifies whether or not the content within a node is visually displayed. The value of this field has no effect on animation behaviors, collision behaviors, event passing, or other non-visual characteristics.
The global field controls whether lights contained in the Inline scene are allowed to have external lighting effects or not, according to 17.2.1.2 Scoping of lights.
If the load field is set to TRUE (the default field value), the X3D file specified by the url field is loaded immediately. If the load field is set to FALSE, no action is taken. It is possible to explicitly load the URL at a later time by sending a TRUE event to the load field (such as, the result of a ProximitySensor or other sensor firing an event). If a FALSE event is sent to the load field of a previously loaded Inline, the contents of the Inline will be unloaded from the scene graph.
An event sent to url can be used to change the scene that is inlined by the Inline node. If this value is set after the Inline is already loaded, its contents will be unloaded and the scene to which the new URL points will be loaded.
The user is able to specify a bounding box for the Inline node using the bboxCenter and bboxSize fields. This is a hint to the browser and could may be used for optimization purposes such as culling.
Note that Shape nodes defined as part of models loaded from prior versions of X3D have the castShadow field set to TRUE when loaded in the current scene.
Security precaution: it is an error for a model to Inline itself, directly or indirectly, in order to avoid nonterminating recursion loops. X3D players SHALL NOT honor self-referential loading of model loops in order to avoid security vulnerabilities.
LoadSensor : X3DNetworkSensorNode {
SFBool [in,out] enabled TRUE
SFNode [in,out] metadata NULL [X3DMetadataObject]
SFTime [in,out] timeOut 0
MFNode [in,out] watchList [] [X3DUrlObject]
MFNode [in,out] children [] [X3DUrlObject]
SFBool [out] isActive
SFBool [out] isLoaded
SFTime [out] loadTime
SFFloat [out] progress
}
The LoadSensor monitors the progress and success of downloading URL elements over a network. Only nodes that contain a valid URL field (i.e., descendants of X3DUrlObject), may be specified in the watchListchildren field. Multiple nodes may be watched with a single LoadSensor.
The timeOut field specifies the maximum time for which the LoadSensor will monitor loading, starting from when the sensor becomes active. A value of 0 for the timeOut field indicates an indefinite time out period; i.e., the LoadSensor will wait until loading has completed either with success or failure.
The watchListchildren field contains one or more URL objects to monitor. Only nodes that contain a valid URL field (i.e., descendants of X3DUrlObject), may be specified as elements of watchListchildren. If multiple values are specified for this field, output events are generated only when all of the children have loaded or at least one has failed. If individual load status information is desired for different nodes, multiple LoadSensor nodes may be used, each with a single watchListchildren element.
NOTE the original name for the LoadSensor children field in X3D version 3 is watchList.
If an Anchor node is part of a watchListchildren field value, isLoaded reports success for this node as follows. There are three cases that Anchor node can handle:
When binding to a viewpoint (item a above), the asset is loaded when the Viewpoint is bound. When loading a replacement world or asset (item b above), no action is taken because the current world is lost. When launching a separate window or asset (item c above), the load is considered complete when the operating system or web browser acknowledges the load request.
The isActive field generates events when loading of the LoadSensor's watchListchildren elements begins and ends. An isActive TRUE event is generated when the first element begins loading. An isActive FALSE event is generated when loading has completed, either with a successful load of all objects or a failed load of one of the objects, or when the timeout period is reached as specified in the timeout field.
The isLoaded field generates events when loading of the LoadSensor's watchListchildren has completed. An isLoaded TRUE event is generated when all of the elements have been loaded. An isLoaded FALSE event is generated when one or more of the elements has failed to load, or when the timeout period is reached as specified in the timeout field. If all elements in the watchListchildren are already loaded by the time the LoadSensor is processed, the LoadSensor shall generate an isLoaded event with value TRUE and a progress event with value 1 at the next event cascade.
The loadTime event is generated when loading of the LoadSensor's watchListchildren has successfully completed. If loading fails or the timeout period is reached, a loadTime event is not generated.
The progress field generates events as loading progresses. The value of progress is a floating-point number between 0 and 1 inclusive. A value of 1 indicates complete loading of all watchListchildren elements. The exact meaning of all other values (i.e., whether these indicate a percentage of total bytes, a percentage of total number of files, or some other measurement) and the frequency with which progress events are generated are browser-dependent. Regardless, the browser shall in all cases guarantee that a progress value of 1 is generated upon successful load of all URL objects.
The following example defines a LoadSensor that monitors the progress of loading two different ImageTexture nodes:
Shape {
appearance Appearance {
material Material {
texture DEF TEX1 ImageTexture { url "Amypic.png" }
}
}
geometry Sphere {}
}
Shape {
appearance Appearance {
material Material {
texture DEF TEX2 ImageTexture { url "Bmypic.png" }
}
}
geometry Sphere {}
}
DEF LS LoadSensor {
watchList [ USE TEX1, USE TEX2 ]
}
ROUTE LS.loadTime TO MYSCRIPT.loadTime
The events this would generate are:
For watchListchildren elements that allow dynamic reloading of their contents, any reload of that element (EXAMPLE changing the url field of an ImageTexture or setting the load field of an Inline), resets the LoadSensor so that it monitors those elements based on the new values and resets its timeout period if one was specified.
For streamed media types, the first frame of data available means successful load of the URL object (i.e., the browser can render one frame of a movie or start playing an audio file).
9.5 Support levelsThe Networking component provides three levels of support as specified in Table 9.3.
Table 9.3 — Networking component support levels
| Level | Prerequisites | Nodes/Features | Support |
|---|---|---|---|
| 1 | Core 1 | ||
| X3DUrlObject (Abstract) | n/a | ||
| X3DNetworkSensorNode (Abstract) | n/a | ||
| Protocols | file: protocol only. | ||
| Name resolution | Fully-specified URLs. | ||
| 2 | Core 1 Grouping 1 |
||
| Level 1 supported nodes | Support as specified for Level 1. | ||
| Anchor | All fields fully supported. | ||
| Inline | All fields except load which is optionally supported. | ||
| Protocols | file:, and http:, and https: protocols are required. | ||
| Name resolution | Relative URLs; and URNs. | ||
| 3 | Core 1 Grouping 1 |
||
| Level 2 supported nodes | Support as specified for Level 2. | ||
| Inline | All fields fully supported. | ||
| LoadSensor | All fields fully supported. | ||
| Statements: IMPORT EXPORT |
Full support. | ||
| Browser options | Implementation-dependent. | ||
| 4 | Core 1 Grouping 1 |
||
| Level 3 supported nodes | Support as specified for Level 3. | ||
| Protocols | https: protocol is required. | ||
| Communication security | HTTP and HTTPS username/password is required. | ||
| Model support |
Support for glTF models in Inline nodes, in .gltf (model/gltf+json) and .glb (model/gltf-binary) formats. Requires support for Shape component level 2 and Lighting component level 3. Minimum required glTF support:
|