"track-lod-tree" container

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m (1 revision)
(lod-season-index: Added note about lod-season-index tag)
 
(16 intermediate revisions by 6 users not shown)
Line 1: Line 1:
''Warning: This page is a work in progress and any details or metrics included here may change regularly as TS2009 development continues.''
+
The "track-lod-tree" container is a top-level [[config.txt file]] entry used by [[KIND Track]].
  
The "track-lod-tree" container is a top-level [[config.txt file]] entry used by the TS2009 [[Stitched 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.
  
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]] 4.5.
  
  
Line 15: Line 15:
 
  lod-tessellation-length 0.0
 
  lod-tessellation-length 0.0
 
  lod-random-bias 0.0
 
  lod-random-bias 0.0
 +
lod-is-surveyor 0
 +
lod-season-index 255
 +
piece-position "none"
 
  high-detail
 
  high-detail
 
  {
 
  {
Line 24: Line 27:
 
Each node may either select a mesh from the [["mesh-table" Container]], or may branch into two new nodes.
 
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.
+
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.
  
  
 
==Mesh Node==
 
==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.
+
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
 
  subdivisions 1
 
  mesh "track-lod2"
 
  mesh "track-lod2"
Line 36: Line 39:
  
 
==Branch Node==
 
==Branch Node==
The branch node specifies a ''high-detail'' and a ''low-detail'' path, and provides information for Trainz to choose between them.
+
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
 
  subdivisions 4
Line 51: Line 54:
 
  }
 
  }
  
Each of the ''high-detail'' and ''low-detail'' paths is another [["track-lod-tree" container]], causing this structure to be recursive.
+
Each of the ''high-detail'' and ''low-detail'' paths is another [["track-lod-tree" container]], creating the binary tree structure of the container.  
  
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.)
 
  
The ''lod-distance'' tag determines the distance (meters) at which Trainz will swap to using the lower detail path. This distance is a guideline and may be affected by user performance settings.
+
====subdivisions====
  
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.
+
: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.)
  
Trainz determines a desired tessellation length based on factors which include the ground bumpiness and the bend angle of the spline.
+
====lod-distance====
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.
+
: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.
  
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-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'' 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.
 +
 
 +
====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.
 +
 
 +
====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.
 +
 
 +
====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.
 +
 
 +
====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).
  
  
 
==Examples==
 
==Examples==
''TBD''
 
  
[[Category:Config Container]]
+
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"
 +
    }
 +
  }
 +
 +
 
 +
 
 +
[[Category:Config Container|T]]

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.


Contents

[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"
    }
  }
}
Personal tools