Textures are the materials from which the objects in POV-Ray are made. They 
specifically describe the surface coloring, shading, and properties like 
transparency and reflection.

You can create your own textures using the parameters described below, or 
you can use the many pre-defined high quality textures that have been 
provided in the files TEXTURES.INC and STONES.INC. The tutorial in section 
4 above introduces the basics of defining textures and attaching them to 
objects.  It explains how textures are made up of three portions, a color 
pattern called "pigment", a bump pattern called "normal", and surface 
properties called "finish". 

The most complete form for defining a texture is as follows:

  texture {
    TEXTURE_IDENTIFIER
    pigment {...}
    normal {...}
    finish {...}
    TRANSFORMATIONS...
  }

Each of the items in a texture are optional but if they are present, the 
identifier must be first and the transformations bust be last.  The 
pigment, normal and finish parameters modify any pigment, normal and finish 
already specified in the TEXTURE_IDENTIFIER.  If no texture identifier is 
specified then the pigment, normal and finish statements modify the current 
default values.  TRANSFORMATIONs are translate, rotate and scale 
statements.  They should be specified last.

The sections below describe all of the options available in pigments, 
normals and finishes.

The color or pattern of colors for an object is defined by a pigment 
statement.  A pigment statement is part of a texture specification.  
However it can be tedious to type "texture{pigment{...}}" just to add a 
color to an object.  Therefore you may attach a pigment directly to an 
object without explicitly specifying that it as part of a texture.  For 
example...

 this...                        can be shortened to this...

  object {                           object {                   
    My_Object                          My_Object                
    texture {                          pigment {color Purple} 
      pigment {color Purple}         }                        
    }                                  
  }                                                           

The color you define is the way you want it to look if fully illuminated.  
You pick the basic color inherent in the object and POV-Ray brightens or 
darkens it depending on the lighting in the scene.  The parameter is called 
"pigment" because we are defining the basic color the object actually IS 
rather than how it LOOKS.

The most complete form for defining a pigment is as follows:

  pigment {
    PIGMENT_IDENTIFIER
    PATTERN_TYPE
    PIGMENT_MODIFIERS
    TRANSFORMATIONS...
  }

Each of the items in a pigment are optional but if they are present, they 
should be in the order shown above to insure that the results are as 
expected.  Any items after the PIGMENT_IDENTIFIER modify or override 
settings given in the IDENTIFIER.  If no identifier is specified then the 
items modify the pigment values in the current default texture.  
TRANSFORMATIONs are translate, rotate and scale statements.  They apply 
only to the pigment and not to other parts of the texture.  They should be 
specified last.

The various PATTERN_TYPEs fall into roughly 4 categories.  Each category is 
discussed below.  They are solid color, color list patterns, color mapped 
patterns and image maps.

The simplest type of pigment is a solid color.  To specify a solid color 
you simply put a color specification inside a pigment.  For example...

  pigment {color Orange}

A color specification consists of the keyword "color" followed a color 
identifier or by a specification of the amount or red, green, blue and 
transparency in the surface.  For example:

  color red 0.5   green 0.2   blue 1.0

The float values between 0.0 and 1.0 are used to specify the intensity of 
each primary color of light.  Note that we use additive color primaries 
like the color phosphors on a color computer monitor or TV.  Thus...

  color red 1.0   green 1.0   blue 1.0 

 ...specifies full intensity of all primary colors which is white light.  
The primaries may be given in any order and if any primary is unspecified 
its value defaults to zero.

In addition to the primary colors a 4th value called "filter" specifies the 
amount of transparency.  For example a piece of red tinted cellophane might 
have...

  color red 1.0  filter 1.0

Lowering the filter value would let less light through.  The default value 
if no filter is specified is 0.0 or no transparency.  Note that the example 
has an implied "green 0.0  blue 0.0" which means that no green or blue 
light can pass through.  Often users mistakenly specify a clear object 
by...
 
  color filter 1.0

but this has implied red, green and blue values of zero.  You've just 
specified a totally black filter so no light passes through.  The correct 
way is...

  color red 1.0   green 1.0   blue 1.0   filter 1.0

Note in earlier versions of POV-Ray the keyword "alpha" was used for 
transparency.  However common usage of "alpha" in this context usually 
means that light passes through unaffected.  In POV-Ray however, light is 
filtered when it passes through a colored surface.  The program works the 
same as it always did but the keyword has been changed to make its meaning 
clearer.

A short-cut way to specify a color is...

  color rgb<0.2, 0.5, 0.9>

      or

  color rgbf<0.2, 0.8, 1.0, 0.7>

Color specifications are used elsewhere in POV-Ray.  Unless stated 
otherwise, all of the above information on color specs given above applies 
to any color spec.

Color identifiers may be declared.  For examples see COLORS.INC.  A color 
identifier contains red, blue, green and filter values even if they are not 
explicitly specified.  For example:

  color filter 1.0 My_Color // here My_Color overwrites the filter

  color My_Color filter 1.0 // this changes My_Color's filter value to 1.0

When using a color specification to give an object a solid color pigment, 
the keyword "color" may be omitted.  For example...

  pigment {red 1  blue 0.5}
        or
  pigment {My_Color}

are legal.

Two of the simplest color patterns available are the checker and hexagon 
patterns.  These patterns take a simple list of colors one after the other.  
For example a checker pattern is specified by...

  pigment {checker color C1  color C2}

This produces a checkered pattern consisting of alternating squares of 
color C1 and C2.  If no colors are specified then default blue and green 
colors are used.

All color patterns in POV-Ray are 3 dimensional.  For every x,y,z point in 
space, the pattern has a unique color.  In the case of a checker pattern it 
is actually a series of cubes that are one unit in size.  Imagine a bunch 
of 1 inch cubes made from two different colors of modeling clay.  Now 
imagine arranging the cubes in an alternating check pattern and stacking 
them in layer after layer so that the colors still alternated in every 
direction.  Eventually you would have a larger cube.  The pattern of checks 
on each side is what the POV-Ray checker pattern produces when applied to a 
box object.  Finally imagine cutting away at the cube until it is carved 
into a smooth sphere or any other shape.  This is what the checker pattern 
would look like on an object of any kind.

Color patterns do not wrap around the surfaces like putting wallpaper on an 
object.  The patterns exist in 3-d and the objects are carved from them 
like carving stacked colored cubes.  In a later section we describe wood 
and marble patterns for example.  The wood grain or stone swirls exist 
through the whole object but they appear only at the surface.

Another pattern that uses a list of colors is the hexagon pattern.  A 
hexagon pattern is specified by...

  pigment {hexagon color C1  color C2  color C3}

Hex pattern generates a repeating pattern of hexagons in the XZ plane.  In 
this instance imagine tall rods that are hexagonal in shape and are 
parallel to the Y axis and grouped in bundles like this...

           _____              
          /     \              
         /   C2  \_____             
        |\       /     \        
        | \_____/   C3  \
        | /     \       /|      
         /   C1  \_____/ |
        |\       /|    | |
        | \_____/ |    | |
        | |     | |    | |
        | |     | |    | |
        | |     | |    | |
        | |     | |    | |
        | |     | |    |
        | |     | |    |
          |     |
          |     |


The three colors will repeat the pattern shown above with hexagon C1 
centered at the origin.  Each side of the hexagon is one unit long.  The 
hexagonal "rods" of color extend infinitely in the +Y and -Y directions.  
If no colors are specified then default blue, green, and red colors are 
used.

Most of the color patterns do not use abrupt color changes of just two or 
three colors like those in the checker or hexagon patterns.  They instead 
use smooth transitions of many colors that gradually change from one point 
to the next.  The colors are defined in a color map that describes how the 
pattern blends from one color to the next.  

This simplest such pattern is the "gradient" pattern.  It is specified as 
follows...

  pigment {gradient VECTOR}

where VECTOR is a vector pointing in the direction that the colors blend.  
For example:

      sphere {
        <0, 1, 2>, 2
        pigment { gradient x } // bands of color vary as you move
                               // along the "x" direction.
      }

This produces a series of smooth bands of color that look like layers of 
color next to each other.  Points at x=0 are black.  As the X location 
increases it smoothly turns to white at x=1.  Then it starts over with 
black and gradually turns white at x=2.  The pattern reverses for negative 
values of X.  Using "gradient y" or "gradient z" makes the colors blend 
along the y or z axis.  Any vector may be used but x, y and z are most 
common.

The gray scale default colors of the gradient pattern isn't a very 
interesting sight.  The real power comes from specifying a color map to 
define how the colors should blend.

Each of the various pattern types available is in fact a mathematical 
function that takes any x,y,z location and turns it into a number between 
0.0 and 1.0.  That number is used to specify what mix of colors to use from 
the color map.

A color map is specified by...

      color_map {
        [ NUM_1 color C1]
        [ NUM_2 color C2]
        [ NUM_3 color C3]
         ... 
        }

Where NUM_1, NUM_2... are float values between 0.0 and 1.0 inclusive.  C1, 
C2 ... are color specifications.  NOTE: the [] brackets are part of the 
actual statement.  They are not notational symbols denoting optional parts.  
The brackets surround each entry in the color map.  There may be from 2 to 
20 entries in the map. 

For example,

      sphere {
        <0,1,2>, 2
        pigment { 
          gradient x 
          color_map {
            [0.1  color Red]
            [0.3  color Yellow]
            [0.6  color Blue]
            [0.6  color Green]
            [0.8  color Cyan]
          }
        }
      }

The pattern function is evaluated and the result is a value from 0.0 to 
1.0.  If the value is less than the first entry (in this case 0.1) then the 
first color (Red) is used.  Values from 0.1 to 0.3 use a blend of red and 
yellow using linear interpolation of the two colors.  Similarly values from 
0.3 to 0.6 blend from yellow to blue.  Note that the 3rd and 4th entries 
both have values of 0.6.  This causes an immediate abrupt shift of color 
from blue to green.  Specifically a value that is less than 0.6 will be 
blue but exactly equal to 0.6 will be green.  Moving along, values from 0.6 
to 0.8 will be a blend of green and cyan.  Finally any value greater than 
or equal to 0.8 will be cyan.

If you want areas of unchanging color you simply specify the same color for 
two adjacent entries.  For example:

      color_map {
        [0.1  color Red]
        [0.3  color Yellow]
        [0.6  color Yellow]
        [0.8  color Green]
      }

In this case any value from 0.3 to 0.6 will be pure yellow.

A "gradient x" pattern uses colors from the color map from 0.0 up to 1.0 at 
location x=1 but then jumps back to the first color for x=1.00000001 (or 
some tiny fraction above 1.0) and repeats the pattern again and again.  The 
marble pattern is similar except that it uses the color map from 0 to 1 but 
then it reverses the map and blends from 1 back to zero.  For example:

      pigment { 
        gradient x 
        color_map {
          [0.0  color Yellow]
          [1.0  color Cyan]
        }
      }

This blends from yellow to cyan and then it abruptly changes back to yellow 
and repeats.  However replacing "gradient x" with "marble" smoothly blends 
from yellow to cyan as the x coordinate goes from 0.0 to 0.5 and then 
smoothly blends back from cyan to yellow by x=1.0.

When used with a "turbulence" modifier and an appropriate color map, this 
pattern looks like veins of color of real marble, jade or other types of 
stone. By default, marble has no turbulence.

Wood uses the color map to create concentric cylindrical bands of color 
centered on the Z axis.  These bands look like the growth rings and veins 
in real wood.  Small amounts of turbulence should be added to make it look 
more realistic. By default, wood has no turbulence.

Like marble, wood uses color map values 0 to 1 then repeats the colors in 
reverse order from 1 to 0.

Onion is a pattern of concentric spheres like the layers of an onion.  It 
uses colors from a color map from 0 to 1, 0 to 1 etc without reversing.

Leopard creates regular geometric pattern of circular spots.  It uses 
colors from a color map from 0 to 1, 0 to 1 etc without reversing.

This pattern uses a simple 1/f fractal noise function to give a pretty darn 
good granite pattern. Typically used with small scaling values (2.0 to 
5.0).  This pattern is used with creative color maps in STONES.INC to 
create some gorgeous layered stone textures. By default, granite has no 
turbulence.  It uses colors from a color map from 0 to 1, 0 to 1 etc 
without reversing.

The bozo color pattern takes a noise function and maps it onto the surface 
of an object. It uses colors from a color map from 0 to 1, 0 to 1 etc 
without reversing.

Noise in ray tracing is sort of like a random number generator, but it has 
the following properties:

  1) It's defined over 3D space i.e., it takes x, y, and z and returns the 
noise value there.
  2) If two points are far apart, the noise values at those points are 
relatively random.
  3) If two points are close together, the noise values at those points are 
close to each other.

You can visualize this as having a large room and a thermometer that ranges 
from 0.0 to 1.0. Each point in the room has a temperature. Points that are 
far apart have relatively random temperatures. Points that are close 
together have close temperatures. The temperature changes smoothly, but 
randomly as we move through the room. 

Now, let's place an object into this room along with an artist. The artist 
measures the temperature at each point on the object and paints that point 
a different color depending on the temperature. What do we get? A POV-Ray 
bozo texture!

This uses the same noise pattern as bozo but it is unaffected by 
turbulence.  It uses colors from a color map from 0 to 1, 0 to 1 etc 
without reversing.

This pattern is very beautiful and similar to marble, but uses a different 
turbulence function. The turbulence keyword has no effect, and as such it 
is always very turbulent. You may control the amount of the built-in 
turbulence by adding the "agate_turb" keyword followed by a float value.  
For example:

      pigment { 
        agate
        agate_turb 0.5
        color_map {
          ...
        }
      }

The mandel pattern computes the standard Mandelbrot fractal pattern and 
projects it onto the X-Y plane.  It uses the X and Y coordinates to compute 
the Mandelbrot set.  The pattern is specified with the keyword mandel 
followed by an integer number.  This number is the maximum number of 
iterations to be used to compute the set.  Typical values range from 10 up 
to 256 but any positive integer may be used.  For example:

      sphere { 
       <0, 0, 0>, 1 
       pigment {
         mandel 25
         color_map {
           [0.0  color Cyan]
           [0.3  color Yellow]
           [0.6  color Magenta]
           [1.0  color Cyan]
         }
         scale .5
       }
      }

The value passed to the color map is computed by the formula:

	value = number_of_iterations / max_iterations

The color extends infinitely in the Z direction similar to a planar image 
map.  

The radial pattern is a radial blend that wraps around the +Y axis.  The 
color for value 0.0 starts at the +X direction and wraps the color map 
around from east to west with 0.25 in the -Z direction, 0.5 in -X, 0.75 at 
+Z and back to 1.0 at +X.  See the "frequency" and "phase" pigment 
modifiers below for examples.

When all else fails and none of the above pigment pattern types meets your 
needs, you can use an image map to wrap a 2-D bit-mapped image around your 
3-D objects.

The syntax for image_map is...

  pigment {
    image_map {
      FILE_TYPE "filename"
      MODIFIERS...
    }
  }

Where FILE_TYPE is one of the following keywords "gif", "tga", "iff" or 
"dump".  This is followed by the name of the file in quotes.  Several 
optional modifiers may follow the file specification.  The modifiers are 
described below.  Note: Earlier versions of POV-Ray allowed some modifiers 
before the FILE_TYPE but that syntax is being phased out in favor of the 
syntax described here.

Filenames specified in the image_map statements will be searched for in the 
home (current) directory first, and if not found, will then be searched for 
in directories specified by any "-L" (library path) options active. This 
would facilitate keeping all your image maps files in a separate 
subdirectory, and giving an "-L" option on the command line to where your 
library of image maps are. 

By default, the image is mapped onto the X-Y plane.  The image is 
"projected" onto the object as though there were a slide projector 
somewhere in the -Z direction.  The image exactly fills the square area 
from x,y coordinates (0,0) to (1,1) regardless of the image's original size 
in pixels.  If you would like to change this default, you may translate, 
rotate or scale the pigment or texture to map it onto the object's surface 
as desired. 

In the section 5.4.1.2 above when we explained checker pigment patterns, we 
described the checks as solid cubes of colored clay from which objects are 
carved.  With image maps you should imagine that each pixel is a long, 
thin, square, colored rod that extends parallel to the Z axis.  The image 
is made from rows and columns of these rods bundled together and the object 
is then carved from the bundle.

If you would like to change this default orientation, you may translate, 
rotate or scale the pigment or texture to map it onto the object's surface 
as desired. 

Normally there are an infinite number of repeating images created over 
every unit square of the X-Y plane like tiles.  By adding the keyword 
"once" after a file name, you can eliminate all other copies of the image 
except the one at (0,0) to (1,1).  Areas outside this unit square are 
treated as fully transparent.

Note: The "once" keyword may also be used with bump_map and material_map 
statements.

The default projection of the image onto the X-Y plane is called a "planar 
map type".  This option may be changed by adding the "map_type" keyword 
followed by a number specifying the way to wrap the image around the 
object.

A "map_type 0" gives the default planar mapping already described.

A "map_type 1" is a spherical mapping.  It assumes that the object is a 
sphere of any size sitting at the origin.  The Y axis is the north/south 
pole of the spherical mapping.  The top and bottom edges of the image just 
touch the pole regardless of any scaling.  The left edge of the image 
begins at the positive X axis and wraps the image around the sphere from 
"west" to "east" in a -Y rotation.  The image covers the sphere exactly 
once.  The "once" keyword has no meaning for this type.

With "map_type 2" you get a cylindrical mapping.  It assumes that a 
cylinder of any diameter lies along the Y axis.  The image wraps around the 
cylinder just like the spherical map but the image remains 1 unit tall from 
y=0 to y=1.  This band of color is repeated at all heights unless the 
"once" keyword is applied.

Finally "map_type 5" is a torus or donut shaped mapping.  It assumes that a 
torus of major radius 1 sits at the origin in the X-Z plane.  The image is 
wrapped around similar to spherical or cylindrical maps.  However the top 
and bottom edges of the map wrap over and under the torus where they meet 
each other on the inner rim.

Types 3 and 4 are still under development.

Note: The "map_type" option may also be applied to bump_map and 
material_map statements.

To make all or part of an image map transparent, you can specify filter 
values for the color palette/registers of GIF or IFF pictures (at least for 
the modes that use palettes/color maps). You can do this by adding the 
keyword "filter" following the filename.  The keyword is followed by two 
numbers.  The first number is the palette/register number value and 2nd is 
the amount of transparency. The values should be separated by a comma.  For 
example:

   image_map { 
     gif "mypic.gif"
     map_type 0 
     filter 0, 0.5 // Make color 0 50% transparent
     filter 5, 1.0 // Make color 5 100% transparent
     filter 8, 0.3 // Make color 8 30% transparent
    }

You can give the entire image a filter value using "filter all VALUE".  For 
example:

   image_map { 
     gif "stnglass.gif"
     map_type 0 
     filter all 0.9
    }

NOTE: Transparency works by filtering light by its original color.  Adding 
"filter" to the color black still leaves you with black no matter how high 
the filter value is. If you want a color to be clear, add filter 1 to the 
color white.

Adding the "interpolate" keyword can smooths the jagged look of an image or 
bump map.  When POV-Ray asks a color or bump amount for an image or bump 
map, it often asks for a point that is not directly on top of one pixel, 
but sort of between several different colored pixels.  Interpolations 
returns an "in-between" value so that the steps between the pixels in the 
image or bump map will look smoother.

There are currently two types of interpolation:

   Normalized Distance -- interpolate 4
   Bilinear            -- interpolate 2

Default is no interpolation. Normalized distance is the slightly faster of 
the two, bilinear does a better job of picking the between color. Normally, 
bilinear is used.

If your bump or image map looks jaggy, try using interpolation instead of 
going to a higher resolution image.  The results can be very good.  For 
example:

   image_map { 
     gif "mypic.gif"
     map_type 0 
     interpolate 2
    }

After specifying the pigment type such as marble, wood etc and adding an 
optional color map, you may add any of several modifiers.

The keyword "turbulence" followed by a float or vector may be used to stir 
up the color pattern.  Typical values range from the default 0.0 which is 
no turbulence to 1.0 which is very turbulent.  If a vector is specified 
then different amounts of turbulence are applied in the x, y and z 
directions.  For example "turbulence <1.0, 0.6, 0.1>" has much turbulence 
in the x direction, a moderate amount in the y direction and a small amount 
in the z direction.

Turbulence uses a noise function called DNoise.  This is sort of like noise 
used in the bozo pattern except that instead of giving a single value it 
gives a direction. You can think of it as the direction that the wind is 
blowing at that spot.

Turbulence which uses DNoise to push a point around a few times.  We locate 
the point we want to color (P), then push it around a bit using turbulence 
to get to a final point (Q) then look up the color of point Q in our 
ordinary boring textures. That's the color that's used for the point P.

It in effect says "Don't give me the color at this spot... take a few 
random steps in a different direction and give me that color.  Each step is 
typically half as long as the one before.  For example:

         P ------------------------->
                  First Move        /
                                   /
                                  /
                                 /Second
                                /  Move
                               /
                        ______/
                        \
                         \
                          Q - Final point.


The magnitude of these steps is controlled by the turbulence value.

The number of steps used by turbulence is controlled by the "octaves" 
value.  The values may range from 1 up to 10.  The default value of 
"octaves 6" is fairly close to the upper limit; you won't see much change 
by setting it to a higher value because the extra steps are too small.  You 
can achieve some very interesting wavy effects by specifying lower values. 
Setting octaves higher can slow down rendering because more steps are 
computed.

The keyword "omega" followed by a float value may be added to change the 
turbulence calculations.  Each successive octave of turbulence is 
multiplied by the omega value. The default "omega 0.5" means that each 
octave is 1/2 the size of the previous one.  Higher omega values mean that 
2nd, 3rd, 4th and up octaves contribute more turbulence giving a sharper, 
"krinkly" look while smaller omegas give a fuzzy kind of turbulence that 
gets blury in places.

The lambda parameter controls how statistically different the random move 
of an octave is compared to its previous octave.  The default value for 
this is "lambda 2".  Values close to lambda 1.0 will straighten out the 
randomness of the path in the diagram above.  Higher values can look more 
"swirly" under some circumstances.  More tinkering by POV-Ray users may 
lead us to discover ways to make good use of this parameter.  For now just 
tinker and enjoy.

When developing POV-Ray scenes its often useful to do low quality test runs 
that render faster.  The +Q command line switch can be used to turn off 
some time consuming color pattern and lighting calculations to speed things 
up.  However all settings of +Q5 or lower turns off pigment calculations 
and creates gray objects.

By adding a "quick_color" to a pigment you tell POV-Ray what solid color to 
use for quick renders instead of a patterned pigment.  For example:

   pigment {
     gradient x
     color_map{
       [0 color Yellow][0.3 color Cyan][0.6 color Magenta][1 color Cyan]
     }
     turbulence 0.5  lambda 1.5  omega 0.75  octaves 8
     quick_color Neon_Pink
   }

This tells POV-Ray to use solid Neon_Pink for test runs at quality +Q5 or 
lower but to use the turbulent gradient pattern for rendering at +Q6 and 
higher.

Note that solid color pigments such as:

   pigment {color Magenta}

automatically set the quick_color to that value.  You may override this if 
you want.  Suppose you have 10 spheres on the screen and all are Yellow.  
If you want to identify them individually you could give each a different 
quick_color like this:

   sphere {<1,2,3>,4 pigment {color Yellow  quick_color Red}}

   sphere {<-1,-2,-3>,4 pigment {color Yellow  quick_color Blue}}

 ...and so on.  At +Q6 or higher they will all be Yellow but at +Q5 or 
lower each would be different colors so you could identify them.

The frequency and phase keywords were originally intended for the normal 
patterns ripples and waves discussed in the next section.  With version 2.0 
they were extended to pigments to make the radial and mandel pigment 
pattern easier to use.  As it turned out it was simple to make them apply 
to any color map pattern.

The frequency keyword adjusts the number of times that a color map repeats 
over one cycle of a pattern.  For example gradient x covers color map 
values 0 to 1 over the range x=0 to x=1.  By adding "frequency 2" the color 
map repeats twice over that same range.  The same effect can be achieved 
using "scale x*0.5" so the frequency keyword isn't that useful for patterns 
like gradient. 

However the radial pattern wraps the color map around the +Y axis once.  If 
you wanted two copies of the map (or 3 or 10 or 100) you'd have to build a 
bigger map.  Adding "frequency 2" causes the color map to be used twice per 
revolution.  Try this:

      sphere {<0,0,0>,3
        pigment { 
          radial
          color_map{[0.5 color Red][0.5 color White]}
          frequency 6
        }
        rotate -x*90
      }

The result is 6 sets of red and white radial stripes evenly spaced around 
the sphere.

Note "frequency -1" reverses the entries in a color_map.

The phase keyword takes values from 0.0 to 1.0 and rotates the color map 
entries.  In the example above if you render successive frames at phase 0 
then phase 0.1, phase 0.2 etc you could create an animation that rotates 
the stripes.  The same effect can be easily achieved by rotating the radial 
pigment using "rotate y*Angle" but there are other uses where phase can be 
handy.  

Sometimes you create a great looking gradient or wood color map but you 
want the grain slightly adjusted in or out.  You could re-order the color 
map entries but that's a pain.  A phase adjustment will shift everything 
but keep the same scale.  Try animating a mandel pigment for a color 
palette rotation effect.

You may modify pigment patterns with "translate", "rotate" and "scale" 
commands.  Note that placing these transforms inside the texture but 
outside the pigment will transform the entire texture.  However placing 
them inside the pigment transforms just the pigment.  For example:

      sphere {<0,0,0>,3
        texture {
          pigment { 
            checker color Red color White
            scale <2,1,3>  // affects pigment only... not normal
          }
          normal {
            bumps 0.3
            scale 0.4      // affects bump normal only... not pigment
          }
          finish {Shiny}
          translate 5*x    // affects entire texture
        }
        translate y*2      // affects object and texture
      }

Note that transforms affect the entire pigment regardless of the ordering 
of other parameters.  For example:

  This...                         ...is the same as this...

     pigment {                          pigment {                    
       bozo                               bozo                       
       turbulence 0.3                     scale 2                              
       scale 2                            turbulence 0.3   
     }                                  }                            

The scaling before or after turbulence makes no difference.  In general it 
is best to put all transformations last for the sake of clarity.

Ray tracing is known for the dramatic way it depicts reflection, refraction 
and lighting effects.  Much of our perception depends on the reflective 
properties of an object.  Ray tracing can exploit this by playing tricks on 
our perception to make us see complex details that aren't really there.

Suppose you wanted a very bumpy surface on the object.  It would be very 
difficult to mathematically model lots of bumps.  We can however simulate 
the way bumps look by altering the way light reflects off of the surface.  
Reflection calculations depend on a vector called a "surface normal" 
vector.  This is a vector which points away from the surface and is 
perpendicular to it.  By artificially modifying (or perturbing) this normal 
vector you can simulate bumps.  

The "normal {...}" statement is the part of a texture which defines the 
pattern of normal perturbations to be applied to an object.  Like the 
pigment statement, you can omit the surrounding texture block to save 
typing.  Do not forget however that there is a texture implied. For 
example...

 this...                        can be shortened to this...

  object {                           object {                   
    My_Object                          My_Object                
    texture {                          pigment {color Purple} 
      pigment {color Purple}           normal {bumps 0.3}                        
      normal {bumps 0.3}             }
    }                                  
  }                                                           

Note that attaching a normal pattern does not really modify the surface.  
It only affects the way light reflects or refracts at the surface so that 
it looks bumpy.

The most complete form for defining a normal is as follows:

  normal {
    NORMAL_IDENTIFIER
    NORMAL_PATTERN_TYPE
    NORMAL_MODIFIERS
    TRANSFORMATIONS...
  }

Each of the items in a normal are optional but if they are present, they 
should be in the order shown above to insure that the results are as 
expected.  Any items after the NORMAL_IDENTIFIER modify or override 
settings given in the IDENTIFIER.  If no identifier is specified then the 
items modify the normal values in the current default texture.  
TRANSFORMATIONs are translate, rotate and scale statements.  They apply 
only to the normal and not to other parts of the texture.  They should be 
specified last.

There are 6 different NORMAL_PATTERN_TYPEs discussed below.  They are 
bumps, dents, ripples, waves, wrinkles and bump_map.  

A smoothly rolling random pattern of bumps can be created with the "bumps" 
normal pattern.  Bumps uses the same random noise function as the bozo and 
spotted pigment patterns, but uses the derived value to perturb the surface 
normal or, in other words, make the surface look bumpy. This gives the 
impression of a "bumpy" surface, random and irregular, sort of like an 
orange. 

After the bumps keyword, you supply a single floating point value for the 
amount of surface perturbation.  Values typically range from 0.0 (No Bumps) 
to 1.0 or greater (Extremely Bumpy). For example:

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {color Yellow}  
          normal {bumps 0.4   scale 0.2}
          finish {phong 1}
        }
      }

This tells POV-Ray to use a bump pattern to modify the surface normal.  The 
value 0.4 controls the apparent depth of the bumps.  Usually the bumps are 
about 1 unit wide which doesn't work very well with a sphere of radius 2.  
The scale makes the bumps 1/5th as wide but does not affect their depth. 

The "dents" pattern is especially interesting when used with metallic 
textures, it gives impressions into the metal surface that look like dents 
have been beaten into the surface with a hammer. A single value is supplied 
after the dents keyword to indicate the amount of denting required. Values 
range from 0.0 (Showroom New) to 1.0 (Insurance Wreck). Scale the pattern 
to make the pitting more or less frequent.

The ripples bump pattern make a surface look like ripples of water. The 
ripples option requires a value to determine how deep the ripples are.  
Values range from 0.0 to 1.0 or more.  The ripples radiate from 10 random 
locations inside the unit cube area <0,0,0> to <1,1,1>.  Scale the pattern 
to make the centers closer or farther apart.  

The frequency keyword changes the spacing between ripples.  The phase 
keyword can be used to move the ripples outwards for realistic animation.

This works in a similar way to ripples except that it makes waves with 
different frequencies. The effect is to make waves that look more like deep 
ocean waves.  The waves option requires a value to determine how deep the 
waves are.  Values range from 0.0 to 1.0 or more.  The waves radiate from 
10 random locations inside the unit cube area <0,0,0> to <1,1,1>.  Scale 
the pattern to make the centers closer or farther apart.  

The frequency keyword changes the spacing between waves.  The phase keyword 
can be used to move the waves outwards for realistic animation.

This is sort of a 3-D bumpy granite. It uses a similar 1/f fractal noise 
function to perturb the surface normal in 3-D space. With a transparent 
color pattern, could look like wrinkled cellophane. Requires a single value 
after the wrinkles keyword to indicate the amount of wrinkling desired. 
Values from 0.0 (No Wrinkles) to 1.0 (Very Wrinkled) are typical. 

When all else fails and none of the above normal pattern types meets your 
needs, you can use a bump map to wrap a 2-D bit-mapped bump pattern around 
your 3-D objects.

Instead of placing the color of the image on the shape like an image_map, 
bump_map perturbs the surface normal based on the color of the image at 
that point. The result looks like the image has been embossed into the 
surface.  By default, bump_map uses the brightness of the actual color of 
the pixel. Colors are converted to gray scale internally before calculating 
height.  Black is a low spot, white is a high spot. The image's index 
values may be used instead (see use_index) below.  

The syntax for bump_map is...

  normal {
    bump_map {
      FILE_TYPE "filename"
      MODIFIERS...
    }
  }

Where FILE_TYPE is one of the following keywords "gif", "tga", "iff" or 
"dump".  This is followed by the name of the file in quotes.  Several 
optional modifiers may follow the file specification.  The modifiers are 
described below.  Note: Earlier versions of POV-Ray allowed some modifiers 
before the FILE_TYPE but that syntax is being phased out in favor of the 
syntax described here.

Filenames specified in the bump_map statements will be searched for in the 
home (current) directory first, and if not found, will then be searched for 
in directories specified by any "-L" (library path) options active. This 
would facilitate keeping all your bump maps files in a separate 
subdirectory, and giving an "-L" option on the command line to where your 
library of bump maps are. 

By default, the bump is mapped onto the X-Y plane.  The bump is "projected" 
onto the object as though there were a slide projector somewhere in the -Z 
direction.  The bump exactly fills the square area from x,y coordinates 
(0,0) to (1,1) regardless of the bump's original size in pixels.  If you 
would like to change this default, you may translate, rotate or scale the 
normal or texture to map it onto the object's surface as desired. 

If you would like to change this default orientation, you may translate, 
rotate or scale the normal or texture to map it onto the object's surface 
as desired. 

The relative bump_size can be scaled using bump_size modifier. The 
bump_size number can be any number other than 0. Valid numbers are 2, .5, 
-33, 1000, etc. For example:

  normal {
    bump_map { 
      gif "stuff.gif" 
      bump_size 5
    }
  }

Usually the bump_map converts the color of the pixel in the map to a 
grayscale intensity value in the range 0.0 to 1.0 and calculates the bumps 
based on that value.  If you specify use_index, bump_map uses the color's 
palette number to compute as the height of the bump at that point. So, 
color #0 would be low and color #255 would be high. The actual color of the 
pixels doesn't matter when using the index.  The "use_color" keyword may be 
specified to explicitly note that the color methods should be used instead.

Normally there are an infinite number of repeating bump_maps created over 
every unit square of the X-Y plane like tiles.  By adding the keyword 
"once" after a file name, you can eliminate all other copies of the 
bump_map except the one at (0,0) to (1,1).  Areas outside this unit square 
are treated as fully transparent.

Note: The "once" keyword may also be used with image_map and material_map 
statements.

The default projection of the bump onto the X-Y plane is called a "planar 
map type".  This option may be changed by adding the "map_type" keyword 
followed by a number specifying the way to wrap the bump around the object.

A "map_type 0" gives the default planar mapping already described.

A "map_type 1" is a spherical mapping.  It assumes that the object is a 
sphere of any size sitting at the origin.  The Y axis is the north/south 
pole of the spherical mapping.  The top and bottom edges of the bump_map 
just touch the pole regardless of any scaling.  The left edge of the 
bump_map begins at the positive X axis and wraps the pattern around the 
sphere from "west" to "east" in a -Y rotation.  The pattern covers the 
sphere exactly once.  The "once" keyword has no meaning for this type.

With "map_type 2" you get a cylindrical mapping.  It assumes that a 
cylinder of any diameter lies along the Y axis.  The bump pattern wraps 
around the cylinder just like the spherical map but remains 1 unit tall 
from y=0 to y=1.  This band of bumps is repeated at all heights unless the 
"once" keyword is applied.

Finally "map_type 5" is a torus or donut shaped mapping.  It assumes that a 
torus of major radius 1 sits at the origin in the X-Z plane.  The bump 
pattern is wrapped around similar to spherical or cylindrical maps.  
However the top and bottom edges of the map wrap over and under the torus 
where they meet each other on the inner rim.

Types 3 and 4 are still under development.

Note: The "map_type" option may also be applied to image_map and 
material_map statements.

Adding the "interpolate" keyword can smooths the jagged look of a bump map.  
When POV-Ray asks bump amount for a bump map, it often asks for a point 
that is not directly on top of one pixel, but sort of between several 
different colored pixels.  Interpolations returns an "in-between" value so 
that the steps between the pixels in the bump map will look smoother.

There are currently two types of interpolation:

   Normalized Distance -- interpolate 4
   Bilinear            -- interpolate 2

Default is no interpolation. Normalized distance is the slightly faster of 
the two, bilinear does a better job of picking the between color. Normally, 
bilinear is used.

If your bump map looks jaggy, try using interpolation instead of going to a 
higher resolution image.  The results can be very good.

After specifying the normal type such as bumps, dents etc you may add any 
of several modifiers.

The keyword "turbulence" followed by a float or vector may be used to stir 
up the color pattern.  Typical values range from the default 0.0 which is 
no turbulence to 1.0 which is very turbulent.  If a vector is specified 
then different amounts of turbulence is applied in the x, y and z 
directions.  For example "turbulence <1.0, 0.6, 0.1>" has much turbulence 
in the x direction, a moderate amount in the y direction and a small amount 
in the z direction.

A complete discussion of turbulence is given under Pigment Modifiers in 
section 5.4.1.5 above.  The "octaves", "omega", and "lambda" options are 
also available as normal modifiers.  They discussed under that section as 
well.

Both waves and ripples respond to a parameter called phase. The phase 
option allows you to create animations in which the water seems to move. 
This is done by making the phase increment slowly between frames. The range 
from 0.0 to 1.0 gives one complete cycle of a wave.

The waves and ripples textures also respond to a parameter called 
frequency. If you increase the frequency of the waves, they get closer 
together. If you decrease it, they get farther apart. 

Bumps, dents, wrinkles and bump_map do not respond to frequency or phase.

You may modify normal patterns with "translate", "rotate" and "scale" 
commands.  Note that placing these transforms inside the texture but 
outside the normal will transform the entire texture.  However placing them 
inside the normal transforms just the normal.  See section 5.4.1.5.7 
Transforming Pigments for examples:

The finish properties of a surface can greatly affect its appearance.  How 
does light reflect?  What happens when light passes through?  What kind of 
highlights are visible.  To answer these questions you need a finish 
statement.

The "finish {...}" statement is the part of a texture which defines the 
various finish properties to be applied to an object.  Like the pigment or 
normal statement, you can omit the surrounding texture block to save 
typing.  Do not forget however that there is a texture implied. For 
example...

 this...                        can be shortened to this...

  object {                           object {                   
    My_Object                          My_Object                
    texture {                          pigment {color Purple} 
      pigment {color Purple}           finish {phong 0.3}                        
      finish {phong 0.3}             }
    }                                  
  }                                                           

The most complete form for defining a finish is as follows:

  finish {
    FINISH_IDENTIFIER
    FINISH_ITEMS...
  }

The FINISH_IDENTIFIER is optional but should proceed all other items.  Any 
items after the FINISH_IDENTIFIER modify or override settings given in the 
IDENTIFIER.  If no identifier is specified then the items modify the finish 
values in the current default texture.  Note that transformations are not 
allowed inside a finish because finish items cover the entire surface 
uniformly.  

When light reflects off of a surface, the laws of physics say that it 
should leave the surface at the exact same angle it came in.  This is 
similar to the way a billiard ball bounces off a bumper of a pool table.  
This perfect reflection is called "specular" reflection.  However only very 
smooth polished surfaces reflect light in this way.  Most of the time, 
light reflects and is scattered in all directions by the roughness of the 
surface.  This scattering is called "diffuse reflection" because the light 
diffuses or spreads in a variety of directions.  It accounts for the 
majority of the reflected light we see.

In the real world, light may come from any of three possible sources.  1)It 
can come directly from actual light sources which are illuminating an 
object.  2)It can bounce from other objects such as mirrors via specular 
reflection.  For example shine a flashlight onto a mirror.  3)It can bounce 
from other objects via diffuse reflections. Look at some dark area under a 
desk or in a corner.  Even though a lamp may not directly illuminate that 
spot you can still see a little bit because light comes from diffuse 
reflection off of nearby objects.

POV-Ray and most other ray tracers can only simulate directly, one of these 
three types of illumination.  That is the light which comes directly from 
the light source which diffuses in all directions.  The keyword "diffuse" 
is used in a finish statement to control how much light of this direct 
light is reflected via diffuse reflection.  For example:

      finish {diffuse 0.7}

means that 70% of the light seen comes from direct illumination from light 
sources.  The default value is diffuse 0.6.

The amount of direct light that diffuses from an object depends upon the 
angle at which it hits the surface.  When light hits at a shallow angle it 
illuminates less.  When it is directly above a surface it illuminates more.  
The "brilliance" keyword can be used in a finish statement to vary the way 
light falls off depending upon the angle of incidence.  This controls the 
tightness of the basic diffuse illumination on objects and slightly adjusts 
the appearance of surface shininess.  Objects may appear more metallic by 
increasing their brilliance. The default value is 1.0. Higher values from 
3.0 to about 10.0 cause the light to fall off less at medium to low angles.  
There are no limits to the brilliance value. Experiment to see what works 
best for a particular situation. This is best used in concert with 
highlighting.

Very rough surfaces, such as concrete or sand, exhibit a dark graininess in 
their apparent color.  This is caused by the shadows of the pits or holes 
in the surface.  The "crand" keyword can be added to cause a minor random 
darkening the diffuse reflection of direct illumination.  Typical values 
range from "crand 0.01" to "crand 0.5" or higher.  The default value is 0.  
For example:

      finish {crand 0.05}

The grain or noise introduced by this feature is applied on a pixel-by-
pixel basis.  This means that it will look the same on far away objects as 
on close objects.  The effect also looks different depending upon the 
resolution you are using for the rendering.  For these reasons it is not a 
very accurate way to model the rough surface effect, but some objects still 
look better with a little crand thrown in.

In previous versions of POV-Ray there was no "crand" keyword.  Any lone 
float value found inside a texture{...} which was not preceded by a keyword 
was interpreted as a randomness value.

NOTE: This should not be used when rendering animations.  This is the one 
of a few truly random features in POV-Ray, and will produce an annoying 
flicker of flying pixels on any textures animated with a "crand" value.
       

The light you see in dark shadowed areas comes from diffuse reflection off 
of other objects.  This light cannot be directly modeled using ray tracing.  
However we can use a trick called "ambient lighting" to simulate the light 
inside a shadowed area.  

Ambient light is light that is scattered everywhere in the room. It bounces 
all over the place and manages to light objects up a bit even where no 
light is directly shining.  Computing real ambient light would take far too 
much time, so we simulate ambient light by adding a small amount of white 
light to each texture whether or not a light is actually shining on that 
texture.

This means that the portions of a shape that are completely in shadow will 
still have a little bit of their surface color. It's almost as if the 
texture glows, though the ambient light in a texture only affects the shape 
it is used on. 

The default value is very little ambient light (0.1). The value can range 
from 0.0 to 1.0.  Ambient light affects both shadowed and non-shadowed 
areas so if you turn up the ambient value you may want to turn down the 
diffuse value.

Note that this method doesn't account for the color of surrounding objects.  
If you walk into a room that has red walls, floor and ceiling then your 
white clothing will look pink from the reflected light.  POV-Ray's ambient 
shortcut doesn't account for this.  There is also no way to model specular 
reflected indirect illumination such as the flashlight shining in a mirror.

When light does not diffuse and it DOES reflect at the same angle as it 
hits an object, it is called "specular reflection".  Such mirror-like 
reflection is controlled by the "reflection" keyword in a finish statement.  
For example:

      finish {reflection 1.0  ambient 0  diffuse 0}

This gives the object a mirrored finish. It will reflect all other 
elements in the scene.  The value can range from 0.0 to 1.0. By default 
there is no reflection.

Adding reflection to a texture makes it take longer to render because an 
additional ray must be traced.  

NOTE: Although such reflection is called "specular" it is not controlled by 
the POV-Ray "specular" keyword.  That keyword controls a "specular" 
highlight.

A highlights are the bright spots that appear when a light source reflects 
off of a smooth object.  They are a blend of specular reflection and 
diffuse reflection.  They are specular-like because they depend upon 
viewing angle and illumination angle.  However they are diffuse-like 
because some scattering occurs.  In order to exactly model a highlight you 
would have to calculate specular reflection off of thousands of microscopic 
bumps called micro facets.  The more that micro facets are facing the 
viewer, the shinier the object appears, and the tighter the highlights 
become. POV-Ray uses two different models to simulate highlights without 
calculating micro facets.  They are the specular and phong models.

Note that specular and phong highlights are NOT mutually exclusive. It is 
possible to specify both and they will both take effect. Normally, however, 
you will only specify one or the other.

The "phong" keyword controls the amount of Phong highlighting on the 
object.  It causes bright shiny spots on the object that are the color of 
the light source being reflected.

The Phong method measures the average of the facets facing in the mirror 
direction from the light sources to the viewer. 

Phong's value is typically from 0.0 to 1.0, where 1.0 causes complete 
saturation to the light source's color at the brightest area (center) of 
the highlight. The default phong 0.0 gives no highlight.

The size of the highlight spot is defined by the phong_size value.  The 
larger the phong_size, the tighter, or smaller, the highlight and the 
shinier the appearance. The smaller the phong_size, the looser, or larger, 
the highlight and the less glossy the appearance.

Typical values range from 1.0 (Very Dull) to 250 (Highly Polished) though 
any values may be used. Default phong_size is 40 (plastic) if phong_size is 
not specified.  For example:

      finish {phong 0.9  phong_size 60}

If "phong" is not specified then "phong_size" has no effect.

A specular highlight is very similar to Phong highlighting, but uses 
slightly different model.  The specular model more closely resembles real 
specular reflection and provides a more credible spreading of the 
highlights occur near the object horizons. 

Specular's value is typically from 0.0 to 1.0, where 1.0 causes complete 
saturation to the light source's color at the brightest area (center) of 
the highlight. The default specular 0.0 gives no highlight.

The size of the spot is defined by the value given for roughness.  Typical 
values range from 1.0 (Very Rough -- large highlight) to 0.0005 (Very 
Smooth -- small highlight). The default value, if roughness is not 
specified, is 0.05 (Plastic).

It is possible to specify "wrong" values for roughness that will generate 
an error when you try to render the file. Don't use 0 and if you get 
errors, check to see if you are using a very, very small roughness value 
that may be causing the error.  For example:

      finish {specular 0.9  roughness 0.02}

If "specular" is not specified then "roughness" has no effect.

The keyword "metallic" may be used with phong or specular highlights.  This 
keyword indicates that the color of the highlights will be filtered by the 
surface color instead of directly using the light_source color. Note that 
the keyword has no numeric value after it.  You either have it or you 
don't.  For example:

      finish {phong 0.9  phong_size 60  metallic}

If "phong" or "specular" is not specified then "metallic" has no effect.

When light passes through a surface either into or out of a dense medium, 
the path of the ray of light is bent.  Such bending is called refraction.  
Normally transparent or semi-transparent surfaces in POV-Ray do not refract 
light.  Adding "refraction 1.0" to the finish statement turns on 
refraction.  

Note: It is recommended that you only use "refraction 0" or "refraction 1".  
Values in between will darken the refracted light in ways that do not 
correspond to any physical property.  Many POV-Ray scenes were created with 
intermediate refraction values before this "bug" was discovered so the 
"feature" has been maintained.  A more appropriate way to reduce the 
brightness of refracted light is to change the "filter" value in the colors 
specified in the pigment statement.  Note also that "refraction" does not 
cause the object to be transparent.  Transparency is only occurs if there 
is a non-zero "filter" value in the color.

The amount of bending or refracting of light depends upon the density of 
the material.  Air, water, crystal, diamonds all have different density and 
thus refract differently.  The "index of refraction" or "ior" value is used 
by scientists to describe the relative density of substances.  The "ior" 
keyword is used in POV-Ray to specify the value.  For example:

      texture {
        pigment { White filter 0.9 }
        finish {
          refraction 1
          ior 1.5
        }
      }

The default ior value of 1.0 will give no refraction.  The index of 
refraction for air is 1.0, water is 1.33, glass is 1.5, and diamond is 2.4. 
The file IOR.INC pre-defines several useful values for ior.

NOTE: If a texture has a filter component and no value for refraction and 
ior are supplied, the renderer will simply transmit the ray through the 
surface with no bending.  In layered textures, the refraction and ior 
keywords MUST be in the last texture, otherwise they will not take effect.

Most textures consist of a single pigment, normal and finish specification 
which applies to the entire surface.  However two special textures have 
been implemented that extend the "checker" and "image_map" concepts to 
cover not just pigment but the entire texture.

This first special texture is the "tiles" texture.  It works just like the 
"checker" pigment pattern except it colors the blocks with entire textures 
rather than solid colors.

The syntax is:

      texture{
        tiles {
          texture {... put in a texture here ... } 
        tile2
          texture {... this is the second tile texture } 
        } 
       // Optionally put translate, rotate or scale here
      }

For example:

    texture{
       tiles {
          texture { Jade }
       tile2
          texture { Red_Marble }
       } 
    }

The textures used in each tile may be any type of texture including more 
tiles or regular textures made from pigment, normal and finish statements.  
Note that no other pigment, normal or finish statements may be added to the 
texture.  This is illegal:

      texture {
        tiles {
          texture {T1}
        tile2
          texture {T2}
        }
        finish {phong 1.0}
      }

The finish must be individually added to each texture.

Note that earlier versions of POV-Ray used only the pigment parts of the 
textures in the tiles.  Normals and finish were ignored.  Also layered 
textures were not supported.  In order to correct these problems the above 
restrictions on syntax were necessary.  This means some POV-Ray 1.0 scenes 
using tiles many need minor modifications that cannot be done automatically 
with the version compatibility mode.

The textures within a tiles texture may be layered but tiles textures do 
don't work as part of a layered texture.

The "material_map" special texture extends the concept of "image_map" to 
apply to entire textures rather than solid colors.  A material_map allows 
you to wrap a 2-D bit-mapped texture pattern around your 3-D objects.

Instead of placing a solid color of the image on the shape like an 
image_map, an entire texture is specified based on the index or color of 
the image at that point.  You must specify a list of textures to be used 
like a "texture palette" rather than the usual color palette.  

When used with mapped file types such as GIF, the index of the pixel is 
used as an index into the list of textures you supply.  For unmapped file 
types such as TGA, the 8 bit value of the red component in the range 0-255 
is used as an index.  

If the index of a pixel is greater than the number of textures in your list 
then the index is taken modulo N where N is the length of your list of 
textures.  

The syntax for material_map is...

      texture {
        material_map {
          FILE_TYPE "filename"
          MODIFIERS...
          texture {...} // First used for index 0
          texture {...} // Second texture used for index 1
          texture {...} // Third texture used for index 2
          texture {...} // Fourth texture used for index 3
                        // and so on for however many used.
        }
        TRANSFORMATION...
      }

If particular index values are not used in an image then it may be 
necessary to supply dummy textures.  It may be necessary to use a paint 
program or other utility to examine the map file's palette to determine how 
to arrange the texture list.

In the syntax above, FILE_TYPE is one of the following keywords "gif", 
"tga", "iff" or "dump".  This is followed by the name of the file in 
quotes.  Several optional modifiers may follow the file specification.  The 
modifiers are described below.  Note: Earlier versions of POV-Ray allowed 
some modifiers before the FILE_TYPE but that syntax is being phased out in 
favor of the syntax described here.

Filenames specified in the material_map statements will be searched for in 
the home (current) directory first, and if not found, will then be searched 
for in directories specified by any "-L" (library path) options active. 
This would facilitate keeping all your material maps files in a separate 
subdirectory, and giving an "-L" option on the command line to where your 
library of material maps are. 

By default, the material is mapped onto the X-Y plane.  The material is 
"projected" onto the object as though there were a slide projector 
somewhere in the -Z direction.  The material exactly fills the square area 
from x,y coordinates (0,0) to (1,1) regardless of the material's original 
size in pixels.  If you would like to change this default, you may 
translate, rotate or scale the normal or texture to map it onto the 
object's surface as desired. 

If you would like to change this default orientation, you may translate, 
rotate or scale the texture to map it onto the object's surface as desired. 

Note that no other pigment, normal or finish statements may be added to the 
texture outside the material_map.  This is illegal:

      texture {
        material_map {
          gif "matmap.gif"
          texture {T1}
          texture {T2}
          texture {T3}
        }
        finish {phong 1.0}
      }

The finish must be individually added to each texture.

Note that earlier versions of POV-Ray allowed such specifications but they 
were ignored.  The above restrictions on syntax were necessary for various 
bug fixes.  This means some POV-Ray 1.0 scenes using material_maps many 
need minor modifications that cannot be done automatically with the version 
compatibility mode.

The textures within a material_map texture may be layered but material_map 
textures do don't work as part of a layered texture.  To use a layered 
texture inside a material_map you must declare it as a texture identifier 
and invoke it in the texture list.

The "once" and "map_type" options may be used with material_maps exactly 
like image_map or bump_map.  The "interpolate" keyword also is allowed but 
it interpolates the map indices rather than the colors.  In most cases this 
results in a worse image instead of a better image.  Future versions will 
fix this problem.

It is possible to create a variety of special effects using layered 
textures.  A layered texture is one where several textures that are 
partially transparent are laid one on top of the other to create a more 
complex texture. The different texture layers show through the transparent 
portions to create the appearance of one texture that is a combination of 
several textures.

You create layered textures by listing two or more textures one right after 
the other. The last texture listed will be the top layer, the first one 
listed will be the bottom layer. All textures in a layered texture other 
than the bottom layer should have some transparency.  For example:

      object {
        My_Object
        texture {T1}  // the bottom layer
        texture {T2}  // a semi-transparent layer
        texture {T3}  // the top semi-transparent layer
      }

In this example T2 shows only where T3 is transparent and T1 shows only 
where T2 and T3 are transparent.

The color of underlying layers is filtered by upper layers but the results 
do not look exactly like a series of transparent surfaces.  If you had a 
stack of surfaces with the textures applied to each, the light would be 
filtered twice: once on the way in as the lower layers are illuminated by 
filtered light and once on the way out.  Layered textures do not filter the 
illumination on the way in.  Other parts of the lighting calculations work 
differently as well.  The result look great and allow for fantastic looking 
textures but they are simply different from multiple surfaces.  See 
STONES.INC in the standard include files for some magnificent layered 
textures.

Note layered textures must use the "texture{...}" wrapped around any 
pigment, normal or finish statements.  Do not use multiple pigment, normal 
or finish statements without putting them inside the texture statement.

Layered textures may be declared.  For example:

      #declare Layered_Examp=
            texture {T1}
            texture {T2}
            texture {T3}

Then invoke it as follows:

      object {
        My_Object
        texture {
          Layer_Examp
          // Any pigment, normal or finish here
          // modifies the bottom layer only.
        }
      }

POV-Ray creates a default texture when it begins processing.  You may 
change those defaults as described below.  Every time you specify a 
"texture{...}" statement, POV-Ray creates a copy of the default texture.  
Anything items you put in the texture statement override the default 
settings.  If you attach a pigment, normal or finish to an object without 
any texture statement then POV-Ray checks to see if a texture has already 
been attached.  If it has a texture then the pigment, normal or finish will 
modify that existing texture.  If no texture has yet been attached to the 
object then the default texture is copied and the pigment, normal or finish 
will modify that texture.

You may change the default texture, pigment, normal or finish using the 
language directive "#default {...}" as follows:

      #default {
        texture {
          pigment {...}
          normal  {...}
          finish  {...}
        }
      }

Or you may change just part of it like this:

      #default {
         pigment {...}
      }

This still changes the pigment of the default texture.  At any time there 
is only one default texture made from the default pigment, normal and 
finish.  The example above does not make a separate default for pigments 
alone.  Note: Special textures tiles and material_map may not be used as 
defaults.

You may change the defaults several times throughout a scene as you wish.  
Subsequent #default statements begin with the defaults that were in effect 
at the time.  If you wish to reset to the original POV-Ray defaults then 
you should first save them as follows:

      //At top of file
      #declare Original_Default = texture {}

later after changing defaults you may restore it with...

      #default {texture {Original_Default}}

If you do not specify a texture for an object then the default texture is 
attached when the object appears in the scene.  It is not attached when an 
object is declared.  For example:

      #declare My_Object=
        sphere{<0,0,0>,1}  // Default texture not applied

      object{My_Object}    // Default texture added here

You may force a default texture to be added by using an empty texture 
statement as follows:

      #declare My_Thing=
        sphere{<0,0,0>,1 texture{}}  // Default texture applied

The original POV-Ray defaults for all items are given throughout the 
documentation under each appropriate section.