View source for M.foliage

[[m.foliage]] is a variation on the [[m.pbrmetal]] material, supported in assets using trainz-build 5.4 and up.

This material is intended for use with the [[Clutter Effect Layer]], and is tuned to suit that purpose to the detriment of any other possible use-case. While it is permissible to use the material with non-clutter asset types (scenery, traincars, etc.), it may result in visual artifacts or errors if configured improperly. We reserve the right to make changes to the behaviour of the material in ways that do not impact negatively on the clutter effect layer usage, even where those changes negatively impact other uses. For this reason, and because performance of an m.foliage asset is likely to be lower than an equivalent m.pbrmetal asset, it is recommended that m.foliage is used for a non-clutter asset only where substantial performance and visual gains are possible which cannot be achieved using other techniques.


m.foliage introduces support for per-vertex procedural wind animation and ground alignment, to be used with clutter effect layers.

NOTE: This material pertains to meshes which require advanced wind animation or ground alignment. If your clutter mesh is intended to be a static object without ground shearing, the [[m.clutter]] material should be used instead.

[[File:Foliage_animation_1.gif|border|middle|x500px]]


All PBR materials are defined using a multitude of texture channels (not just a simple RGB image) which define various aspects of the material on a per-texel basis. One major advantage of this approach is that a single in-game [[material]] can be used to display various different real-world materials, rather than requiring multiple separate in-game materials with different parameters. Trainz uses a Metallic/Roughness style [[Physically Based Rendering|PBR workflow]].

This page describes [["Trainz-build" number|content format v5.4]] and assumes that the [[FBX file format]] is used as a data source for any meshes.

= Mesh Metadata Config =

m.foliage supports several attributes which must be configured through the use of a [[mesh metadata file]].

Listed below are the mesh metadata tags associated with m.foliage, and their meaning.

==clutter-wind-type==

m.foliage supports three wind animation modes, specified by the ''clutter-wind-type'' tag:

===none===
Default behavior. Wind will not affect this material.

===vertex-color===
In this wind mode, the mesh vertex color represents the wind strength multiplier on a per-vertex basis (i.e. how far each vertex is allowed deviate from its initial position in windy conditions).
This is useful for assets such as trees or shrubs, which may need explicit control over how the individual vertices of leaves or branches are permitted to sway in the wind.

The vertex color channels control the following values:

R:
Wind strength factor [0-1].

GBA:
Currently unused. Care should be taken to ensure the green and blue channels remain 0, as they may become used by this material in future.


Authoring vertex color data: TBA

===position-z===
In this wind mode, the vertex Z position is used as the wind strength factor (Higher Z = sways more intensely in the wind).
This is useful for dense meshes, such as grass blades, where the root of each blade should remain fixed in place on the ground while the tips sway fully in the wind.

==clutter-sample-method==

m.foliage supports three ground alignment/shear modes, specified by the ''clutter-sample-method'' tag:

===origin===
Default behavior. No change is made to the vertex position depending on the ground height. This matches existing clutter behavior.

===per-vertex===
In this mode, each vertex will be offset based on the ground height directly below it. For instance, on meshes where all vertices are Z=0, this results in the mesh being projected directly onto the ground geometry.
This mode is useful for large dense ground cover meshes, or 'fake' grass meshes that use a simple billboard card rather than individually modeled blades. These meshes have no discernable 'roots' and thus must deform smoothly and continuously onto the ground rather than discretely.
This mode is NOT recommended for use on meshes featuring individually modeled grass blades. Those meshes should use the ''contiguous-geometry'' mode, documented below.

===contiguous-geometry===
In this mode, vertices will align to the ground intelligently as a group, determined by Trainz based on loose/unconnected geometry within the mesh.
This mode is most useful for grass meshes featuring individually modeled blades. It allows each connected blade in a mesh to snap to the ground as a single unit, preventing distortion effects that would otherwise be caused by rough or noisy ground height.

The contiguous-geometry sample point is determined according to the value of the clutter-geometry-root tag.
clutter-geometry-root can be one of three values:

* bottom - The vertex with the lowest Z position in each sample group is used as the sample location. This is the default behavior, and is the most typical for meshes featuring grass blades.

* top - The vertex with the highest Z position in each sample group is used as the sample location.

* center - The bounding box center of each sample group is used as the sample location.

== Mesh Metadata File Example ==

It is recommended to use the bend-normals-upward-ratio tag with grass meshes using m.foliage, as this allows the grass blades to be more convincingly lit.

<pre>materials
{
    grass.m.foliage
    {
        clutter-sample-method       per-vertex
        clutter-wind-type           position-z
        two-sided                   0
        bend-normals-upward-ratio   1.0			
    }
}
</pre>


=Texture Slots=
The following texture slots are used for this material. All textures should typically have the same dimensions unless they represent a uniform color, however this is not strictly enforced.

==Albedo==
RGB: The [[albedo map]] defines the base color of each texel. The sRGB color space is used.

'''Albedo Texture Example'''

[[File:Grass_12_albedo.png|border|middle|x200px]]

A: The alpha channel provides a greyscale [[blended alpha]] channel. Black indicates full transparency. White indicates full opacity. Mid levels offer partial transparency. If the alpha channel is omitted, this material becomes fully opaque but still suffers from a number of drawbacks, unlike the truly opaque [[m.pbrmetal]]. Note that unlike legacy Trainz materials, PBR materials do not autodetect opacity mode based on the texture in use. The content creator must select the appropriate material for their desired outcome.

'''Alpha Texture Example'''

[[File:Grass_12_alpha.png|border|middle|x200px]]

The full texture is available here: [[File:Grass_12_albedo.tga]]

==Normal==
RGB: Surface [[normal map]]. This defines which way the surface is facing, relative to the interpolated vertex normals. Since this is an XYZ format rather than color data, it should never be modified in Photoshop. Using Photoshop to add a fourth channel or copy/paste smaller textures into a [[texture atlas]] is acceptable. Per-pixel manipulation or use of filters on the "RGB" channels is not acceptable.

'''Normal Texture Example''

[[File:pbrnormalmap1.jpg|border|middle|x200px]]

==Parameter==
This texture is comprised of four separate channels which each form a separate data element. Linear color space (not sRGB) is used for these channels.

[[File:pbrparametersall.jpg|border|middle|x200px]]


R: Emissive. This causes the texture to have an internal glow, even when no external light is present. Used for phosphors, permanently-lit markings, etc. The glow color is based on the albedo. Note that this glow does not cast light upon surrounding surfaces except via the Bloom post-processing effect.


'''Parameters (Emissive - Red Channel) Texture Example'''

[[File:pbrparametersemissivemap1.jpg|border|middle|x200px]]

G: Roughness. Defines whether the surface reflections are shiny (0.0) or matte (1.0). See the [[Physically Based Rendering|PBR metal workflow]] for details.


'''Parameters (Roughness - Green Channel) Texture Example'''

[[File:pbrparametersroughnessmap1.jpg|border|middle|x200px]]

B: Ambient Occlusion. Defines whether the surface is exposed to ambient lighting conditions (1.0) or affected only by direct lighting (0.0).


'''Parameters (Ambient Occlusion - Blue Channel) Texture Example'''

[[File:pbrparametersambientocclusionmap1.jpg|border|middle|x200px]]

A: Metallicity. Defines whether the surface is metallic (1.0) with the albedo used to colorize reflected light, or dielectric (0.0) with the albedo used to colorize the surface. While intermediate values are not physically accurate, they may be used to emulate subsurfaces which are partially metallic. See the [[Physically Based Rendering|PBR metal workflow]] for details.


'''Parameters (Metallic - Alpha Channel) Texture Example'''

[[File:pbrparametersmetallicmap1.jpg|border|middle|x200px]]


=Examples=

[[File:Foliage_blender_crop.png|border|middle|x300px]]
[[File:Foliage_animation_2.gif|border|middle|x300px]]


Example asset (blend + CDP) download:

[https://dl1.n3vgames.com/downloads/content/foliage/m.foliage-grass-12-sample-source.zip Sample asset and source files]