### 6.9.5 Rainbow

Rainbows are implemented using fog-like, circular arcs. Their syntax is:

    RAINBOW:
        rainbow { [RAINBOW_IDENTIFIER] [RAINBOW_ITEMS...] }
    RAINBOW_ITEM:
        direction <Dir> | angle Angle | width Width |
        distance Distance | COLOR_MAP | jitter Jitter | up <Up> |
        arc_angle Arc_Angle | falloff_angle Falloff_Angle

Rainbow default values:

    arc_angle     : 180.0
    falloff_angle : 180.0
    jitter        : 0.0
    up            : y

The required `direction` vector determines the direction of the (virtual) light that is responsible for the rainbow. Ideally this is an infinitely far away light source like the sun that emits parallel light rays. The position and size of the rainbow are specified by the required `angle` and `width` keywords. To understand how they work you should first know how the rainbow is calculated.

For each ray the angle between the rainbow's direction vector and the ray's direction vector is calculated. If this angle lies in the interval from `Angle-Width/2` to `Angle+Width/2` the rainbow is hit by the ray. The color is then determined by using the angle as an index into the rainbow's color_map. After the color has been determined it will be mixed with the background color in the same way like it is done for fogs.

Thus the angle and width parameters determine the angles under which the rainbow will be seen. The optional `jitter` keyword can be used to add random noise to the index. This adds some irregularity to the rainbow that makes it look more realistic.

The required `distance` keyword is the same like the one used with fogs. Since the rainbow is a fog-like effect it's possible that the rainbow is noticeable on objects. If this effect is not wanted it can be avoided by using a large distance value. By default a sufficiently large value is used to make sure that this effect does not occur.

The `color_map` statement is used to assign a color map that will be mapped onto the rainbow. To be able to create realistic rainbows it is important to know that the index into the color map increases with the angle between the ray's and rainbow's direction vector. The index is zero at the innermost ring and one at the outermost ring. The filter and transmittance values of the colors in the color map have the same meaning as the ones used with fogs (see section "Fog").

The default rainbow is a 360 degree arc that looks like a circle. This is no problem as long as you have a ground plane that hides the lower, non-visible part of the rainbow. If this isn't the case or if you don't want the full arc to be visible you can use the optional keywords `up`, `arc_angle` and `falloff_angle` to specify a smaller arc.

The `arc_angle` keyword determines the size of the arc in degrees (from 0 to 360 degrees). A value smaller than 360 degrees results in an arc that abruptly vanishes. Since this doesn't look nice you can use the `falloff_angle` keyword to specify a region in which the rainbow will smoothly blend into the background making it vanish softly. The falloff angle has to be smaller or equal to the arc angle.

The `up` keyword determines were the zero angle position is. By changing this vector you can rotate the rainbow about its direction. You should note that the arc goes from -Arc_Angle/2 to +Arc_Angle/2. The soft regions go from -Arc_Angle/2 to -Falloff_Angle/2 and from +Falloff_Angle/2 to +Arc_Angle/2.

The following example generates a 120 degrees rainbow arc that has a falloff region of 30 degrees at both ends:

      rainbow {
        direction <0, 0, 1>
        angle 42.5
        width 5
        distance 1000
        jitter 0.01
        color_map { Rainbow_Color_Map }
        up <0, 1, 0>
        arc_angle 120
        falloff_angle 30
      }

It is possible to use any number of rainbows and to combine them with other atmospheric effects.