Extensible 3D (X3D)
Part 1: Architecture and base components

24 Environmental effects component

# 24.1 Introduction

## 24.1.1 Name

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

## 24.1.2 Overview

This clause describes the Environmental Effects component of this document . Nodes in this component support the creation of realistic environmental effects such as panoramic backgrounds and fog. Table 24.1 provides links to the major topics in this clause.

Table 24.1 — Topics

24.1 Introduction 24.1.1 Name 24.1.2 Overview 24.2 Concepts 24.2.1 Backgrounds 24.2.2 Fog semantics 24.2.2.1 Overview 24.2.2.2 Global fog semantics 24.2.2.3 Local fog semantics 24.2.2.4 Local and bindable fog interaction 24.2.2.5 Fog colour calculation 24.3 Abstract types 24.3.1 X3DBackgroundNode 24.3.2 X3DFogObject 24.4 Node reference 24.4.1 Background 24.4.2 Fog 24.4.3 FogCoordinate 24.4.4 LocalFog 24.4.5 TextureBackground 24.5 Support levels Figure 24.1 — X3DBackgroundNode field relationships Table 24.1 — Topics Table 24.2 — Environmental effects component support levels

# 24.2 Concepts

## 24.2.1 Backgrounds

Background nodes are used to specify a colour backdrop that simulates ground and sky, as well as a background texture, or panorama, that is placed behind all geometry in the scene and in front of the ground and sky. Background nodes are specified in the local coordinate system and are affected by the accumulated rotation of their ancestors as described below. X3D supports two kinds of background nodes: a simple background node that contains a set of url fields for specifying static image files that compose the backdrop (see 24.4.1 Background), and a complex background node containing arbitrary X3DTexture nodes that compose the backdrop (see 24.4.3 TextureBackground). Both types of background node descend from the abstract node type X3DBackgroundNode. Applications should use the Background node for simplicity, and the TextureBackground node for more flexibility and additional features.

Background nodes are bindable nodes as described in 7.2.2 Bindable children nodes. There exists a Background stack, in which the top-most X3DBackgroundNode node on the stack is the currently active X3DBackgroundNode. To move an X3DBackgroundNode node to the top of the stack, a TRUE value is sent to the set_bind field. Once active, the X3DBackgroundNode node is then bound to the X3D browser's view. A FALSE value sent to set_bind removes the X3DBackgroundNode from the stack and unbinds it from the X3D browser's current view.

The backdrop is conceptually a partial sphere (the ground) enclosed inside of a full sphere (the sky) in the local coordinate system with the viewer placed at the centre of the spheres. Both spheres have infinite radius and each is painted with concentric circles of interpolated colour perpendicular to the local Y-axis of the sphere. The X3DBackgroundNode node is subject to the accumulated rotations of its ancestors' transformations. Scaling and translation transformations are ignored. The sky sphere is always slightly farther away from the viewer than the ground partial sphere causing the ground to appear in front of the sky where they overlap.

The skyColor field specifies the colour of the sky at various angles on the sky sphere. Angles for skyColor are specified in angle base units. The following assumes that the angle base units are radians. The equivalent values apply if an angle base unit other than radians is specified.The first value of the skyColor field specifies the colour of the sky at 0.0 radians representing the zenith ( i.e., straight up from the viewer). The skyAngle field specifies the angles from the zenith in which concentric circles of colour appear. The zenith of the sphere is implicitly defined to be 0.0 radians, the natural horizon is at π/2 radians, and the nadir ( i.e., straight down from the viewer) is at π radians. skyAngle is restricted to non-decreasing values in the range [0.0, π]. There shall be one more skyColor value than there are skyAngle values. The first colour value is the colour at the zenith, which is not specified in the skyAngle field. If the last skyAngle is less than π, then the colour band between the last skyAngle and the nadir is clamped to the last skyColor. The sky colour is linearly interpolated between the specified skyColor values.

The groundColor field specifies the colour of the ground at the various angles on the ground partial sphere. Angles for groundColor are specified in angle base units. The following assumes that the angle base units are radians. The equivalent values apply if an angle base unit other than radians is specified. The first value of the groundColor field specifies the colour of the ground at 0.0 radians representing the nadir ( i.e., straight down from the user). The groundAngle field specifies the angles from the nadir that the concentric circles of colour appear. The nadir of the sphere is implicitly defined at 0.0 radians. groundAngle is restricted to non-decreasing values in the range [0.0, π/2]. There shall be one more groundColor value than there are groundAngle values. The first colour value is for the nadir which is not specified in the groundAngle field. If the last groundAngle is less than π/2, the region between the last groundAngle and the equator is non-existant. The ground colour is linearly interpolated between the specified groundColor values.

The back, bottom, front, left, right, and top fields specify a set of images that define a background panorama between the ground/sky backdrop and the scene's geometry. The panorama consists of six images, each of which is mapped onto a face of an infinitely large cube contained within the backdrop spheres and centred in the local coordinate system. The images are applied individually to each face of the cube. On the front, back, right, and left faces of the cube, when viewed from the origin looking down the negative Z-axis with the Y-axis as the view up direction, each image is mapped onto the corresponding face with the same orientation as if the image were displayed normally in 2D ( back to back face, front to front face, left to left face, and right to right face ). On the top face of the cube, when viewed from the origin looking along the +Y-axis with the +Z-axis as the view up direction, the top image is mapped onto the face with the same orientation as if the image were displayed normally in 2D. On the bottom face of the box, when viewed from the origin along the negative Y-axis with the negative Z-axis as the view up direction, the bottom image is mapped onto the face with the same orientation as if the image were displayed normally in 2D.

Figure 24.1 illustrates the X3DBackgroundNode node backdrop and background textures.

Alpha values in the panorama images ( i.e., two or four component images) specify that the panorama is semi-transparent or transparent in regions, allowing earlier rendered layers or the groundColor and skyColor to be visible.

See 18 Texturing component for a general description of texture maps.

Often, the bottom and top images will not be specified, to allow sky and ground to show. The other four images may depict surrounding mountains or other distant scenery.

Figure 24.1 — X3DBackgroundNode field relationships

Panorama images may be one component (greyscale), two component (greyscale plus alpha), three component (full RGB colour), or four-component (full RGB colour plus alpha).

Ground colours, sky colours, and panoramic images do not translate with respect to the viewer, though they do rotate with respect to the viewer. That is, the viewer can never get any closer to the background, but can turn to examine all sides of the panorama cube, and can look up and down to see the concentric rings of ground and sky (if visible).

X3DBackgroundNode nodes are not affected by X3DFogObject nodes. Therefore, if a X3DBackgroundNode node is active ( i.e., bound) while an X3DFogObject node is active, the X3DBackgroundNode node will be displayed with no fogging effects. It is the author's responsibility to set the X3DBackgroundNode values to match the X3DFogObject node values (EXAMPLE ground colours fade to fog colour with distance and panorama images tinted with fog colour). X3DBackgroundNode nodes are not affected by light sources.

## 24.2.2 Fog semantics

### 24.2.2.1 Overview

This document supports two types of fog: global and local.

### 24.2.2.2 Global fog semantics

Global fog applies to the entire world and is specified using a Fog node. Global fog blends the colours of all objects with the fog colour based on distance from the object to the camera. The further the distance the greater the amount of fog colour.

### 24.2.2.3 Local fog semantics

Local fog applies only within the same transformation hierarchy that contains the LocalFog node. This limits the effect of the fog to subsets of the world and supports the creation of realistic effects such as a smoke-filled room inside a larger building that is not smoke-filled. If a local fog and a global fog are both defined and active, the lighting contribution from the local fog shall be used instead of the global effect.

Local fog effects shall not affect nodes derived from X3DBackgroundNode.

### 24.2.2.4 Local and bindable fog interaction

If a global Fog node is bound and a LocalFog node is enabled, the LocalFog node shall have precedence over the globally bound Fog node in determining the fog colour contribution to the lighting equations defined in 17 Lighting component.

### 24.2.2.5 Fog colour calculation

During the traversal of the scene graph, if more than one LocalFog node is encountered in the path from the root to a given renderable leaf node, only the contribution of the LocalFog instance closest to the leaf node shall be used. All other fog values shall be ignored.

# 24.3 Abstract types

## 24.3.1 X3DBackgroundNode

    X3DBackgroundNode : X3DBindableNode {
      SFBool  [in]     set_bind
      MFFloat [in,out] groundAngle   []      [0,π/2]
      MFColor [in,out] groundColor   []      [0,1]
      SFNode  [in,out] metadata      NULL    [X3DMetadataObject]
      MFFloat [in,out] skyAngle      []      [0,π]
      MFColor [in,out] skyColor      0 0 0   [0,1]
      SFFloat [in,out] transparency  0       [0,1]
      SFTime  [out]    bindTime
      SFBool  [out]    isBound
    }

X3DBackgroundNode is the abstract type from which all backgrounds inherit. X3DBackgroundNode is a bindable node that, when bound, defines the panoramic background for the scene. For complete information on backgrounds, see 24.2.1 Backgrounds.

## 24.3.2 X3DFogObject

    X3DFogObject {
      SFColor  [in,out] color           1 1 1    [0,1]
      SFString [in,out] fogType         "LINEAR" ["LINEAR"|"EXPONENTIAL"]
      SFFloat  [in,out] visibilityRange 0        [0,∞)
    }

X3DFogObject is the abstract interface that describes a node that influences the lighting equation through the use of fog semantics. It defines the basic colour and rendering effects that influence the lighting equations as described in 17 Lighting component.

# 24.4 Node reference

## 24.4.1 Background

    Background : X3DBackgroundNode {
      SFBool   [in]     set_bind
      MFString [in,out] backUrl      []    [URI]
      MFString [in,out] bottomUrl    []    [URI]
      MFString [in,out] frontUrl     []    [URI]
      MFFloat  [in,out] groundAngle  []    [0,π/2]
      MFColor  [in,out] groundColor  []    [0,1]
      MFString [in,out] leftUrl      []    [URI]
      SFNode   [in,out] metadata     NULL  [X3DMetadataObject]
      MFString [in,out] rightUrl     []    [URI]
      MFFloat  [in,out] skyAngle     []    [0,π]
      MFColor  [in,out] skyColor     0 0 0 [0,1]
      MFString [in,out] topUrl       []    [URI]
      SFFloat  [in,out] transparency 0     [0,1]
      SFTime   [out]    bindTime
      SFBool   [out]    isBound
    }

A background node that uses six static images to compose the backdrop. The common fields of the Background node are described in 24.2 Concepts. For the backUrl, bottomUrl, frontUrl, leftUrl, rightUrl, topUrl fields, X3D browsers shall support the JPEG (see [JPEG]) and PNG (see ISO/IEC 15948) image file formats, and in addition, may support any other image format (EXAMPLE CGM) that can be rendered into a 2D image. Support for the GIF (see [GIF]) format is recommended (including transparency). More detail on the url fields can be found in 9.2.1 URLs, URNs and URIs.

## 24.4.2 Fog

    Fog : X3DBindableNode, X3DFogObject {
      SFBool   [in]     set_bind
      SFColor  [in,out] color           1 1 1    [0,1]
      SFString [in,out] fogType         "LINEAR" ["LINEAR"|"EXPONENTIAL"]
      SFNode   [in,out] metadata        NULL     [X3DMetadataObject]
      SFFloat  [in,out] visibilityRange 0        [0,∞)
      SFTime   [out]    bindTime
      SFBool   [out]    isBound
    }

The Fog node provides a way to simulate atmospheric effects by blending objects with the colour specified by the color field based on the distances of the various objects from the viewer. The distances are calculated in the coordinate space of the Fog node. The visibilityRange specifies the distance in length base units (in the local coordinate system) at which objects are totally obscured by the fog. Objects located outside the visibilityRange from the viewer are drawn with a constant colour of color. Objects very close to the viewer are blended very little with the fog color. A visibilityRange of 0.0 disables the Fog node. The visibilityRange is affected by the scaling transformations of the Fog node's parents; translations and rotations have no affect on visibilityRange. Values of the visibilityRange field shall be in the range [0,∞).

Since Fog nodes are bindable children nodes (see 7.2.2 Bindable children nodes), a Fog node stack exists, in which the top-most Fog node on the stack is currently active. To push a Fog node onto the top of the stack, a TRUE value is sent to the set_bind field. Once active, the Fog node is bound to the X3D browser view. A FALSE value sent to set_bind, pops the Fog node from the stack and unbinds it from the X3D browser viewer. More details on the Fog node stack can be found in 7.2.2 Bindable children nodes.

The fogType field controls how much of the fog colour is blended with the object as a function of distance. If fogType is "LINEAR", the amount of blending is a linear function of the distance, resulting in a depth cueing effect. If fogType is "EXPONENTIAL," an exponential increase in blending is used, resulting in a more natural fog appearance.

The effect of fog on lighting calculations is described in 17 Lighting component.

## 24.4.3 FogCoordinate

    FogCoordinate : X3DGeometricPropertyNode {
      MFFloat [in,out] depth    []   [0,1]
      SFNode  [in,out] metadata NULL [X3DMetadataObject]
    }

This node defines a set of explicit fog depths on a per-vertex basis. This depth value shall be applied per-vertex and used to replace the automatically generated depth. Fog coordinates take precedence over implicitly generated depths; specifying fog coordinates will result in the implicit depth (specified by the visibilityRange field of a node derived from X3DFogObject) being ignored. Details on lighting equations can be found in 17.2.2 Lighting model.

One depth value per vertex shall be supplied. If the user does not provide a sufficient number of depth values, the last value defined shall be replicated for any further vertices. If too many depth values are supplied, the excess depth values shall be ignored.

## 24.4.4 LocalFog

    LocalFog : X3DChildNode, X3DFogObject {
      SFColor  [in,out] color           1 1 1    [0,1]
      SFBool   [in,out] enabled         TRUE
      SFString [in,out] fogType         "LINEAR" ["LINEAR"|"EXPONENTIAL"]
      SFNode   [in,out] metadata        NULL     [X3DMetadataObject]
      SFFloat  [in,out] visibilityRange 0        [0,∞)
    }

The LocalFog node provides a way to simulate atmospheric effects by blending objects with the colour specified by the color field based on the distances of the various objects from the viewer. The distances are calculated in the coordinate space of the LocalFog node. The visibilityRange field specifies the distance in metres (in the local coordinate system) at which objects are totally obscured by the fog. Objects located outside the visibilityRange from the viewer are drawn with a constant colour of color. Objects very close to the viewer are blended very little with the fog color. A visibilityRange of 0.0 disables the LocalFog node. The visibilityRange is affected by the scaling transformations of the parents of the LocalFog node; translations and rotations have no affect on visibilityRange.

The fogType field controls how much of the fog colour is blended with the object as a function of distance. If fogType is "LINEAR", the amount of blending is a linear function of the distance, resulting in a depth-cueing effect. If fogType is "EXPONENTIAL", an exponential increase in blending is used, resulting in a more natural fog appearance.

The effect of fog on lighting calculations is described in 17 Lighting component.

## 24.4.5 TextureBackground

    TextureBackground : X3DBackgroundNode {
      SFBool  [in]     set_bind
      SFNode  [in,out] backTexture   NULL  [X3DTexture2DNode|MultiTexture]
      SFNode  [in,out] bottomTexture NULL  [X3DTexture2DNode|MultiTexture]
      SFNode  [in,out] frontTexture  NULL  [X3DTexture2DNode|MultiTexture]
      MFFloat [in,out] groundAngle   []    [0,π/2]
      MFColor [in,out] groundColor   []    [0,1]
      SFNode  [in,out] leftTexture   NULL  [X3DTexture2DNode|MultiTexture]
      SFNode  [in,out] metadata      NULL  [X3DMetadataObject]
      SFNode  [in,out] rightTexture  NULL  [X3DTexture2DNode|MultiTexture]
      MFFloat [in,out] skyAngle      []    [0,π]
      MFColor [in,out] skyColor      0 0 0 [0,1]
      SFNode  [in,out] topTexture    NULL  [X3DTexture2DNode|MultiTexture]
      SFFloat [in,out] transparency  0     [0,1]
      SFTime  [out]    bindTime
      SFBool  [out]    isBound
    }

The TextureBackground node uses six individual texture nodes to compose the backdrop. Unlike the Background node, which only supports static image formats referenced by URL fields, the contents of the TextureBackground node can be arbitrary texture types, including ImageTexture, PixelTexture, MovieTexture and MultiTexture. The common fields of the TextureBackground node are described in 24.2 Concepts.

TextureBackground supports the creation of rich backgrounds with animation. It also allows the world author to attach load sensors (see 9.4.3 LoadSensor) to the node's texture fields to receive notification of when elements of the background are loaded.

TextureBackground supports a transparency value that allows the scene to overlay other elements in an application. A transparency value of zero specifies that the background is fully opaque obscuring all content in the underlying window. A transparency value of one specifies that the background specified by the TextureBackground node is fully transparent causing the TextureBackground to not be visible so that all underlying content appears as the background. The value of the transparency field is applied to the skyColor and groundColor by first converting the transparency value to an alpha value using the formula:

> alpha = (1 - transparency)

The alpha value is then multiplied against the components of the skyColor and groundColor (including the alpha component, if provided) to obtain the color that is applied to the underlying window content. The transparency value is not applied to the six texture fields. Transparency of these fields can be achieved by using alpha values within their images.

For the backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, topTexture fields, X3D browsers shall support any X3DTexture node types supported in the currently supported profile.

# 24.5 Support levels

The Environmental Effects component provides three levels of support as specified in Table 24.2. Level 1 is intended to support simple backgrounds for lightweight profiles. Level 2 provides additional environmental effects, including full background features, fog, and limited texture backgrounds. Level 3 provides full support for texture backgrounds.

Table 24.2 — Environmental effects component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 Time 1 Grouping 1 |  |
|  | X3DBackgroundNode (abstract) | n/a
|  | X3DFogObject (abstract) | n/a
|  | Background | groundAngle and groundColor optionally supported. backURL, frontURL, leftURL, rightURL, topURL optionally supported. skyAngle optionally supported. One skyColor.
2 | Core 1 Time 1 Grouping 1 |  |
|  | All Level 1 Environmental Effects nodes | All fields fully supported.
|  | Fog | All fields fully supported.
3 | Core 1 Time 1 Grouping 1 |  |
|  | All Level 2 Environmental Effects nodes | All fields fully supported.
|  | TextureBackground | All fields fully supported.
4 | Core 1 Time 1 Grouping 1 |  |
|  | All Level 3 Environmental Effects nodes | All fields fully supported.
|  | FogCoordinate | All fields fully supported.
|  | LocalFog | All fields fully supported.