From f65c50f14ab4f851da5d96b604cc366032faecaa Mon Sep 17 00:00:00 2001
From: Stuart Buchanan <stuart_d_buchanan@yahoo.co.uk>
Date: Wed, 8 Feb 2012 22:56:50 +0000
Subject: [PATCH] README documentation for materials.xml.

---
 Docs/README.materials | 151 ++++++++++++++++++++++++++++++++++++++++++
 materials-dds.xml     | 117 +-------------------------------
 materials.xml         | 117 +-------------------------------
 3 files changed, 153 insertions(+), 232 deletions(-)
 create mode 100644 Docs/README.materials

diff --git a/Docs/README.materials b/Docs/README.materials
new file mode 100644
index 000000000..1544f3585
--- /dev/null
+++ b/Docs/README.materials
@@ -0,0 +1,151 @@
+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.
+
+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 be a
+         strip with multiple tree textures.
+
+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)
+
+object-group : A group of random objects to be placed on the surface. Contains
+         <range-m> and one or mode <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
+           
diff --git a/materials-dds.xml b/materials-dds.xml
index 7a60c03f3..2f0914945 100644
--- a/materials-dds.xml
+++ b/materials-dds.xml
@@ -1,120 +1,5 @@
 <?xml version="1.0"?>
-
-<!--
-************************************************************************
-FlightGear Materials File
-
-This property file configures the materials for FlightGear.  Each
-material describes a single visual appearance in the simulator, which
-can be represented by a colour, a texture, or both.  If a material has
-more than one name, all of the names will be used as aliases for the
-same material: this is often a good idea to save texture memory.
-
-Currently, colours will not be used unless the user disables textures;
-in the future, the program may use textures with an alpha component so
-that it will combine with the colour underneath.
-
-Properties currently used:
-
-  name: A name for the texture (you may provide more than one).  The
-   FlightGear scenery files look up their textures by name.
-
-  texture: A relative path to an SGI RGB file containing a texture for
-    the material.
-
-  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
-    (0, the default, means use the natural size [??]).
-
-  ysize: the vertical size of a single texture repetition, in meters
-    (0, the default, means use the natural size [??]).
-
-  light-coverage: a seed number for generating random night lighting
-    over an area.  A higher number means fewer lights, and 0 means
-    that lighting is disabled.
-
-  ambient: the ambient light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.2, alpha 1.0).
-
-  diffuse: the diffuse light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.8, alpha 1.0).
-
-  specular: the specular light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.0, alpha 1.0).
-
-  emissive: the emissive light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.0, alpha 1.0).
-
-  solid: bool value, if true the surface is solid for an FDM. 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: FLT_MAX).
-
-  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 woods. A value of 
-    0 indicates no woods.
-
-  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 be a
-    strip with multiple tree textures.
-
-  tree-varieties: The number of different trees defined in the tree-texture
-
-  tree-height-m: The average height of the trees cover. Actual tree height
-    will vary by +/- 50%.
-
-  tree-width-m: The average width of the tree cover. Actual tree width
-    will vary by +/- 50%.
-
-  effect - The name of an effect to inherit from. The default is
-    Effects/terrain-default.
-
-  object-mask: png file used as a mask for trees (green channel), buildings
-    (blue channel) and building rotation (red channel). Note that this is
-    used as a mask on the coverage-m2 and wood-coverage values. I.e. the
-    wood-coverage value is used to determine the placement of a number of
-    trees, which are then masked by the object-mask texture.  Partial values
-    are randomly checked against, so a green value of 128 (0.5) means that 
-    if the wood-coverage indicates that a tree is located at that point,
-    it only has a 50% chance of being added. 
-
-   ambient, diffuse, specular, emissive, and shininess are copied into the
-   parameter section of the effect created for this material.
-************************************************************************
--->
+<!-- FlightGear Materials File. See Docs/README.materials for details. -->
 
 <PropertyList>
 
diff --git a/materials.xml b/materials.xml
index a6abcc31c..b4095be5b 100644
--- a/materials.xml
+++ b/materials.xml
@@ -1,120 +1,5 @@
 <?xml version="1.0"?>
-
-<!--
-************************************************************************
-FlightGear Materials File
-
-This property file configures the materials for FlightGear.  Each
-material describes a single visual appearance in the simulator, which
-can be represented by a colour, a texture, or both.  If a material has
-more than one name, all of the names will be used as aliases for the
-same material: this is often a good idea to save texture memory.
-
-Currently, colours will not be used unless the user disables textures;
-in the future, the program may use textures with an alpha component so
-that it will combine with the colour underneath.
-
-Properties currently used:
-
-  name: A name for the texture (you may provide more than one).  The
-   FlightGear scenery files look up their textures by name.
-
-  texture: A relative path to an SGI RGB file containing a texture for
-    the material.
-
-  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
-    (0, the default, means use the natural size [??]).
-
-  ysize: the vertical size of a single texture repetition, in meters
-    (0, the default, means use the natural size [??]).
-
-  light-coverage: a seed number for generating random night lighting
-    over an area.  A higher number means fewer lights, and 0 means
-    that lighting is disabled.
-
-  ambient: the ambient light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.2, alpha 1.0).
-
-  diffuse: the diffuse light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.8, alpha 1.0).
-
-  specular: the specular light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.0, alpha 1.0).
-
-  emissive: the emissive light colour for the material, specified as
-    separate red, green, blue, and alpha components (default: all
-    color components 0.0, alpha 1.0).
-
-  solid: bool value, if true the surface is solid for an FDM. 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: FLT_MAX).
-
-  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.
-
-  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 be a
-    strip with multiple tree textures.
-
-  tree-varieties: The number of different trees defined in the tree-texture
-
-  tree-height-m: The average height of the trees cover. Actual tree height
-    will vary by +/- 50%.
-
-  tree-width-m: The average width of the tree cover. Actual tree width
-    will vary by +/- 50%.
-
-  effect - The name of an effect to inherit from. The default is
-    Effects/terrain-default.
-
-  object-mask: png file used as a mask for trees (green channel), buildings
-    (blue channel) and building rotation (red channel). Note that this is
-    used as a mask on the coverage-m2 and wood-coverage values. I.e. the
-    wood-coverage value is used to determine the placement of a number of
-    trees, which are then masked by the object-mask texture.  Partial values
-    are randomly checked against, so a green value of 128 (0.5) means that 
-    if the wood-coverage indicates that a tree is located at that point,
-    it only has a 50% chance of being added. 
-
-   ambient, diffuse, specular, emissive, and shininess are copied into the
-   parameter section of the effect created for this material.
-************************************************************************
--->
+<!-- FlightGear Materials File. See Docs/README.materials for details. -->
 
 <PropertyList>