"track-lod-tree" container

Latest revision as of 06:53, 27 July 2019

The "track-lod-tree" container is a top-level config.txt file entry used by KIND Track.

The container defines a track-lod-tree which describes a binary tree structure. When stitching the track geometry, Trainz breaks the spline up into smaller parts (determined by the track's mesh-length tag) and then parses the track-lod-tree using the current view distance to determine which meshes to use.

This page describes trainz-build 4.5.

[edit] Supported Tags

Each node in the track-lod-tree supports the following tags. Each tag is shown here with its default value.

mesh ""
subdivisions 1
lod-distance 0.0
lod-length 0.0
lod-tessellation-length 0.0
lod-random-bias 0.0
lod-is-surveyor 0
lod-season-index 255
piece-position "none"
high-detail
{
}
low-detail
{
}

Each node may either select a mesh from the "mesh-table" Container, or may branch into two new nodes.

The subdivisions tag indicates that the specified data is to be used for several repeats. Exactly how this affects rendering depends on the node type and is detailed below. Trainz may choose to render only some of the repeats in specific scenarios such as very short track lengths - the details of this should not overly concern the content creator.

[edit] Mesh Node

The mesh node selects a single mesh from the "mesh-table" Container. It does not specify a .IM format file directly - the node always refers to a named mesh in the mesh-table container. A mesh node is an end node - when the tree parsing reaches a mesh node the parsing is complete.

subdivisions 1
mesh "track-lod2"

The subdivisions tag causes the mesh to be repeated the specified number of times.

[edit] Branch Node

The branch node specifies a high-detail and a low-detail path, and provides information for Trainz to choose between them. When the tree parsing reaches a branch node it takes one of the two paths contained in that node.

subdivisions 4
lod-distance 100.0
lod-length 10.0
lod-tessellation-length 6.0
high-detail
{
  ..
}
low-detail
{
  ..
}

Each of the high-detail and low-detail paths is another "track-lod-tree" container, creating the binary tree structure of the container.

[edit] subdivisions

The subdivisions tag causes the current track part to be subdivided into multiple parts, each of which is then passed through the track-lod-tree. Each part may take a separate path through the tree, however they all start at the current tree node and move downward (ie. the parsing does not re-start from the root of the tree.)

[edit] lod-distance

The lod-distance tag provides the distance (in meters) that defines whether the parsing will use the high detail path of the branch node (the current view distance is less than the lod-distance) or the low detail path (the current view distance is greater than the lod-distance). This distance is used as a guideline only, and may be affected by user performance settings.

[edit] lod-length

Track parts are scaled to some extent based on the length of the Track Stretch being generated and the mesh-length tag. The lod-length tag provides a mechanism for forcing the high-detail path for short parts, even when the low-detail path would be appropriate given the distance. Specifically, if the generated geometry will be shorter than the lod-length setting, the high-detail path is chosen. This tag should be used with extreme caution, since it has the potential to ruin the LOD scheme and thus kill performance. This tag should only be used to select between a long (efficient) low detail mesh and multiple short (less efficient) low detail meshes, and never to force a change to an actual high detail mesh.

[edit] lod-tessellation-length

Trainz determines a desired tessellation length based on factors which include the ground bumpiness and the bend angle of the spline.

The lod-tessellation-length tag provides a mechanism for forcing the high-detail path for track parts with high tessellation requirements. The length (m) specified in this tag refers to the distance between tessellation points in the mesh, not to the whole length of the mesh. For example, a lod-tessellation-length of 6.0 indicates that the low-detail path is suitable for tessellation at around six meters, whereas the high-detail path is required for tessellation finer than six meters. The high detail path in this case should generally look identical to the low detail path, but with slightly increased tessellation along the Y-axis. This allows Trainz to increase tessellation without the cost of changing to an actual high detail mesh.

The lod-tessellation-length tag should ideally be used to force a path as deep in the track-lod-tree as possible, as Trainz may refine this data as it progresses through the tree - the more parameters that have been set in stone before tessellation is considered, the more accurate the tessellation process will be.

[edit] lod-random-bias

The lod-random-bias isn't really a LOD scheme but instead allows for random selection between the high or low "detail" paths. At the default setting of 0.0, this has no effect. As the number is raised toward 1.0, the chance of forcing the high "detail" path is increased. At 1.0 or higher, the high detail path would always be chosen. While this tag can be used in tandem with other lod-* tags, the behavior is somewhat arbitrary so this isn't recommended. A value of 0.5 gives a 50% variation between high and low "detail" paths.

[edit] lod-is-surveyor

The lod-is-surveyor isn't really a LOD scheme but instead allows for the display of different meshes in Surveyor (editing mode) versus Driver (gameplay mode.) When set to '1', this tag causes the high "detail" path to be chosen when in editing mode.

[edit] lod-season-index

The lod-season-index isn't really a LOD scheme but instead allows for the display of seasonal meshes. When a specific season index (as per the "Season-selector" container) is specified, this tag causes the high "detail" path to be chosen when that season is current.

Note: It appears that the high "detail" path is not only chosen when the current season is equal but also when it is greater than the season specified in this tag.

[edit] lod-piece-position

This tag was introduced at trainz-build 4.5.

The lod-piece-position isn't really a LOD scheme but instead allows for the display of different meshes at the end of track. If present, valid options include "first", "last", and "first-or-last" which activate the high "detail" path when this mesh is (respectively) the first, last, or either the first or last mesh in the track (ie. the mesh is adjacent to an endcap position, regardless of whether an endcap mesh is present).

[edit] Examples

Here is an exaple of a 2 LOD track-lod-tree container for a Track.  :

track
{
 mesh-length                           20
 
 track-lod-tree
 {
   lod-distance                        250
   
   high-detail
   {
     mesh                              "default-lod0"
   }
   
   low-detail
   {
     mesh                              "default-lod1"
   }
 }
}

The following example illustrates how to use the "Season-selector" container to select a seasonal mesh for a track/spline/road (providing lod-season-index 1 refers to winter):

track
{
 mesh-length                           4
 
 track-lod-tree
 {
   lod-distance                        250
   
   high-detail
   {
       lod-season-index              1
			
	high-detail
	{
		mesh                        "track-lod0w"
	}
			
	low-detail 
	{
		mesh                        "track-lod0"
	}
   }
   
   low-detail
   {
       lod-season-index              1
			
	high-detail
	{
		mesh                        "track-lod1w"
	}
		
 	low-detail
	{
		mesh                        "track-lod1"
	}
   }
 }
}

The following example shows a more complex container, with 4 levels of LOD. Note that in this case the containers are arranged with the lod-distance tags running from highest (furthest) to lowest (nearest) within the tree. Therefore the high-detail paths lead to a branch node, and the low-detail paths lead to a mesh (until the end of the tree, when both paths lead to a mesh). The alternative is to arrange the lod-distance from nearest to furthest, in which case the low-detail paths would lead to a branch node and the high detail paths would lead to a mesh. The choice is up to the content creator, but it is important that the path through the tree is valid. For instance, a container that selected for a lod-distance of 400 could not have a low-detail branch that led to a container with a lod-distance of 200. Whenever the parser takes a low-detail path it expects to find either a mesh, or a container with a greater (further) lod-distance: whenever it takes a high-detail path it expects to find either a mesh, or a container with a lower (nearer) lod-distance.

track
{
  mesh-length                           18
  adjust-cross-section-to-ground        0
 
  track-lod-tree
  {
    lod-distance                        400
    
    high-detail
    {
      subdivisions                      3
      lod-distance                      45
      
      high-detail
      {
        lod-distance                    10
        subdivisions                    2
        
        high-detail
        {
          mesh                          "track-lod0"
        }
        low-detail
        {
          mesh                          "track-lod1"
        }
      }
     
      low-detail
      {
        mesh                            "track-lod2"
      }
    }
   
    low-detail
    {
      mesh                              "track-lod3"
    }
  }
}