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>