fgdata/Docs/README.materials

README.materials

This README describes the materials.xml file format. It is targeted at those 
wanting to change the appearance of the scenery in FlightGear.

As is the norm in FG, the materials.xml file is a properties file. However,
it is only read on startup, is not part of the main property tree and cannot
be changed at runtime. 

The properties file consists of a number of <material> entries, each of which
describes a single visually distinct terrain material in the FG world. 

The rest of this document describes the children tags of the <material> entry.

name : Scenery type names that map to this material. These are typically taken 
       from landclass definitions created by TerraGear. Multiple scenery types
       may map to a single material. This is recommended to minimize texture
       memory usage.
       
condition : A condition statement used to activate the material. Note that this
       if evaluated once at start-up.
       
texture : A relative path to an SGI RGB, PNG or DDS file containing a texture 
       for the material. RGB and PNG are recommended for platform compatibility.
       You may define more than one <texture> element, in which case the scenery
       loader will choose one texture for each contiguous set of scenery 
       triangles.

texture-set : If using an effect (see below), it may be necessary to define more
       than one texture.  The texture-set element has multiple <texture> element
       children which may then be referenced by the effect. You may define more 
       than one <texture-set> element, in which case the scenery loader will 
       choose one texture for each contiguous set of scenery triangles.
       
object-mask : An optional bitmap file used to control random placement of lights, 
       buildings and vegetation on the terrain.  The green channel mask is used
       for random vegetation placement, the blue channel for buildings and lights.
       and the red channel controls the rotation of buildings (0.0 is North, 0.5
       is South). Fractional colour values can be used to give a probability of 
       placement. Multiple object-masks may be defined to match up with <texture>
       or <texture-set> elements.
       
effect : The effect to be used for this material. (default: 
       Effects/terrain-default)

       ambient, diffuse, specular, emissive, and shininess are copied into the
       parameter section of the effect created for this material.

parameters : Additional parameters to be used in the effect. See README.effects        for format information.

wrapu : True if the texture should repeat horizontally over a surface, false if 
       it should not repeat (default: true).

wrapv : True if the texture should repeat vertically over a surface, false if 
       it should not repeat (default: true).

mipmap : True if the texture should be mipmapped, false otherwise. (default: true).

xsize : The horizontal size of a single texture repetition, in meters.
        
ysize : the vertical size of a single texture repetition, in meters

light-coverage : The coverage of a single point of light in m^2. 0 indicates no
        lights at all. Minimum value is 1000m^2. May be masked by the blue channel
        of an object-mask. Lights are all generated 3m above the surface, and
        have random colour (50% yellow, 35% white, 10% orange, 5% red)
        
ambient : The ambient light colour for the material, specified as separate 
        r, g, b, a components (default: all color components 0.2, alpha 1.0).

diffuse : The diffuse light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.8, alpha 1.0).

specular : The specular light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.0, alpha 1.0).

emissive : The emissive light colour for the material, specified as separate
        r, g, b, a components (default: all color components 0.0, alpha 1.0).

solid : Whether the surface is solid from an FDM perspective. If it is not
        solid, it is assumed that the material models a fluid (water) surface.
        (default: true).

friction-factor : The friction factor for that material. The normalized
        factor can be used by a FDM to post-multiply all contact friction forces
        with that factor. That is the more slippery a material is the smaller this
        value should be. (default: 1.0 for Dry concrete/Asphalt).

rolling-friction : the gear rolling rolling-friction coefficient for this
        particular material. (default: 0.02 for Dry concrete/Asphalt).

bumpiness : normalized bumpiness factor for this particular terrain.
        (default: 0.0 for a smooth surface).

load-resistance : a pressure value how much force per surface area this
        surface can carry without deformation. The value should be in N/m^2
        (default: 1e30).

glyph : group that defines one letter/digit/symbol in a font texture
        sub-entries: name, left (default: 0.0), right (default: 1.0)
        (left and right describe the horizontal position in the texture.)

wood-coverage : The coverage of trees in areas marked as woodland in 
         m^2. A lower number means a higher density of trees. A value of 
         0 indicates no woods. May be masked by the green channel of an
         object-mask. (default: 0)

tree-range-m : The range at which trees become visible. Note that this
         is not absolute, as trees are loaded in blocks. A lower number means
         trees will not become visible until you are closer.

tree-texture : A texture to use for the trees. Typically this will contain around
         8 different trees in a row, duplicate 4 times. From bottom to top, the
         rows contain
         * summer textures
         * summer snow texture
         * winter texture
         * winter snow texture
         
         Each tree must have space at the top. For a 512x512 texture sheet, this
         should be 8 pixels.  Otherwise subsequent rendering results in "top hats" 
         above trees in the distance where the trunk of the tree above in the 
         textures sheet bleeds downwards when the mipmaps are generated.         

tree-varieties : The number of different trees defined in the tree-texture
         horizontally. (default: 1)

tree-height-m : The average height of the trees. Actual tree height will 
         vary by +/- 50%. (default: 0)

tree-width-m : The average width of the tree cover. Actual tree width will 
         vary by +/- 50%. (default 0)
         
tree-max-density-angle-deg : The slope angle at which trees begin to thin out
         as the slope is too steep to support the full coverage. Shallower 
         slopes have maximum wood-coverage.  Steeper slopes have fewer trees.
         (default : 45)
         
tree-zero-density-angle-deg : The angle at which the slope is too steep to 
         support significant vegetation.  Steeper slopes have no trees. 
         (default : 60)

object-max-density-angle-deg : The angle at which objects and buildings become 
         less dense due to a steep slope. (default : 20)

object-zero-density-angle-deg : The angle at which the slope is too steep to build
         on.  No object/buildings will be placed on slopes steeper than this.
         (default : 30)

object-group : A group of random objects to be placed on the surface. Contains
         <range-m> and one or more <object> children.
         
range-m : The distance at which objects within this object-group become 
         visible. Note that for realism, 60% of the objects will become visible
         at <range-m>, 30% at 1.5*<range-m>, and 10% at 2*<range-m>. 
         (default: 2000)
         
object : A set of random objects to be placed. Contains <coverage-m2>, <path>
         and <heading> children.
         
coverage-m2 : The coverage of a single object in m2. Lower values mean a higher
         density. Minimum value is 1000.
         
spacing-m : The minimum space between this object and any other on the surface in
         meters. This helps to avoid objects being placed ontop of each other.
         (default 20)
         
path :   Path relative to FG_ROOT to a model definition, usually .ac or .xml file. 
         More than one <path> may be included within the <object> tag, in which
         case a single <path> is chosen at random for each individual object
         placement.

heading-type : Indicator of how the heading of the random objects should be 
         determined. Valid values are: 
           fixed     - Objects all point North. Default.
           random    - Objects are assigned an individual random heading
           mask      - Rotation is taken from the red channel of the object-mask
           billboard - Object is always rotated to face camera - expensive
           
           
Random Buildings
================

Random Buildings come in three sizes, with individual constraints. 

Small buildings.  These have different textures on the sides compared to the front and back.
Small buildings are never deeper than they are wide.

Medium buildings, which are never taller than they are wide.

Large buildings. There are no constraints on their width, depth or height.
           
building-coverage : The coverage of random buildings in areas marked for random objects in 
         m^2. A lower number means a higher density of buildings. A value of 
         0 indicates no buildings. May be masked by the blue channel of an
         object-mask. (default: 0)            
           
building-spacing-m : The minimum spacing between random buildings and other buildings
         or random objects. This helps avoid objects being placed on top of each other. 
         (default: 5)
         
building-small-ratio: Ratio of small buildings. These buildings are 1-3 stories
         in height, and may have a pitched roof. Fraction of small buildings is
         (<building-ratio-small> / (<building-ratio-small> + <building-ratio-medium>
         + <building-ratio-large>). (default: 0.8)
         
building-medium-ratio : Ratio of medium buildings. These buildings are 3-6 stories in
         height, and have a flat roof. (default: 0.15)
         
building-large-ratio : Ratio of large buildings. These buildings are 5-10 stories in 
         height, and have a flat roof. (default 0.05)
         
building-small-pitch : Fraction of small buildings with pitched roofs. (default 0.8)
building-medium-pitch : Fraction of small buildings with pitched roofs. (default 0.2)
building-large-pitch : Fraction of small buildings with pitched roofs. (default 0.1)

building-small-min-floors : Minimum number of floors for a small building. (default 1)
building-small-max-floors : Maximum number of floors for a small building. (default 3)         

building-medium-min-floors  : Minimum number of floors for a medium building. (default 3)
building-medium-max-floors  : Maximum number of floors for a medium building. (default 8)

building-large-min-floors  : Minimum number of floors for a medium building. (default 5)
building-large-max-floors  : Maximum number of floors for a medium building. (default 20)

building-small-min-width-m : Minimum width of small buildings. (default 15)
building-small-max-width-m : Maximum width of small buildings. (default 60)
building-small-min-depth-m : Minimum depth of small buildings. (default 10)
building-small-max-depth-m : Maximum depty of small buildings. (default 20)

building-medium-min-width-m : Minimum width of medium buildings. (default 25)
building-medium-max-width-m : Maximum width of medium buildings. (default 50)
building-medium-min-depth-m : Minimum depth of medium buildings. (default 20)
building-medium-max-depth-m : Maximum depty of medium buildings. (default 50)

building-large-min-width-m : Minimum width of large buildings. (default 50)
building-large-max-width-m : Maximum width of large buildings. (default 75)
building-large-min-depth-m : Minimum depth of large buildings. (default 50)
building-large-max-depth-m : Maximum depty of large buildings. (default 75)

building-texture : The texture used for all buildings. See Docs/buildings.png for details. 
(default Texture/buildings.png)

building-lightmap: Emissive texture for all buildings, which is faded in at night to provide
illusion of lit windows.  Same texture coordinates and format at building-texture above.

building-range-m: Range at which all buildings are visible.  Beyond this point fewer and fewer
          buildings are rendered, with no buildings rendered at 2*building-range-m (default 10000)