Shout3D™ 2.5 Specification

Concepts

2.1 Introduction and Contents

2.1.1 Introduction

This document describes key concepts in the Shout3D 2.5 specification. This includes the Shout3D lighting model and how nodes are combined into scene graphs.

2.1.2 Table of contents

See Table 2.1 for the table of contents for this document.

Table 2.1 -- Table of contents, Concepts

2.1.3 Conventions used

The following conventions are used throughout the entire set of Shout3D Specification documents.

Italics are used for field names, and are also used when new terms are introduced and equation variables are referenced.

A fixed-space font is used for URL addresses and source code examples.

Node type names are appropriately capitalized (e.g., "The IndexedFaceSet node draws geometry..."). However, the concept of the node is often referred to in lower case in order to refer to the semantics of the node, not the node itself (e.g., "To rotate the transform...").

The form "0xhh" expresses a byte as a hexadecimal number representing the bit configuration for that byte.

2.2 Overview

2.2.1 Scene graph

The Shout3D scene graph contains nodes which describe objects and their properties. It contains hierarchically grouped geometry to provide a visual representation of objects. Nodes may be instanced and reused in the scene graph hierarchy.

2.2.2 Presentation

Shout3D files will typically be read, parsed, and rendered by a mechanism known as a Core Shout3D viewer.

Core Shout3D viewers are not required to provide any navigation algorithm. The Shout3D API provides mechanisms for getting user input, and for getting and setting the current viewpoint. To provide navigation capabilities, a viewer may use this API to provide the user with the ability to navigate.

2.3 Scene graph structure

2.3.1 Root nodes

A Shout3D scene graph contains a root node and all of its children. A Shout3D viewer may contain more than one scene graph. Root nodes shall be children nodes (see 2.5.5, Grouping and children nodes).

2.3.2 Scene graph hierarchy

A Shout3D scene graph is a directed acyclic graph. Nodes can contain NodeField or NodeArrayField fields that, in turn, contain nodes (or instances of nodes). This hierarchy of nodes is called the scene graph. Each arc in the graph from A to B means that node A has a NodeField or NodeArrayField field whose value directly contains node B. See [FOLE] for details on hierarchical scene graphs.

2.3.3 Descendant and ancestor nodes

The descendants of a node are all of the nodes in its NodeField or NodeArrayField fields, as well as all of those nodes' descendants. The ancestors of a node are all of the nodes that have the node as a descendant.

2.3.4 Transformation hierarchy

The transformation hierarchy includes all of the root nodes and root node descendants that are considered to have one or more particular locations in the virtual world. Shout3D includes the notion of local coordinate systems, defined in terms of transformations from ancestor coordinate systems (using Transform nodes). The coordinate system in which the root nodes are displayed is called the world coordinate system.

Background, NavigationInfo, Interpolator, and TimeSensor nodes are in the scene graph but not affected by the transformation hierarchy.

The transformation hierarchy shall be a directed acyclic graph; results are undefined if a node in the transformation hierarchy is its own ancestor.

2.3.5 Standard units and coordinate system

Shout3D defines the unit of measure of the world coordinate system to be metres. All other coordinate systems are built from transformations based from the world coordinate system. Table 2.2lists standard units for Shout3D.

Table 2.2 -- Standard units

Shout3D uses a Cartesian, right-handed, three-dimensional coordinate system. By default, the viewer is on the Z-axis looking down the -Z-axis toward the origin with +X to the right and +Y straight up. A modelling transformation (see Transform) or viewing transformation (see Viewpoint) can be used to alter this default projection.

2.3.6 Run-time name scope

Each Shout3D Viewer defines a run-time name scope that contains all of the root nodes currently contained by the Shout3D Viewer and all of the descendant nodes of the root nodes.

Nodes created dynamically (using the Shout3D API) are not part of any name scope, until they are added to the scene graph, at which point they become part of the same name scope of their parent node(s). A node may be part of more than one run-time name scope. A node shall be removed from a name scope when it is removed from the scene graph.

2.4 Shout3D and the World Wide Web

2.4.1 URLs

A URL (Uniform Resource Locator), described in [URL], specifies a file located on a particular server and accessed through a specified protocol (e.g., http). In ISO/IEC 14772, 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.

More general information on URLs is described in [URL].

2.4.2 Relative URLs

Relative URLs are handled as described in 2.[RURL]. The base document for nodes that contain URL fields is the file from which the statement is read.

2.5 Node semantics

2.5.1 Introduction

Each node has the following characteristics:

1. A type name. Examples include Background, Shape or Viewpoint.
2. Zero or more fields that define how each node differs from other nodes of the same type. Field values are stored in the Shout3D file along with the nodes, and encode the state of the virtual world.
3. A name. Nodes can be named. This is used by other statements to reference a specific instantiation of a node.

2.5.2 Instancing semantics

A node may be referenced multiple times by a scene graph contained in a Shout3D Viewer. This does not create copies of the node. Instead, the same node is re-inserted into the scene graph, resulting in the node having multiple parents. Using an instance of a node multiple times is called node instancing.

2.5.3 Naming semantics

Node names are limited in scope to a single Shout3D Viewer. Multiple nodes may be given the same name. Given a node named "NewNode", any instancing of "NewNode" in NodeField or NodeArrayField inside NewNode's scope refer to NewNode (see 2.3.4, Transformation hierarchy, for restrictions on self-referential nodes).

2.5.4 Shapes, geometry and appearance

The Shape node associates a geometry node with nodes that define that geometry's appearance. Shape nodes must be part of the transformation hierarchy to have any visible result, and the transformation hierarchy must contain Shape nodes for any geometry to be visible (the only nodes that render visible results are Shape nodes and the Background node). A Shape node contains exactly one geometry node in its geometry field. The following node types are geometry nodes in Shout3D. Programmers may extend this set, by creating new nodes subclassed from the abstract Geometry base class (see Abstract Node Classes):

• IndexedFaceSet
• IndexedLineSet
• PointSet

Shape nodes may specify an Appearance node that describes the appearance properties (material and texture) to be applied to the Shape's geometry. Nodes of the following type may be specified in the material field of the Appearance node. Programmers may extend this set, by creating new nodes subclassed from the Material class:

• Material

Nodes of the following type may be specified by the texture field of the Appearance node.Programmers may extend this set, by creating new nodes subclassed from the abstract Texture base class (see Abstract Node Classes):

• ImageTexture

The interaction between such appearance nodes and the lighting model is described in 2.7, Lighting Model.

2.5.5 Grouping and children nodes

Grouping nodes have a field that contains a list of children nodes. Each grouping node defines a coordinate space for its children. This coordinate space is relative to the coordinate space of the node of which the group node is a child. Such a node is called a parent node. This means that transformations accumulate down the scene graph hierarchy.

The following node types are grouping nodes. Programmers may extend this, by creating new nodes subclassed from the Group base class (see Abstract Node Classes):

• Anchor
• Billboard
• Group
• Switch
• TouchSensor
• Transform

The following node types are children nodes:

The following node types are not valid as children nodes:

All grouping nodes inherit a children field of type NodeArrayField from the base Group class. Adding a node to this field will add that node to the grouping node's set of children. Adding any node to a grouping node's children field that is already in that group's child list is illegal. Adding any node to a grouping node's children field that is an ancestor of that grouping node is illegal.

Note that a variety of node types reference other node types through fields. Some of these are parent-child relationships, while others are not (there are node-specific semantics). Table 2.3 lists all node types that reference other nodes through fields in Shout3D. Programmers may implement new nodes types that reference other nodes. Programmers may also extend the valid set of nodes types that may be referenced in fields of the node types below.

Note that, for each valid node type, any node that is subclassed from that node is a legal value for that field. For example, and the geometry field of the Shape node may be filled with an IndexedFaceSet, IndexedLineSet, PointSet, or any other subclass of Geometry.

Table 2.3 -- Nodes with NodeField or NodeArrayField fields

2.5.6 Light sources

Shape nodes are illuminated by the sum of all of the lights in the world that affect them. This is defined by the contribution of the direct illumination from light sources.

The following node types are light source nodes in Shout3D. Programmers may extend this set, by creating new nodes subclassed from the abstract Light base class (see Abstract Node Classes):

• DirectionalLight

All light source nodes contain the fields affectedGroups, color, intensity and on.

The intensity field specifies the brightness of the direct emission from the light. Light intensity may range from 0.0 (no light emission) to 1.0 (full intensity). The color field specifies the spectral color properties of the light emission as an RGB value. The on field specifies whether the light is enabled or disabled. If the falue is FALSE, then the light is disabled and will not affect any nodes in the scene. If the value is TRUE, then the light will affect other nodes according to the following scoping rules:

2.5.6.1 Scoping of lights

The affectedGroups field controls which nodes in the scene are affected by the light. By default, the field is empty, meaning that the light will affect all nodes below the light node's parent group, but no other nodes. If the affectedGroups field is not null, then it will contain a list of names of Group nodes in the scene. In this case, the light will affect all nodes contained below one of the Group nodes whose name matches an entry in the affectedGroups field. The light will not affect any other nodes. If a value in the affectedGroups field contains a name for which no matching Group node can be found, then that field value will not cause any lighting to occur; other values will still cause lighting of other groups, if matches can be found.

The special value "#Root"

There is a special value for the affectedGroups field, "#Root" which specifies that the light should be scoped to affect all nodes in the viewer.

2.5.7 Sensor nodes

2.5.7.1 Introduction to sensors

The Anchor, TimeSensor and TouchSensor nodes all sensor nodes.

Sensors are children nodes in the hierarchy and therefore may be parented by grouping nodes as described in 2.5.5, Grouping and children nodes.

Anchor and TouchSensor -- pointing-device sensors

The Anchor and TouchSensor nodes may be considered pointing-device sensors, in that they are activated when the user locates the pointing device over geometry descended from their children, or in the case of TouchSensor, the children of the TouchSensor's parent Group. The appearance properties of the geometry do not affect activation of pointing-device sensors. In particular, transparent materials or textures shall be treated as opaque with respect to activation of pointing-device sensors.

For a given user activation, the lowest pointing-device sensor in the hierarchy is activated. All other pointing-device sensors above the lowest pointing-device sensor are ignored. If a pointing-device sensor appears in the transformation hierarchy multiple times (DEF/USE), it shall be tested for activation in all of the coordinate systems in which it appears.

TimeSensor -- an environmental sensor

The TimeSensor is a clock that has no geometry or location associated with it; it is used to start and stop time-based nodes such as interpolators. See 2.7.2, Clock and TimeSensor, and TimeSensor, for more information.

2.5.7.2 Activating sensors

The pointing device controls a pointer in the virtual world. Typically the pointing device may be categorized as either 2D (e.g., conventional mouse) or 3D (e.g., wand). It is suggested that the pointer controlled by a 2D device is mapped onto a plane a fixed distance from the viewer and perpendicular to the line of sight. The mapping of a 3D device may describe a 1:1 relationship between movement of the pointing device and movement of the pointer.

The position of the pointer defines a bearing which is used to determine which geometry is being indicated. When implementing a 2D pointing device it is suggested that the bearing is defined by the vector from the viewer position through the location of the pointer. This is equivalent to using the Picker from the Programming API with a MouseInput's (x,y) coordinates as input to the Picker's pick() method. When implementing a 3D pointing device it is suggested that the bearing is defined by extending a vector from the current position of the pointer in the direction indicated by the pointer.

In all cases the pointer is considered to be indicating a specific geometry when that geometry is intersected by the bearing. If the bearing intersects multiple sensors' geometries, only the sensor nearest to the pointer will be eligible for activation.

2.5.8 Bindable nodes

Bindable nodes have the unique behavior that only one node of each type can be affecting the user's experience, or bound, at any instant in time. Each of these bindable nodes has an isBound field which indicates whether it should be used.

When the isBound field of a bindable node is set to TRUE, the viewer will insure that the isBound field of any other currently bound node of that type is changed to FALSE. If no bindable node of a given type is bound, then the viewer will use the first node in the scene belonging to that type. If the scene contains no nodes at all of that type, it will behave as if there is a node containing the default field values for that type of node.

The following node types are bindable nodes in Shout3D. Programmers may extend this set, by creating new nodes subclassed from the abstract Bindable base class (see Abstract Node Classes):

• Background
• NavigationInfo
• Viewpoint

2.5.9 Texture maps

2.5.9.1 Texture map formats

ImageTexture nodes specify texture maps in Shout3D. Programmers may extend this set, by creating new nodes subclassed from the abstract Texture base class (see Abstract Node Classes). Texture maps are defined by 2D images that contain an array of colour values describing the texture. The texture map values are interpreted differently depending on the number of components in the texture map and the specifics of the image format. In general, texture maps may be described using one of the following forms:

1. Intensity textures (one-component)
2. Intensity plus alpha opacity textures (two-component)
3. Full RGB textures (three-component)
4. Full RGB plus alpha opacity textures (four-component)

Note that most image formats specify an alpha opacity, not transparency (where alpha = 1 - transparency).

See Table 2.4 and Table 2.5 for a description of how the various texture types are applied.

2.5.9.2 Texture map image formats

Texture nodes that require support for the GIF (see [GIF]) image format ( ImageTexture) shall interpret the GIF pixel formats in the following way:

1. Greyscale pixels without alpha or simple transparency are treated as intensity textures.
2. Greyscale pixels with alpha or simple transparency are treated as intensity plus alpha textures.
3. RGB pixels without alpha channel or simple transparency are treated as full RGB textures.
4. RGB pixels with alpha channel or simple transparency are treated as full RGB plus alpha textures.

If the image specifies colors as indexed-color (i.e., palettes or colormaps), the following semantics should be used (note that `greyscale' refers to a palette entry with equal red, green, and blue values):

1. If all the colors in the palette are greyscale and there is no transparency chunk, it is treated as an intensity texture.
2. If all the colors in the palette are greyscale and there is a transparency chunk, it is treated as an intensity plus opacity texture.
3. If any color in the palette is not grey and there is no transparency chunk, it is treated as a full RGB texture.
4. If any color in the palette is not grey and there is a transparency chunk, it is treated as a full RGB plus alpha texture.

Texture nodes that require support for JPEG files (see [JPEG], and ImageTexture) will interpret JPEG files as follows:

1. Greyscale files (number of components equals 1) are treated as intensity textures.
2. YCbCr files are treated as full RGB textures.
3. No other JPEG file types are required. It is recommended that other JPEG files are treated as a full RGB textures.

2.5.10 Interpolator nodes

Interpolators are designed to allow content authors to easily interpolate between values in a Shout3D scene. While Shout3D only specifies linear interpolators, the abstract base class Interpolator is provided so that programmers can create additional types of interpolation.

abstract class Interpolator {
  FloatField 		fraction 	= 0; 	// Usage = NORMALIZED_FLOAT
}

The fraction field specifies the current fraction (from 0 to 1) of the interpolator. The interpolator fraction can be set explicitly for the interpolator to output a new value, or a TimeSensor node can be routed to that field.

Every Node that subclasses Interpolator must define a field called value. This field will store the most recently calculated output. Setting the value of this field will have no effect on the interpolator.

Shout3D includes 4 interpolators, all of which interpolate linearly. These interpolators are CoordinateInterpolator, OrientationInterpolator, PositionInterpolator, and ScalarInterpolator. A discussion of linear interpolators follows.

Linear Interpolators

The Shout3D interpolator nodes are designed for linear keyframed animation. Each of these nodes defines a piecewise-linear function, f(t), on the interval (-infinity, +infinity). The piecewise-linear function is defined by n values of t, called key, and the n corresponding values of f(t), called keyValue. The keys shall be monotonically non-decreasing, otherwise the results are undefined. The keys are not restricted to any interval.

Each of these nodes evaluates f(t) given any value of t (via the fraction field) as follows: Let the n keys t₀, t₁, t₂, ..., t_n-1 partition the domain (-infinity, +infinity) into the n+1 subintervals given by (-infinity, t₀), [t₀, t₁), [t₁, t₂), ... , [t_n-1, +infinity). Also, let the n values v₀, v₁, v₂, ..., v_n-1 be the values of f(t) at the associated key values. The piecewise-linear interpolating function, f(t), is defined to be

     f(t) = v0, if t <= t0,
          = vn-1, if t >= tn-1, 
          = linterp(t, vi, vi+1), if ti <= t <= ti+1

     where linterp(t,x,y) is the linear interpolant, 
     i belongs to {0,1,..., n-2}.

The third conditional value of f(t) allows the defining of multiple values for a single key, (i.e., limits from both the left and right at a discontinuity in f(t)). The first specified value is used as the limit of f(t) from the left, and the last specified value is used as the limit of f(t) from the right. The value of f(t) at a multiply defined key is indeterminate, but should be one of the associated limit values.

All Shout3D interpolator nodes share a common set of fields and semantics:

  FloatField 		fraction = 0; 	// Usage = NORMALIZED_FLOAT
  FloatArrayField 	key 	 = [];   // Usage = NORMALIZED_FLOAT_ARRAY
  FloatArrayField 	keyValue = [];   
  <type>Field		value    = [];	

The usage of the keyValue and value fields are dependent on the type of the interpolator (e.g., the PositionInterpolator's keyValue field usage is COORD3_ARRAY and its value usage is COORD3).

Each time the interpolator node is rendered and each time a field of the interpolator that affects its output value is changed, the value field must be updated.

If a Group node's hidden field will not affect the behavior of interoplator nodes below it. Interpolators will always produce new output values during rendering.

The location of an interpolator node in the transformation hierarchy has no effect on its operation.

2.6 Lighting model

2.6.1 Introduction

The Shout3D lighting model provides detailed equations which define the color to apply to each geometric object. For each object, the values of the Material node and texture currently being applied to the object are combined with the lights illuminating the object. These equations are designed to simulate the physical properties of light striking a surface.

2.6.2 Lighting 'off'

A Shape node is unlit if either of the following is true:

1. The shape's appearance field is NULL (default).
2. The material field in the Appearance node is NULL (default).

Note the special cases of geometry nodes that do not support lighting (see IndexedLineSet, and PointSet, for details).

If the shape is unlit, the color (I_rgb) and alpha (A, 1-transparency) of the shape at each point on the shape's geometry is given in Table 2.4.

Table 2.4 -- Unlit color and alpha mapping

where:

A_T = normalized [0, 1] alpha value from 2 or 4 component texture image
I_T = normalized [0, 1] intensity from 1 or 2 component texture image
I_Trgb= color from 3-4 component texture image

2.6.3 Lighting 'on'

If the shape is lit (i.e., a Material and an Appearance node are specified for the Shape), the Material and Texture nodes determines the diffuse color for the lighting equation as specified in Table 2.5.

The Material's diffuseColor field modulates the color in the texture. Hence, a diffuseColor of white will result in the pure color of the texture, while a diffuseColor of black will result in a black diffuse factor regardless of the texture.

The Material's transparency field modulates the alpha in the texture. Hence, a transparency of 0 will result in an alpha equal to that of the texture. A transparency of 1 will result in an alpha of 0 regardless of the value in the texture.

Table 2.5 -- Lit color and alpha mapping

where:

I_Drgb = material diffuseColor
O_Drgb = diffuse factor, used in lighting equations below
T_M = material transparency

All other terms are as defined in 2.6.2, Lighting `off'.

2.6.4 Lighting equations

Shout3D will evaluate the following lighting equation at each point on a lit surface. RGB intensities at each point on a geometry (I_rgb) are given by:

I_rgb = O_Ergb + SUM( on_i × I_Lrgb× diffuse_i)

where:

diffuse_i = I_i × O_Drgb × ( N · L )

and:

· = modified vector dot product: if dot product < 0, then 0.0, otherwise, dot product
I _Lrgb = light i color

I_i = light i intensity
L = -direction of light source i (Shout3D has only directional lights)
N = normalized normal vector at this point on geometry (calculated by viewer)
O_Drgb = diffuse color, from Material node and/or texture node
O_Ergb = Material emissiveColor
on _i = 1, if light source i affects this point on the geometry,

0, if light source i does not affect this geometry (if outside of enclosing Group/Transform for DirectionalLights, or on field is FALSE)

SUM: sum over all light sources i

2.6.5 References

The Shout3D lighting equations are based on the simple illumination equations given in [FOL]and [OPEN]

2.7 Time

2.7.1 Introduction

Shout3D provides a way for implementations and content authors to query and control the passage of time.

Absolute time is defined as the number of seconds since 00:00:00 GMT January 1, 1970. These times are represented as double-precision floating-point numbers. Negative absolute times are interpreted as happening before 1970.

2.7.2 Clock and TimeSensor

Each Shout3D Viewer provides a simulation of the passage of time via the Clock interface. At each render of the scene or of a subgraph of the scene the Clock's absolute time must be updated by invoking the tick method on the Clock. This sets the current absolute time for that render frame. During that render frame all TimeSensors in the rendered scene or subgraph will use the Clock's current absolute time to determine the TimeSensor's behavior.

Copyright© 1999-2001, Shout3D LLC.