"track-lod-tree" container

Revision as of 12:34, 3 August 2016

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

The track-lod-tree is a recursive format 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 to determine which meshes to use.

This page describes trainz-build 3.7.

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
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 overly concern the content creator.

Mesh Node

The mesh node selects a single mesh from the "mesh-table" Container, which is always used. It does not specify a .IM format file directly.

subdivisions 1
mesh "track-lod2"

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

Branch Node

The branch node specifies a high-detail and a low-detail path, and provides information for Trainz to choose between them.

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, causing this structure to be recursive.

subdivisions

The subdivisions tag causes the current track part to be subdivided into multiple parts, which continue to be 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. they do not re-parse from the root of the tree.)

lod-distance

The lod-distance tag determines the maximum distance (meters) at which Trainz will use the high detail path of the tree, before changing to the low detail path. This distance is a guideline and may be affected by user performance settings.

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.

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 branch should ideally be specified 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.

lod-random-bias

The lod-random-bias isn't really a LOD scheme and 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.

lod-is-surveyor

The lod-is-surveyor isn't really a LOD scheme and 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.

lod-season-index

The lod-season-index isn't really a LOD scheme and 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.

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"
	}
   }
 }
}