9.1 Introduction

9.1.1 Name

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

9.1.2 Overview

This clause describes the Networking component of this document. 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 Concepts

9.2.1 URLs, URNs and URIs

A URL (Uniform Resource Locator) 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 document, 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 X3D 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 [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 [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 X3D 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].

9.2.2 Relative URLs

Relative URLs are handled as described in [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:

1. The X3D file in which an EXTERNPROTO is declared, namely the value of the externprotoURL field specified in 7.2.5.9 EXTERNPROTO statement.
2. The X3D file in which the parent PROTO is declared, if the statement is inside the body of a prototype declaration, namely the value of the protoDefinition field specified in 7.2.5.8 PROTO statement.
3. The X3D file in which a Script is defined.
4. Otherwise, the X3D file from which the statement is read.

9.2.3 Scripting language protocols

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. X3D browsers that conform to a profile that supports scripting are not required to support both the Java and ECMAScript scripting languages. X3D 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.

9.2.4 X3D browser options

X3D supports configuring the X3D browser via a set of options. These options are values passed to the X3D 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 X3D browser is running within some other containing application.

Support for X3D browser options is not required but is strongly recommended. Some X3D browsers may not support all available options, due to limitations in the underlying rendering system.

Table 9.2 lists the available X3D browser options.

9.2.5 IMPORT statement

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.

IMPORT statements may appear anywhere in the file and have the following form:

IMPORT <InlineNodeName> .<ExportedNameFromInlinedFile> [ AS <NewLocalNodeName> ]

The IMPORT statement has the following components:

1. The name of the Inline node that contains the node to be imported
2. The name of the node to import
3. An optional name that is used as an alias for the imported node within the run-time name scope, to help prevent name clashes within the parent scene containing the IMPORT statement.

The IMPORT statement has the following semantics:

4. Once imported, events may be routed to or from the imported node in exactly the same manner as any node defined with DEF.
5. Nodes imported into an X3D scene using the IMPORT statement may not be instanced via the USE statement.
6. Only nodes that are exported from within the Inline via an EXPORT statement may be imported using a corresponding IMPORT statement.
7. The IMPORT statement can appear wherever a ROUTE statement is allowed, and shall follow the Inline node to which it refers.

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. All defined alias AS names shall also meet appropriate uniqueness requirements in the local DEF namespace of the parent scene.

9.2.6 EXPORT statement

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.

EXPORT statements may appear anywhere in the file and have the following form:

EXPORT <NodeName> [ AS <ExportedNodeName> ]

The EXPORT statement has the following components:

1. The DEF name of the node to be exported
2. An optional name that is used as an alias for the exported node when importing it into other files

The EXPORT statement has the following semantics:

3. Once imported into a containing scene, events may be routed to or from an exported node in exactly the same manner as any node defined with DEF.
4. Exported nodes imported into a containing scene may not be instanced via the USE statement.
5. Exportation may not be propagated across multiple files; that is, a node imported into one scene using the IMPORT statement may not then be further exported into another scene using the EXPORT statement.
6. Nodes shall not be exported from the body of a PROTO declaration.
7. The EXPORT statement can appear wherever a ROUTE statement is allowed, and shall be contained within the Inline node to which it refers.

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). All defined alias AS names shall also meet appropriate uniqueness requirements in the local DEF namespace of the parent scene.

9.3 Abstract types

9.3.1 X3DNetworkSensorNode

X3DNetworkSensorNode : X3DSensorNode {
  SFString [in,out] description ""
  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.

9.3.2 X3DUrlObject

X3DUrlObject {
  SFTime   [in,out] autoRefresh          0.0    [0,∞)
  SFTime   [in,out] autoRefreshTimeLimit 3600.0 [0,∞)
  SFString [in,out] description          ""
  SFBool   [in,out] load                 TRUE
  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 X3D 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 X3D 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 X3D 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.

If 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 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:

• an error shall be generated,
• the URL shall be treated as not interpretable as specified in 9.3.2 X3DUrlObject, and
• the next URL shall be loaded and checked in accordance with 9.2 Concepts.

For more information on URLs, see 9.2.1 URLs, URNs and URIs.

9.4 Node reference

9.4.1 Anchor

Anchor : 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            []
  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 X3D 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 X3D 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 X3D browser. Each string shall consist of "keyword=value" pairs. For example, some X3D 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 X3D 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 X3D browser. More details on the bboxCenter and bboxSize fields can be found in 10.2.2 Bounding boxes.

9.4.2 Inline

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

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 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 shall 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 X3D browser and 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 browsers shall not honor self-referential loading of Inline model loops in order to avoid security vulnerabilities.

9.4.3 LoadSensor

LoadSensor : X3DNetworkSensorNode {
  MFNode   [in,out] children    []   [X3DUrlObject]
  SFString [in,out] description ""
  SFBool   [in,out] enabled     TRUE
  SFNode   [in,out] metadata    NULL [X3DMetadataObject]
  SFTime   [in,out] timeOut     0
  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 children 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 children 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 children. 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 children element.

NOTE  the original name for the LoadSensor children field in X3D version 3 is watchList.

If an Anchor node is part of a children field value, isLoaded reports success for this node as follows. There are three cases that Anchor node can handle:

1. binding to a Viewpoint node in the current scene,
2. loading a replacement world or file asset, and
3. launching a separate window for a file asset.

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 X3D browser acknowledges the load request.

The isActive field generates events when loading of the LoadSensor's children 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 children 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 children 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 children 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 children 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 X3D browser-dependent. Regardless, the X3D 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:

• Success of all children:
  • isLoaded = true
  • loadTime = now
  • progress = 1
  • isActive = false
• Timeout of any children, failure of any children, or no network present:
  • isLoaded = false
  • isActive = false

For children 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 X3D browser can render one frame of a movie or start playing an audio file).

9.5 Support levels

The Networking component provides four levels of support as specified in Table 9.3.