Environmental effects component - extensions


1. ImageBackground node

ImageBackground : X3DBackgroundNode {
  SFColorRGBA [in,out]      color       1 1 1 1   
  SFNode     [in,out]      texture     NULL        # [X3DTextureNode]
  MFVec2f    [in,out]      texCoords   [ 0 0, 1 0, 1 1, 0 1 ]

Displays a background from a simple 2D image.

Demo models of this node: background/background_image.x3dv, background/background_image_partial.x3dv, background/background_image_animated.x3d . Open them with view3dscene.


  • texture is the most important field of this node. It specifies the actual image to be displayed. If this node is not set, the ImageBackground behaves the same as if it was completely transparent.

    The texture is displayed as a full-screen quad.

    Right now, the allowed texture nodes are ImageTexture and PixelTexture. In the future we plan to allow more nodes, like MovieTexture, or cube-map texture nodes (they would allow to specify background skybox just like a cube-map).

  • color multiplies the texture color. It is opaque white by default.

    Note that the alpha component of this color matters (just like the alpha channel of the texture in texture). If the resulting image is partially-transparent, it will be mixed with the default background color (configurable in view3dscene, in general in Castle Game Engine looking at TCastleSceneManager.BackgroundColor and TCastleSceneManager.Transparent settings; other UI controls may be visible underneath a transparent viewport).

  • texCoords

    Texture coordinates of the full-screen quad. By default they use the whole texture area:

      0 0,
      1 0,
      1 1,
      0 1

    It is undefined what happens if there are not exactly 4 items on this list.

The node inside ImageBackground.texture may specify a TextureProperties node. This TextureProperties is treated a little differently than in other cases:

  • Various TextureProperties fields do not work (as they would make little sense), e.g. minificationFilter and anisotropicDegree are ignored.

  • Also, magnificationFilter="FASTEST" (default value of the TextureProperties.magnificationFilter value) is treated like "LINEAR", although it really should be "NEAREST_PIXEL". So the "trap" with using <TextureProperties/> described on texturing page is not present in case of the ImageBackground.

  • Summing it up, the only useful thing you can do with TextureProperties inside ImageBackground is to request "nearest" (pixelated) filtering by <TextureProperties magnificationFilter="NEAREST_PIXEL" />

Note that this node descends from the "trimmed" Castle Game Engine version of the X3DBackgroundNode node. This trimmed X3DBackgroundNode is just like X3DBindableNode. It doesn't have other fields specified in the X3D specification for X3DBackgroundNode (to be precise, it doesn't have groundAngle, groundColor, skyAngle, skyColor, or transparency).

This node participates in the X3D background nodes stack, which means that only one of the Background, TextureBackground or ImageBackground is active at a given time. You can use X3DBindableNode events to make this node active, or observe when it becomes active.