Object model

Error message

Deprecated function: The each() function is deprecated. This message will be suppressed on further calls in book_prev() (line 775 of /home/drbiz/public/tools.realism.com/modules/book/book.module).

Primary tabs

Submitted by Leonard Daly on

  Overview

The X3D system is made up of abstract individual entities called objects. This part of ISO/IEC 19775 defines a functional specification for each object type but does not dictate implementation. A compliant implementation of an object shall behave according to its functional specification as provided in 5 Field type reference, clauses 7 through 40 describing components, Part 2 of ISO/IEC 19775 or additional parts of this standard that define object, field or node types. An X3D author arranges objects in the scene graph using one of the declarative X3D encodings described in ISO/IEC 19776 or other future encoding formats, or at run time using built-in scripting (if the supported environment and profile provides it) or some other form of programmatic access to the scene graph (see Part 2 of ISO/IEC 19775).

Objects representing lightweight concepts such as data storage and operations on data of that type are called fields and are derived from the X3DField object. Objects representing more complete spatial or temporal processing concepts are called nodes and are derived from the X3DNode object. Nodes contain one or more fields that hold data values or send or receive events for that node.

Some nodes implement additional functionality by inheritance of interfaces that represent common properties or functionality, such as bounding boxes for visual objects and grouping nodes or a specification that a particular object represents metadata. In addition, X3D defines object types for accessing scene graph information not stored in fields or nodes, such as ROUTEs, PROTO declarations, Component/Profile information and world metadata.

A field may contain either a single value of the given type or an array of such types. Throughout this document, a field type containing a single value is said to be of the given type and is prefixed by the characters SF (e.g., field a is of type SFVec3f), while a field containing an array has its type prefixed by the characters MF (e.g., field b is of type MFVec3f). A field may contain a reference to one or more nodes by using the SFNode and MFNode field types.

Each object has the following common characteristics:

  1. A type name. Examples include SFVec3f, MFColor, SFFloat, Group, Background, or SpotLight.
  2. An implementation. The implementation of each object defines how it reacts to changes in its property values, what other property values it alters as a result of these changes, and how it effects the state of the run-time environment. This part of ISO/IEC 19775 defines the functional semantics of built-in nodes (i.e., nodes with implementations that are provided by the X3D browser).

An object derived from X3DNode has the following additional characteristics:

  1. Zero or more field values. Field values are stored in the X3D file along with the nodes or fields, and encode the state of the virtual world.
  2. Zero or more events that it can receive and send. Each node may receive events to its fields which will result in some change to the node's state. Each node may also generate events from its fields to report changes in the node's state. Events generated from one node can be connected to fields of other nodes to propagate these changes. This is done using the ROUTE statement in the file or through an SAI service reference.
  3. A name. Nodes can be named using either the DEF statement in the file or at run-time through an SAI service call. This is used by other statements to reference a specific instantiation of a node. It is also be used to locate a specific named node within the scene hierarchy. In certain environments, the id attribute can be used to construct references to nodes (see Run-time environment ► DOM).

Node implementations are built-in. The environment may allow implementations from prototypes. Built-in nodes are nodes that are available to the author as specified by the applicable profile and/or component declarations. Different components define different sets of built-in nodes. Built-in nodes are available for instantiation declaratively or at run-time using the SAI services specified in Part 2 of ISO/IEC 19775.

 

In the Classic environment (see Run-time environment ► Classic), X3D supports content extensions using prototypes. Prototypes are objects that the author creates using PROTO or EXTERNPROTO statements. These objects are written in the same declarative notation used to describe nodes in the scene graph. They add new object types to the system which are only available for the lifetime of the session into which they are loaded. Some profiles may not include support of these extension capabilities. The semantics of prototypes are discussed in 4.4.4, Prototype semantics, and 4.4.5, External prototype semantics. Prototypes nodes are available for instantiation using a mechanism similar to that for built-in nodes. All prototypes inherit from the base node type X3DPrototypeInstance.

Field semantics

Fields define the persistent state of nodes, and values which nodes may send or receive in the form of events. X3D supports four types of access to a node's fields:

  1. initializeOnly access, which allows content to supply an initial value for the field but does not allow subsequent changes to its value;
  2. inputOnly access, which means that the node may receive an event to change the value of its field, but does not allow the field's value to be read;
  3. outputOnly access, which means that the node may send an event when its value changes, but does not allow the field's value to be written; and
  4. inputOutput access, which allows full access to the field: content may supply an initial value for the field, the node may receive an event to change the value of its field, and the node may send an event when its value changes.

An inputOutput field can receive events like an inputOnly field, can generate events like an outputOnly field, and can be stored in X3D files like an initializeOnly field. An inputOutput field named zzz can be referred to as 'set_zzz' and treated as an inputOnly, and can be referred to as 'zzz_changed' and treated as an outputOnly field. Within ISO/IEC 19775, fields with inputOutput access or inputOnly access are collectively referred to as input fields, fields with inputOutput access or outputOnly access are collectively referred to as output fields, and the events these fields receive and send are called input events and output events, respectively.

In the DOM environment, fields may not be able to control access to their values. In that case, an X3D DOM Environment browser may continue to run and not generate an error if the user reads an initializeOnly or inputOnly field; or the user writes an initializeOnly or outputOnly field. The browser shall ignore all changes to these fields and not receive incoming events for an initializeOnly or outputOnly field; or generate events from an initializeOnly or inputOnly field.

The initial value of an inputOutput field is its value in the X3D file, or the default value for the node in which it is contained, if a value is not specified. When an inputOutput field receives an event it shall generate an event with the same value and timestamp. The following sources, in precedence order, shall be used to determine the initial value of the inputOutput field:

  1. the user-defined value in the instantiation (if one is specified);
  2. the default value for that field as specified in the node or prototype definition.

 

The recommendations for naming initializeOnly fields, inputOutput fields, outputOnly fields, and inputOnly fields for built-in nodes are as follows:

  1. All names containing multiple words start with a lower case letter, and the first letter of all subsequent words is capitalized (e.g., addChildren), with the exception of set_ and _changed, as described below.
  2. It is recommended that all inputOnly fields have the prefix “set_”, with the exception of the addChildren and removeChildren fields.
  3. Certain inputOnly fields and outputOnly fields of type SFTime do not use the "set_" prefix or "_changed" suffix.
  4. It is recommended that all other outputOnly fields have the suffix “_changed” appended, with the exception of outputOnly fields of type SFBool.