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 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 Concepts

9.2.1 URLs

A URL (Uniform Resource Locator), described in 2.[RFC1738], is a form of Universal Resource Identifier (URI) that specifies a file located on a particular server and accessed through a specified protocol (e.g., http). 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 URNs (Uniform Resource Name), which are another form of URI. A URN allows an abstract resolution mechanism to be invoked to locate a resource (see 2.[RFC2141]). 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 2.[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 2.[RFC2141]). This 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 2.[RFC1738].

9.2.2 Relative URLs

Relative URLs are handled as described in 2.[RFC1808]. The base document for nodes that contain URL fields is the X3D file from which the statement is read. The base document for EXTERNPROTO statements or nodes that contain URL fields is:

1. The X3D file in which the prototype is instantiated, if the statement is part of a prototype definition.
2. The file containing the script code which created a new scene graph.
3. Otherwise, the X3D file from which the statement is read, in which case the RURL information provides the data itself.

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. 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
 "http://bar.com/foo.js", # ECMAScript file reference
 "http://bar.com/foo.class" ] # Java platform bytecode file reference
}

The "..." represents in-line ECMAScript source code.

9.2.4 Browser options

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.

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. 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 to be 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.

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.

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. The EXPORT statement has the following components:

1. The DEF name of the node to be exported
2. An optional name to be 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.

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 types

9.3.1 X3DNetworkSensorNode

 
X3DNetworkSensorNode : 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.

9.3.2 X3DUrlObject

X3DUrlObject {
  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.

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.

For more information on URLs, see 9.2.1 URLs.

9.4 Node reference

9.4.1 Anchor

Anchor : X3DGroupingNode { 
  MFNode   [in]     addChildren
  MFNode   [in]     removeChildren
  MFNode   [in,out] children       []       [X3DChildNode]
  SFString [in,out] description    ""
  SFNode   [in,out] metadata       NULL     [X3DMetadataObject]
  MFString [in,out] parameter      []
  MFString [in,out] url            []       [URI]
  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 (e.g., 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 may be used by browser-specific user interfaces that wish to present users with more detailed information about the Anchor.

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 "http://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 Viewpoints 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 Viewpoint transition rules that specify how browsers shall interpret the transition from the old Viewpoint node 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 Viewpoint is not found, no action occurs on activation.

More details on the url field are contained in 9.2.1 URLs.

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.

9.4.2 Inline

Inline : X3DChildNode, X3DBoundedObject, X3DUrlObject {
  SFBool   [in,out] load       TRUE
  SFNode   [in,out] metadata   NULL     [X3DMetadataObject]
  MFString [in,out] url        []       [URI]
  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, 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 (e.g., reading the scene may be delayed until the Inline node's bounding box is visible to the viewer). 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).

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.

It shall be an error to specify a 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 an inlined world 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.

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 (e.g., 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 be used for optimization purposes such as culling.

9.4.3 LoadSensor

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

The isActive field generates events when loading of the LoadSensor's watchList 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 watchList 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 watchlist 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 watchList 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 watchList 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:

• 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 watchList 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 levels

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