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

All url fields can hold multiple string values. The strings in these fields indicate multiple locations to search for data in decreasing order of preference. If the browser cannot locate or interpret the data specified by the first location, it might try the second and subsequent locations in order until a URL containing interpretable data is encountered. But X3D browsers only have to interpret a single URL. If no interpretable URLs are located, the node type defines the resultant default behaviour.

A component extension can extend the URL support of a browser, such as supporting URNs (Uniform Resource Name), which are a superset of the URL concept. 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.

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 which conform to a profile which supports scripting are not required to support both the Java and ECMAScript scripting languages. Browsers shall adhere to the protocol defined in the corresponding annex of ISO/IEC 19777 for any scripting language which is supported. The following example 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 protocol ECMAScript
 "http://bar.com/foo.js", # std protocol ECMAScript
 "http://bar.com/foo.class" ] # std protocol Java platform bytecode
}

In the example above, 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 startup time that control its runtime 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.3 Abstract types

9.3.1 X3DNetworkSensorNode

 
X3DNetworkSensorNode : X3DSensorNode {
  SFBool [in,out] enabled   TRUE
  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 : X3DObject {
  MFString [in, out] url [] [urn];
}

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 decreasing order of preference. 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 URL containing interpretable data is encountered. X3D browsers only have to interpret a single URL. If no interpretable URLs are located, the node type defines the resultant default behaviour.

Higher levels of this component extend the URL support of a browser, such as supporting URNs (Uniform Resource Name), which are a superset of the URL concept. 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 more information on URLs, see 9.2.1, URLs.

9.4 Node reference

9.4.1 Anchor

Anchor : X3DGroupingNode, X3DBoundedObject { 
  MFNode   [in]     addChildren
  MFNode   [in]     removeChildren
  MFNode   [in,out] children       []       [X3DChildNode]
  SFString [in,out] description    ""
  MFString [in,out] parameter      []
  MFString [in,out] url            []       [urn]
  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 name of a viewpoint defined in the X3D file. For 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 2.[PART9]).

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 4.10.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 {
  SFBool   [in,out] load       TRUE
  MFString [in,out] url        []       [urn]
  SFVec3f  []       bboxCenter 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.

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
  SFTime  [in,out] timeout   0
  MFNode  [in,out] watchList []   [X3DUrlNode]
  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 X3DUrlNode), may be specified in the watchList field. Multiple nodes may be watched with a single LoadSensor.

An example:

Shape {
   appearance Appearance {
      material Material {
         texture DEF TEX1 Texture { url "Amypic.png" }
      }
   }
   geometry Sphere {}
}
Shape {
   appearance Appearance {
      material Material {
         texture DEF TEX2 Texture { url "Bmypic.png" }
      }
   }
   geometry Sphere {}
}
DEF LS LoadSensor {
   watchList [ USE TEX1, USE TEX2 ]
}
ROUTE LS.loadTime TO MYSCRIPT.loadTime

Specifying multiple children to this field the output event is generated only when all of the listed children have loaded or at least one has failed. If individual failure information is desired, multiple nodes are used.

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 streamed children the first frame of data available means success (i. e., the browser can render one frame of a movie or start playing an audio file)

The Progress field has the following behaviour:

• always has a value of 1 on finish
• in-between events are up to the browser
• units are meaningless (might be % bytes, % number of files....), but will always be increasing.

In all cases, only one event is guaranteed.

9.5 Support levels

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