c974f5242d
- Remove trailing whitespace - Replace tabs with spaces - Reformat to < 85 characters to avoid autogenerate readme.pdf bleeding over margins.
251 lines
12 KiB
Text
251 lines
12 KiB
Text
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 : 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)
|