What are Levels of Detail?

Meshes inside a DTS file are grouped into detail levels. Detail levels allow the Torque Game Engine to draw different sets of meshes depending on how far away the DTS shape is from the viewer.  This allows you to set up a less detailed version of each mesh to be rendered when the mesh is far enough away that the player can’t tell the difference.  Each detail level has a corresponding pixel width value.  The engine will select an appropriate detail level to draw based on the width of the shape’s overall bounding box in pixels as displayed on the screen.

For visible detail levels, detail level names are in the form "Detailx" where x is an integer (whole number).  The number at the end of the detail level name defines the size at which the detail level should be displayed.  Meshes in a "Detail32" detail level display on the screen in Torque only if the width of the DTS shape's bounding box exceeds 32 pixels. Under normal conditions, only one detail level is displayed in Torque for a DTS shape at any given time.

For example, let’s say that a DTS shape that 3 detail levels “Detail32”, “Detail50”, and “Detail200”.  From where the player is currently standing, the DTS shape is 40 pixels wide.  The engine draws the meshes in the Detail32 detail level.  As the player backs away from the DTS shape, the shape's width drops below 32 pixels on the screen. When this happens, the DTS shape disappears; since there is no detail level with a pixel value lower than 32, no detail level will be drawn when the shape drops below 32 pixels in width.  As the player approaches the object again, the pixel width goes up to 50.  At this point, the engine starts drawing the meshes in the “Detail50” detail level.  When the pixel width rises above 200, the meshes in the “Detail200” detail level will be drawn.

Both TGE and TGEA have some inconsistencies in the formula that is used to calculate the width of objects on the screen, so the width value is not exact.  In many cases, it's not even close.  Trial and error is pretty much the only way to tell when the detail level switching is acceptable.  Different screen resolutions and geometries, widescreen vs 4:3 modes for example, may cause the detail level switching to change in unpredictable ways.

Defining Levels of Detail in Blender

Detail levels are defined through the use of Blender's scene layers which are assigned to a specific detail level in the Detail Levels panel of the exporter user interface.

Special detail levels

There are several special types of detail levels recognized by the Torque Game Engine.

Collision and LOSCollision detail levels

Collision with DTS shapes in Torque is handled through the use of special collision meshes.  Collision meshes must be closed and convex (rustycode.com) in order to function properly in Torque.  These meshes are stored in special non-rendering collision detail levels.  Any number of collision meshes may be placed in a single collision detail level, and multiple collision detail levels can be used.  Each convex collision mesh should be a separate Blender object, and collision mesh names should start with "col" (for example "ColMesh1", "collisionMesh", etc).  Collision detail levels have a negative size number to indicate that they will not render in the Torque game engine.

LOSCollision detail levels are special collision detail levels that are used for ray casts (projectile collisions, etc).   Under normal circumstances, raycasts are handled by the ordinary collision detail levels, the same as any other type of collision test.  By adding a LOSCollision detail level, you are telling Torque to override the collision meshes in the corresponding collision detail level for raycast tests only.  This can be useful if you want to allow a player to pass through an object or area of an object, but not projectiles, or vice versa.

A note on Collision and LOSCollision detail level numbers

LOSCollision detail levels will override raycast tests for collision detail levels that have the same number as viewed in the exporter user interface.  For example, a "LOSCollision-1" detail level will override the collision meshes in a "Collision-1" detail level when raycasts are performed.  When multiple collision and LOSCollision detail levels are present, each LOSCollision detail level will override the Collision detail level with the same number, if it exists.  In Torque, the Collision and LOSCollision detail level matching is actually handled using a different offset convention.  The exporter will therefore automatically rename your LOSCollision detail levels upon export to make sure that they actually do have the correct offset and will match up and override the same numbered collision detail level as displayed in the exporter user interface.  This is done as an attempt to hide the confusing convention of Collision and LOSCollision detail level matching from the end user.

Auto-billboard LOD

An Auto-billboard Level of detail, also known as TSLastDetail, is an optional final detail level that is composed of billboard snapshots taken of your model from various directions. Torque will switch to this detail level when the pixel size is below the lowest normal detail level. When this feature is enabled, the exporter writes writes out a flag along with information about the number and angles of snapshots to be taken. The snapshots are actually created by Torque when loading the shape, they are not embedded inside the dts file.  This feature may be enabled on the Shape Options panel of the exporter user interface.

Packing of LOD meshes in DTS Objects

DTS Objects contain one or more versions of a mesh to be displayed in different detail levels.  Each DTS Object must contain either a mesh or a null mesh for each detail level that is present in the DTS File.  The exporter generates null meshes automatically as needed.

Defining DTS Objects across detail levels

DTS Objects group related meshes across detail levels.  A visibility animation that fades out a mesh, for example, will act on all of the meshes that are part of that DTS object, regardless of which detail level they belong to.  Multiple Blender mesh objects are grouped into DTS objects based on their names.  The exporter compares the names of each Blender Mesh object in each detail level, discarding anything after the last "." in the Blender mesh object names.  Blender mesh objects that match each other up to the last "." in the mesh object names are stored within the same DTS Object in the exported DTS file.  If multiple Blender objects in the same detail level all reduce to the same DTS object name, you will receive a warning in the console, and the original (full) Blender object names will be used for each DTS object; It is therefore very important that each Blender object that exists in a given detail level has a name that is unique within that detail level, up to the last "." in the mesh object name.  Failure to heed this warning will result in an inefficient, loosely packed dts file containing extra nodes, dts objects, and animation tracks, as well as a warning in the export log file.

The table below demonstrates how Blender mesh objects with different names in each detail level are matched up and packed inside the exported DTS file.  Items in the table represent Blender mesh objects in different layers that have been assigned to specific detail levels through the exporter user interface.

Below are images of the DTS shape hierarchy corresponding to the above table after export, as viewed in Torque Showtool Pro. 

Note: Torque Showtool pro is a valuable tool for troubleshooting problems with DTS files and for understanding the DTS file format.  I cannot recommend it enough, working without it is like working blind.  If you own a TGE 1.5.x indie or commercial license, you should already have a Showtool pro license included with your purchase.

The meshes contained within a given DTS Object must all be either skinned meshes or standard (rigid) meshes.  The two types cannot be mixed and matched within a single DTS Object.

Defining DTS nodes across detail levels

Nodes are not stored in a detail level.  Node animations affect all detail levels, but each node only exists once within the exported DTS file; no matter how many detail levels are exported.  When the exporter generates object nodes, only the highest detail level versions of each object are examined.  Animations are only looked at for the highest detail level versions of each object.  Object animations for lower detail level versions of objects are ignored.  When using bone nodes contained within a Blender armature object, only one armature is needed for all detail levels; duplicating an armature for each detail level will result in duplicate nodes being exported, and warnings in the export log file.

See also:

• User Interface Overview - Detail Levels Panel
• Overview of the DTS file format
• DTS Meshes - Collision Meshes
• DTS Meshes - LOSCollision Meshes
• DTS Animations - Node Animations - Notes on Levels of Detail
• Tutorial 2 - Adding Multiple Levels of Detail
• Tutorial 3 - Adding Collision Meshes
• Blender Survival Guide - Moving Objects Between Layers