7.1 Introduction

7.1.1 Name

The name of this component is "Core". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

7.1.2 Overview

This clause describes the Core component of this document . The Core component supplies the base functionality for the X3D run-time system, including the abstract base node type, field types, the event model, and routing. Table 7.1 lists the major topics in this clause.

7.2 Concepts

7.2.1 Overview of the core

The Core component provides the minimum functionality required by all X3D-compliant implementations. The Core component supplies the following abstract constructs:

1. X3D field types descended from the abstract type X3DField;
2. the base abstract node types X3DNode and X3DPrototypeInstance;
3. all statements;
4. commonly used interfaces such as X3DBindableNode;
5. the X3D event model and routing;
6. abstract file structure; and
7. prototyping.

The Core component is a prerequisite component for all other X3D components.

The Core component may be supported at a variety of levels, allowing for a range of implementations that are conformant to the X3D architecture, object model and event model. For more information on these topics, see 4. Concepts.

7.2.2 Bindable children nodes

Several X3D nodes, such as Background, TextureBackground, Fog, NavigationInfo, and all nodes derived from X3DViewpointNode are bindable children nodes, inheriting from the abstract node type X3DBindableNode. These nodes have the unique behaviour that only one of each type can be bound per layer ( i.e., affect the user's experience) at any instant in time. The X3D browser shall maintain an independent, separate stack for each type of bindable node in each layer. If there is no LayerSet node defined, there shall be only one set of binding stacks that apply to all nodes in the scene graph. Each of these nodes includes a set_bind inputOnly field and an isBound outputOnly field. The set_bind inputOnly field is used to move a given node to and from its respective top of stack. A TRUE value sent to the set_bind inputOnly field moves the node to the top of the stack; sending a FALSE value removes it from the stack. The isBound event is output when a given node is:

1. moved to the top of the stack;
2. removed from the top of the stack;
3. pushed down from the top of the stack by another node being placed on top.

That is, isBound events are sent when a given node becomes, or ceases to be, the active node. The node at the top of the stack (the most recently bound node) is the active node for its type and is used by the X3D browser to set the world state. If the stack is empty ( i.e., either the X3D file has no bindable nodes for a given type or the stack has been popped until empty), the default field values for that node type are used to set world state. The results are undefined if a multiply instanced (DEF/USE) bindable node is bound.

Bindable nodes only affect the binding stacks of the layer in which they are defined.

The following rules describe the behaviour of the binding stack for a node of type <bindable node> (Background, TextureBackground, Fog, NavigationInfo, or Viewpoint):

4. During read, the first encountered <bindable node> in each layer is bound by pushing it to the top of the <bindable node> stack for that layer. Nodes contained within files referenced by Inline nodes, within the strings passed to the Browser.createX3DFromString() method, or within X3D files passed to the Browser.createX3DFromURL() method (see Part 2 of ISO/IEC 19775) are not candidates for the first encountered <bindable node>. The first node within a locally defined prototype instance is a valid candidate for the first encountered <bindable node>. The first encountered <bindable node> sends an isBound TRUE event.
5. When a set_bind TRUE event is received by a <bindable node>,
   1. If it is not on the top of the stack: the current top of stack node sends an isBound FALSE event. The new node is moved to the top of the stack and becomes the currently bound <bindable node>. The new <bindable node> (top of stack) sends an isBound TRUE event.
   2. If the node is already at the top of the stack, this event has no effect.
6. When a set_bind FALSE event is received by a <bindable node> in the stack, it is removed from the stack. If it was on the top of the stack,
   1. it sends an isBound FALSE event;
   2. the next node in the stack becomes the currently bound <bindable node> ( i.e., pop) and issues an isBound TRUE event.
7. If a set_bind FALSE event is received by a node not in the stack, the event is ignored and isBound events are not sent.
8. When a node replaces another node at the top of the stack, the isBound TRUE and FALSE output events from the two nodes are sent simultaneously ( i.e., with identical timestamps).
9. If a bound node is deleted, it behaves as if it received a set_bind FALSE event (see f above).

A Script node with a field containing a USE reference to a bindable node has the ability to bind a node directly by changing the value of the bind field. Setting the bind value is equivalent to receiving a set_bind event.

The results are undefined if a bindable node is bound and is the child of an LOD, Switch, or any node or prototype that disables its children. If a bindable node is bound that results in collision with geometry, the X3D browser shall perform its self-defined navigation adjustments as if the user navigated to this point (see 23.3.2 Collision).

7.2.3 Sensors

Sensors are nodes that generate events based on external inputs to the scene graph, such as user input, changes to the viewing environment, messages from the network or ticks of the system clock. X3D defines the following types of sensors:

1. Pointing device sensors (see 20 Point device sensor component),
2. Environmental sensors (see 22 Environmental sensor component),
3. Key device sensors (see 21 Key device sensor component),
4. Load sensors (see 9 Networking component),
5. Time sensors (see 8 Time component), and
6. Picking sensors (see 38 Picking component).

Sensors are children nodes in the hierarchy and therefore may be parented by grouping nodes as described in 10.2.1 Grouping and children node types.

Each type of sensor defines when an event is generated. The state of the scene graph after several sensors have generated events shall be as if each event is processed separately, in order. If sensors generate events at the same time, the state of the scene graph will be undefined if the results depend on the ordering of the events.

It is possible to create dependencies between various types of sensors.

EXAMPLE  A TouchSensor may result in a change to a VisibilitySensor node's transformation, which in turn may cause the VisibilitySensor node's visibility status to change.

For a detailed description of how dependencies among sensors are handled during execution, see 4.4.8.3 Execution model.

7.2.4 Metadata

7.2.4.1 Overview

Metadata is information that is associated with the objects of the X3D world but is not a direct part of the world representation. This document defines an abstract interface X3DMetadataObject that identifies a node as containing metadata and metadata nodes that specify metadata values in various data types.

7.2.4.2 Data types for metadata

This document specifies four basic representation types:  strings, single-precision and double-precision floating point values, booleans, and integers. Each piece of metadata has two additional strings that describe:

1. the metadata standard (if any) from which the metadata specification emanates, and
2. the identification for the particular piece of metadata being provided.

The MetadataSet node is provided to support cases when a specific set of metadata requires more than a single data type.

NOTE  Since a metadata node is derived from X3DNode, the metadata node may itself have metadata.

7.2.4.3 Integration with X3D worlds

The X3DNode abstract node type specifies an SFNode field metadata that may only be populated with nodes derived from X3DMetadataObject. If the metadata field is empty, no metadata is associated with the node. Since all nodes in X3D are derived from X3DNode, metadata may be placed anywhere in an X3D world.

Metadata is not included as part of the depiction of an X3D world. However, metadata nodes may have a DEF name and the values of the fields of a metadata node may be accessed by SAI services and can be accessed using routing.

The content of the value field of a metadata node is not interpreted by the X3D browser.

Metadata may also be attached to other X3D nodes by setting the metadata field of that node to a node derived from the X3DMetadataNode abstract node type.

7.2.4.4 Assigning metadata to an entire X3D world

The META statement (see 7.2.5.5 META statement) may be used to assign metadata to the entire world. The content of the META statement is accessible using the SAI. If it is desired that metadata information that applies to the entire world be provided for access through routing, a WorldInfo node containing the metadata in its metadata field may be inserted as a root node.

7.2.5 Abstract X3D structure

7.2.5.1 Organization

An X3D world is conceptually defined as a sequence of nodes and statements organized as a file. The first item in the file is the Header statement. The second item in the file is the PROFILE statement. The PROFILE statement may be optionally followed by one or more COMPONENT, UNIT and/or META statements in that order. There may be multiple of each of the COMPONENT, UNIT, and/or META statements. The remainder of the file consists of the other elements (nodes and statements) defined in this document .

X3D statements include the following:

• Header,
• PROFILE,
• COMPONENT,
• META,
• UNIT,
• ROUTE,
• PROTO declare,
• EXTERNPROTO declare,
• PROTO interface,
• PROTO body,
• IS,
• connect,
• IMPORT, and
• EXPORT

Syntax and explicit/implicit definition for these statements can vary among various X3D encodings and language bindings.

ROUTE statements are used to specify the pathways for allowed transmission of events. These statements link a field in one node to a field of the same field type in another node.

PROTO statements are used to specify new node types. Such statements assign a name to the new node type along with a declaration of the interface for the new node type. This is followed by a definition for the node type functionality.

EXTERNPROTO statements are used to specify an interface to PROTO or EXTERNPROTO statements located externally to the local file.

Prototype instances are nodes.

Any additional X3D content loaded into the scene via Inline nodes or scenes loaded using createX3DFromStream, createX3DFromString, or createX3DFromUrl, shall be declared as having a profile that has an equal or smaller set of required functionality; i.e., there can be no components explicitly declared, or implied by the profile in that content, that requires functionality not declared in the original profile and component declarations for the containing scene. Any UNIT statements within the additional contained external X3D content are ignored and the units specified in the root file are used.

Although an X3D world is described as being contained in a file, the file may be conceptual and created dynamically during run-time as described in Part 2 of ISO/IEC 19775.

Comments may appear at various places throughout an X3D model, with syntax varying according to file encoding. Comments have no effect on scene functionality. Comments are not X3D nodes and not X3D statements. Comments may be interspersed between other X3D nodes and statements as long as they do not interfere with the functionality of the model.

7.2.5.2 Header statement

The Header statement is an encoding-dependent statement containing the following elements:

1. identification of the standard being supported (for this standard, this is "X3D");
2. version of the standard being supported (for this version of this document, the version number is "4.0");
3. identification of the character encoding being supported (for this standard, this shall be "UTF-8"), and
4. optional comments that may apply to the file.

While the exact representation of this information is dependent on the encoding, this information shall always be stored as human-readable text.

7.2.5.3 PROFILE statement

Every X3D application shall declare a profile at the beginning of execution. This declaration tells the X3D browser the exact set of components and their support levels that are required for the application to run, allowing for a X3D browser to dynamically load the appropriate components if it so desires, and providing a mechanism for strict conformance should the X3D browser choose to enforce it. If a browser supports the combination of declared profiles, components, and component support levels (see 7.2.5.4 COMPONENT statement), it may proceed with presenting the world; otherwise, it shall fail.

Each PROFILE is equivalent to a precise combination of COMPONENT statements including names and levels. The Full profile defined to be the superset of all components and component support levels. The Core profile is defined to be the minimum set of all components and component support levels.

The profile is declared via a PROFILE statement immediately following the Header statement at the top of the file. The form of the PROFILE statement is:

PROFILE <name>

where name is a string that does not contain whitespace.

The following profiles are defined in this standard:

1. Core (see A Core profile),
2. Interchange (see B Interchange profile),
3. Interactive (see C Interactive profile),
4. MPEG-4 interactive (see D MPEG-4 interactive profile),
5. Immersive (see E Immersive profile),
6. Full (see F Full profile),
7. CADInterchange (see H CAD interchange profile) and
8. MedicalInterchange (see M MedicalInterchange profile).

The profile name is implicitly qualified by the version number of the standard (see 7.2.5.2 Header statement). X3D browsers shall use both the profile name and the version number to determine the specific characteristics of the profile.

For an X3D model that includes references to Inline nodes, the topmost model defines the maximum capabilities of the combined models. The combination of defined PROFILE and COMPONENT statements in the parent model shall be equivalent to (or a superset of) the union of components and component support levels identified by the PROFILE and COMPONENT statements specified in each contained Inline scene.

7.2.5.4 COMPONENT statement

X3D applications may explicitly declare additional components required for the application to run. This is useful for combining features that do not appear together in a predefined profile, such as adding humanoid animation support to the Immersive profile. If an X3D browser supports the combination of declared profile and components, it may proceed with presenting the world; otherwise, it shall fail.

Declaring a component in a file shall only add support for nodes and functionality defined in that component at the requested support level. Nodes that are defined as part of the prerequisite components (see 4.5.3 Base Components) shall not be automatically included. A user shall declare all components and levels for the nodes and/or functionality being used either explicitly through the use of the COMPONENT statement or implicitly through the PROFILE statement.

Components are declared by COMPONENT statements at the top of the file, immediately following the PROFILE statement but preceding any other content. The form of the component statement is:

COMPONENT <name> <level>

where <name> is a string that does not contain whitespace, and <level> is a positive integer.

If support for a component at the desired level is implied by the application's declared profile, the declaration for that component is unnecessary but may be included.

7.2.5.5 UNIT statement

X3D applications may explicitly alter the initial base units within an X3D world by inserting UNIT statements defining the characteristics of the new default base units. At most one UNIT statement shall be provided for each base unit type. Only the UNIT statements in the root file apply to an X3D world. If no UNIT statements are provided, the initial base units as specified in 4.3.6 Standard units and coordinate system shall apply.

UNIT statements contained in X3D files referenced by Inline nodes or contained in X3D files consisting of EXTERNPROTO bodies shall be used to align affected units to the base units of the root file before the referenced X3D file content is incorporated in the X3D world.

UNIT statements may only be contained in X3D worlds created for X3D version 3.3 or later (as specified in the Header statement). If a version of 3.2 or earlier is specified in conjunction with UNIT statements, the X3D browser shall fail.

A change in a base unit is specified by UNIT statements at the top of the file preceding any element content but in the statement order specified in 7.2.5.1 Organization. The form of the UNIT statement is:

UNIT <category> <name> <conversionFactor>

where <category> is a string specifying one of the categories in Table 4.2, <name> is a string that does not contain whitespace that provides a name for the new default base unit, and <conversionFactor> is a positive double-precision value that converts the new default base unit to the initial base unit specified in Table 4.2.

initialBaseUnit = newDefaultBaseUnit x <conversionFactor>

Direct modification of conversion factors for derived units is not allowed.

7.2.5.6 META statement

X3D applications may explicitly declare metadata about the world being defined. This is done by adding one or more META statements that contain such information. Such statements do not affect the scene graph but simply provide additional information in the world.

Metadata that applies to the entire file may be specified by META statements at the top of the file preceding any element content but in the statement order specified in 7.2.5.1 Organization. The form of the META statement is:

META <key> <data>

where <key> is a string that identifies the metadata and <data> is a string that defines the value for the metadata identified by <key>.

7.2.5.7 ROUTE statement

X3D applications specify connections between fields of one node to fields of other nodes using the ROUTE statement. See 4.4.8.2 Routes for a general discussion of routes.

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

ROUTE <fromNodeName> <fromFieldName> <toNodeName> <toFieldName>

where <fromNodeName> identifies the node that will generate an event, <fromFieldName> is the name of the field in the generating node from which the event will emanate, <toNodeName> identifies the node that will receive an event, and <toFieldName> identifies the field in the destination node that will receive the event.

7.2.5.8 PROTO statement

New node types may be defined by X3D applications through use of the PROTO statement as specified in 4.4.4 Prototype semantics.

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

PROTO <protoName> <protoInterfaceDeclaration> <protoDefinition>

The <protoName> specifies the name for the new node type.

The <protoInterfaceDeclaration> specifies a list of field definitions. Each field definition specifies the data type, access type, and name for the field. For initializeOnly and inputOutput fields, the default value is also specified. See 4.4.4.2 PROTO interface declaration semantics for details.

The <protoDefinition> consists of a list of nodes the first of which is used to specify the node type for the prototype. This list may instantiate other prototypes provided that the definitions of the referenced prototypes precede this PROTO statement. See 4.4.4.3 PROTO definition semantics for details.

7.2.5.9 EXTERNPROTO statement

Externally defined new node types may be used by X3D applications by referencing their definition using the EXTERNPROTO statement as specified in 4.4.5 External prototype semantics.

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

EXTERNPROTO <externprotoName> <externprotoInterfaceDeclaration> <externprotoURL>

The <externprotoName> specifies the name for the new node type.

The <externprotoInterfaceDeclaration> specifies a list of field definitions. Each field definition specifies the data type, access type, and name for the field. The default value for initializeOnly and inputOutput field is derived as specified in 4.4.5.2 EXTERNPROTO interface semantics.

The <externprotoURL> specifies the location of the definition for the externally defined prototype. See 4.4.5.3 EXTERNPROTO URL semantics for details.

7.3 Abstract types

7.3.1 X3DBindableNode

X3DBindableNode : X3DChildNode {
  SFBool [in]     set_bind
  SFNode [in,out] metadata NULL [X3DMetadataObject]
  SFTime [out]    bindTime
  SFBool [out]    isBound
}

X3DBindableNode is the abstract node type for all bindable children nodes, including Background, TextureBackground, Fog, NavigationInfo and Viewpoint. For complete discussion of bindable behaviors, see 7.2.2 Bindable children nodes.

7.3.2 X3DChildNode

X3DChildNode : X3DNode { 
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

This abstract node type indicates that the concrete nodes that are instantiated based on it may be used in children, addChildren, and removeChildren fields.

More details on related children, addChildren, and removeChildren fields for parent nodes can be found in 10.2.1 Grouping and children node types.

7.3.3 X3DInfoNode

X3DInfoNode : X3DChildNode { 
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

This is the base node type for selected nodes that only contain information and have no associated rendering.

7.3.4 X3DMetadataObject

X3DMetadataObject { 
  SFString [in,out] name      ""  (Required)
  SFString [in,out] reference "" 
}

This abstract interface is the basis for all metadata nodes. The interface is inherited by all metadata nodes.

The specification of a non-empty value for the name field is required.

The specification of the reference field is optional. If provided, it identifies the metadata standard or other specification that defines the name field. If the reference field is not provided or is empty, the meaning of the name field is considered implicit to the characters in the string.

7.3.5 X3DNode

X3DNode {
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

This abstract node type is the base type for all nodes and node types in the X3D system.

The metadata field provides information about the current node contents, as described in 7.2.4 Metadata.

7.3.6 X3DPrototypeInstance

X3DPrototypeInstance : X3DNode {
  SFNode [in,out] metadata NULL [X3DMetadataObject]
}

This abstract node type is the base type for all prototype instances in the X3D system. Any user-defined nodes declared with PROTO or EXTERNPROTO are instantiated using this base type. An X3DPrototypeInstance may be placed anywhere in the scene graph where it is legal to place the first node declared within the prototype instance.

For example, if the base type of first node is X3DAppearanceNode, that prototype may be instantiated anywhere in the scene graph that allows for an Appearance node (EXAMPLE  Shape). See 4.4.4.3 PROTO definition semantics for a further example.

7.3.7 X3DSensorNode

X3DSensorNode  : X3DChildNode {
  SFString [in,out] description   ""
  SFBool   [in,out] enabled  TRUE
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  SFBool   [out]    isActive
}

This abstract node type is the base type for all sensors with general behavior described in 7.2.3 Sensors.

The description field is useful for authors to communicate functional intent of the interaction with users. Mechanisms for displaying such description hints are intentionally not specified and may vary among X3D browsers.

The enabled field either enables or disables sensing by the node.

The isActive field provides a TRUE event when node sensing becomes active, and a FALSE event when node sensing is stopped.

NOTE It is considered good security practice for X3D browsers to notify a user when sensing is active.

7.4 Node reference

7.4.1 MetadataBoolean

MetadataBoolean : X3DNode, X3DMetadataObject {
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFBool   [in,out] value     []
}

The value field provides a list of Boolean metadata whose meaning is specified by the name field.

7.4.2 MetadataDouble

MetadataDouble : X3DNode, X3DMetadataObject {
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFDouble [in,out] value     []
}

The value field provides a list of double-precision floating-point metadata whose meaning is specified by the name field.

7.4.3 MetadataFloat

MetadataFloat : X3DNode, X3DMetadataObject { 
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFFloat  [in,out] value     []
}

The value field provides a list of single-precision floating-point metadata whose meaning is specified by the name field.

7.4.4 MetadataInteger

MetadataInteger : X3DNode, X3DMetadataObject { 
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFInt32  [in,out] value     []
}

The value field provides a list of integer metadata whose meaning is specified by the name field.

7.4.5 MetadataSet

MetadataSet : X3DNode, X3DMetadataObject { 
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFNode   [in,out] value     [] [X3DMetadataObject]
}

The value field provides a list of X3DMetadataObject nodes whose meaning is specified by the name field.

7.4.6 MetadataString

MetadataString : X3DNode, X3DMetadataObject { 
  SFNode   [in,out] metadata  NULL [X3DMetadataObject]
  SFString [in,out] name      ""
  SFString [in,out] reference ""
  MFString [in,out] value     []
}

The value field provides a list of string metadata whose meaning is specified by the name field.

7.4.7 WorldInfo

WorldInfo : X3DInfoNode { 
  SFNode   [in,out] metadata NULL [X3DMetadataObject]
  MFString [in,out] info     []
  SFString [in,out] title    ""
}

The WorldInfo node contains information about the world. This node is strictly for documentation purposes and has no effect on the visual appearance or behaviour of the world.

The title field is intended to store the name or title of the world so that X3D browsers can present this to the user (perhaps in the window border). The first WorldInfo title encountered in a parent scene is used for display. WorldInfo nodes in a parent scene take precedence over WorldInfo nodes contained in child scenes that are loaded via the Inline node.

Any other information about the world can be stored in the info field, such as author information, copyright, and usage instructions.

7.5 Support levels

The Core component provides two levels of support as specified in Table 7.2. Level 1 provides the minimum basis for all profiles and components. Level 2 adds support for prototypes.