The Annotated VRML 97 Reference

1 Intro     Concepts     3 Nodes     4 Fields/Events    Conformance
A Grammar     B Java     C JavaScript     D Examples     E Related Info    References
Quick Java         Quick JavaScript         Quick Nodes   

  About the Book
  Copyright © 1997-99
  Purchase the book from

Chapter 3:
Node Reference


+3.16 DirectionalLight

DirectionalLight { 
  exposedField SFFloat ambientIntensity  0        # [0,1]
  exposedField SFColor color             1 1 1    # [0,1]
  exposedField SFVec3f direction         0 0 -1   # (-INF,INF)
  exposedField SFFloat intensity         1        # [0,1]
  exposedField SFBool  on                TRUE 

The DirectionalLight node defines a directional light source that illuminates along rays parallel to a given 3-dimensional vector. A description of the ambientIntensity, color, intensity, and on fields is in "2.6.6 Light sources".

The direction field specifies the direction vector of the illumination emanating from the light source in the local coordinate system. Light is emitted along parallel rays from an infinite distance away. A directional light source illuminates only the objects in its enclosing parent group. The light may illuminate everything within this coordinate system, including all children and descendants of its parent group. The accumulated transformations of the parent nodes affect the light.

DirectionalLight nodes do not attenuate with distance. A precise description of VRML's lighting equations is contained in "2.14 Lighting model."

DirectionalLight node figure

Figure 3-18: DirectionalLight Node

TECHNICAL NOTE: VRML 1.0 assumed a default global (i.e., affects all objects) ambient light source of intensity 1.0. VRML 2.0 does not define a global ambient light source. Instead, each light source node (DirectionalLight, PointLight, and SpotLight) have an ambientIntensity field that represents that individual light's contribution to the overall ambient illumination. This has the nice result of increasing the overall ambient illumination as the number of lights in the scene increases. This is a gross, yet reasonable, approximation to the physical world. Note that the default value for ambientIntensity of light sources is 0.0 and thus default scenes will have zero ambient illumination.

TIP: The DirectionalLight node is similar to a floodlight in stage or film lighting. It is an excellent choice for simple scene lighting since directional lights are relatively easy to set up; typically result in bright, fully lit scenes; and render faster than the other light types. Since directional lights do not have a radius field to limit the illumination effects, it is very important to parent DirectionalLights under the Transform node of the shapes that you want to illuminate. If you find that your scene is too bright or that objects are being illuminated by unknown lights, you may want to check for DirectionalLights under the wrong Transform node. Also, note that since some rendering libraries do not support scoped lights and thus illuminate all objects in the scene, this may have no effect. Also note that lights in VRML are not occluded by geometry in the scene. This means that geometry nodes are illuminated by light sources regardless of whether other geometry blocks the light emanating from a light source. This can produce unrealistic lighting effects and takes getting used to. Note that it is possible to create shadow effects by creating transparent geometry (e.g., IndexedFaceSet) that creates the illusion of shadows.

TIP: Remember that VRML 2.0 does not define a default ambient light source. This means that the dark side of all objects in the scene will be very, very dark if you do not set the ambientIntensity field of one or more of the light sources. Typically, each light source node in the scene will contribute to the overall ambient illumination, and thus it is recommended to set the ambientIntensity to 1.0 for each light source. Remember that the default ambient field of the Material node (unfortunately also named ambientIntensity) is set to 0.2 and will ensure that the dark sides of the your objects are not too bright.

TIP: Use the light source nodes to control the overall contrast and brightness of your scene. To raise the dark areas (i.e., shadows) of the scene, increase all of the ambientIntensity field of the light sources. To reduce the hot spots, lower the intensity field of the light sources that are affecting the hot spot. By adjusting these two fields, you can control the contrast and brightness of your scene. Also, remember that most rendering libraries do not provide control over the dynamic range of the image (e.g., a camera's f-stop), and thus if you find that your entire scene is too hot, lower the intensities of all of the light sources proportionally until the scene is within a normal luminance range (i.e., no hot spots). You might need to raise all of the ambientIntensity fields as well (described earlier) to compensate.

TIP: Remember that the default NavigationInfo automatically adds an extra light source to your scene (mounted on the user's head). This needs to be considered when designing your scene lighting and must be anticipated or turned off (NavigationInfo { headlight FALSE ... }).

TIP: Most rendering libraries perform lighting calculations only at the vertices of the polygons and then interpolate the computed colors across the polygonal surface rather than compute the lighting at each point of the surface. This technique is known as Gouraud shading (named after Henri Gouraud) and is used to increase rendering performance (lighting calculations can be very expensive!). Gouraud shading can often produce undesirable aliasing artifacts when the number of vertices is too low and does not represent a reasonable sampling of the surface. Adding extra intermediate vertices to the geometry will typically improve the lighting, but can penalize rendering and download performance.

EXAMPLE (click to run): The following example illustrates use of the DirectionalLight node (see Figure 3-19). The first DirectionalLight is contained by the root Group of the scene and thus illuminates all geometry in the scene. Each of the three subsequent DirectionalLights illuminate only the single Shape node that is contained by the light's parent Transform node. Also, note the use of the NavigationInfo node to turn off the browser's headlight: The following example illustrates typical use of the Anchor node. The first Anchor links the Box geometry to another VRML world that replaces this one after the Anchor is activated. The second Anchor links the Sphere to a Viewpoint in this world. When the user clicks on the Sphere, the browser's view is transported to the Viewpoint. The third Anchor links a Cone to a frame on an HTML page. When the user clicks on the Cone, the frame is activated:
#VRML V2.0 utf8
Group {
  children [
    DEF DL1 DirectionalLight {  # One light on all objects
      ambientIntensity 0.39
      direction 0.24 -0.85 -0.46
    Transform {      # One light to shine on the Box
      children [
        DEF DL2 DirectionalLight {
          direction -0.56 0.34 -0.75
        Transform {
          translation -3 0.77 -4.57
          rotation 0.30 0.94 -0.14 0.93
          scale 0.85 0.85 0.85
          scaleOrientation -0.36 -0.89 -0.29  0.18
          children Shape {
            appearance DEF A1 Appearance {
              material Material {
                ambientIntensity 0.34
                diffuseColor .85 .85 .85
                specularColor 1 1 1  shininess .56
            geometry Box {}
    Transform {      # One light to shine on the Sphere
      children [
        DEF DL3 DirectionalLight { direction 0.50 0.84 0.21 }
        Transform {
          translation 0 0.7 -4.5
          children Shape {
            appearance USE A1
            geometry Sphere {}
    Transform {      # One light to shine on the Cone
      children [
        DEF DL4 DirectionalLight { direction 0.81 -0.06 0.58 }
        Transform {
          translation 3 1.05 -4.45
          rotation 0 0 1  0.6
          children Shape {
            appearance USE A1
            geometry Cone {}
    Transform {
      translation 0 -1.1 -4.33
      scale 5 0.15 3
      children Shape { appearance USE A1 geometry Box {} }
    Background { skyColor 1 1 1 }
    NavigationInfo { type "EXAMINE" headlight FALSE }

DirectionalLight node example

Figure 3-19: DirectionalLight Node Example