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.

The materials file used by FlightGear is set in the /sim/rendering/materials-files
property.  It is read on startup, and can be reloaded in-sim from the
"Reload Materials" item in the Debug menu.

The materials file consists of one or more <region> elements.  Each <region>
contains one or more geographical <area> elements, defining a rectangle
(lat1/lon1, lat2/lon2), and a set of <material> elements which describes a
single visually distinct terrain material in the FG world which will be used to
render one of more scenery landclasses (for example Grass or Town).  When determining
the material to use for a given landclass at a given lat/lon, the <region> elements
are checked in order and the <condition> element of the materials evaluated.  The
_last_ matching material definition is used.  So more specific regions and materials
definitions should be put towards the bottom of the materials file.

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)

light-edge-spacing-m    : Spacing of lighting in m on the edge of line features in WS30.
light-edge-height-m     : Height of lighting in m above the line feature surface.
light-edge-size-cm      : Size of edge lighting in cm. Default 50cm
light-edge-intensity-cd : Intensity of edge lighting in candela. Default 100.
light-edge-angle-horizontal-deg : Horizontal extent of light. Default 360.
light-edge-angle-vertical-deg : Vertical extent of light. Default 360.
light-edge-color/r ... : Light colour, with r,g,b,a properties.  Default 1.0, resulting in white light

line-feature-tex-x0   : x0 texture coordinate for WS3.0 line features
line-feature-tex-x1   : x1 texture coordinate for WS3.0 line features
line-feature-offset-m : vertical offset of line feature from underlying mesh.  
                        May be used to ensure roads go over rivers

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 : Min. number of floors for a small building. (default 1)
building-small-max-floors : Max. number of floors for a small building. (default 3)

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

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

building-small-min-width-m : Min. width of small buildings. (default 15)
building-small-max-width-m : Max. width of small buildings. (default 60)
building-small-min-depth-m : Min. depth of small buildings. (default 10)
building-small-max-depth-m : Max. depth of small buildings. (default 20)

building-medium-min-width-m : Min. width of medium buildings. (default 25)
building-medium-max-width-m : Max. width of medium buildings. (default 50)
building-medium-min-depth-m : Min. depth of medium buildings. (default 20)
building-medium-max-depth-m : Max. depth of medium buildings. (default 50)

building-large-min-width-m : Min. width of large buildings. (default 50)
building-large-max-width-m : Max. width of large buildings. (default 75)
building-large-min-depth-m : Min. depth of large buildings. (default 50)
building-large-max-depth-m : Max. depth 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)