Programmatic DTS billboards

Download Code File

Torque DTS shapes support a nifty feature called "billboards". A billboard is a 2-D representation of what the DTS shape looks like when viewed from a long way away. If a DTS shape has billboards turned on, then Torque will render the DTS as a 2-D bitmap (billboard) when the DTS reaches it's lowest detail level. This can can result in huge speed-ups in some cases, since rendering a 2-D bitmap is much faster than rendering a true 3-D shape.

Until now, billboards had to be turned on or off at the time the DTS was exported from an art tool such as Blender, 3D Studio Max, etc. With this resource, you can now turn on billboards in your game rather than in the art tool! It doesn't matter whether the DTS was exported with billboards on or off. You can also turn billboards off for a DTS that originally had them turned on.

API:
The API consists of one Torquescript function:

declareBillboards(shapeName, numEquatorSteps, numPolarSteps, bitmapSize, detailSize, polarAngle=0, includePoles=false, bitmapDetailLevel=0)

Parameters:

shapeName
the path to the .dts file. E.g. "~/data/shapes/trees/ftree01.dts"

numEquatorSteps
the number of intervals around the equator at which to take snapshots.

If this value is zero, declareBillboards() will attempt to turn billboards off rather than turn them on.

numPolarSteps
the number of intervals between the equator and the poles at which to take snapshots.

bitmapSize
the size of the snapshots to take, in pixels. (each snapshot will be bitmapSize x bitmapSize pixels.) This value *must* be a power of 2.

detailSize
the threshold at which to switch to rendering billboards. When the projected screen size of the DTS drops below this value, the DTS will be rendered as a billboard.

polarAngle
special top and bottom viewing angles for the DTS. See next param. Value is in degrees. Defaults to zero.

includePoles
if true, two additional snapshots are taken from directly above & below the DTS. These snapshots will be shown when the viewing angle is within 'polarAngle' degrees from the top or the bottom poles of the shape. Defaults to false.

bitmapDetailLevel
the detail level to use when creating the snapshots, if the DTS has multiple detail levels. Defaults to zero (the highest-poly detail level).

--------

Call declareBillboards() once for each DTS you want to add billboards to. If the DTS was exported with billboards already on, declareBillboards() will override the existing billboard parameters.

IMPORTANT: you must call declareBillboards() early on, before your DTSs get loaded. declareBillboards() creates a table that the DTS loading code reads. If you call declareBillboards() after DTSs are already loaded, it will have no effect.

All the usual caveats of billboards still apply. In particular, watch out for memory consumption. The total number of snapshots for a given DTS will be equal to numEquatorSteps x (numPolarSteps x 2 + 1) + (includePoles ? 2 : 0).

Example:
You can test this resource in the Torque 1.5 starter.fps example. Run Starter.FPS.bat, bring down the console window(~), and type

declareBillboards("starter.fps/data/shapes/trees/ftree01.dts",8,4,128,128);

Then start the mission "Content Pack Demo 1". Run around the trees, and you should notice some of them transitioning to and from billboards.

In your game, you can call declareBillboards() anytime before DTSs get loaded. E.g. you could call it in the onStart() function of your mod. In the starter.fps mod, this would look like:

function onStart()
{
   Parent::onStart();
   echo("\n--------- Initializing MOD: FPS Starter Kit ---------");

   // blah blah blah all the usual stuff...

   // Declare programmatic billboards here!
   declareBillboards("~/data/shapes/trees/ftree01.dts",8,4,128,128);
   declareBillboards("~/data/shapes/trees/FTREE04.DTS",8,4,64,64);
}

(from the file /example/starter.fps/main.cs)

Code:
The code for this resource should work out-of-the-box for TGE versions 1.3 - 1.5.2.

Download the attached .zip file. It contains two sets of source code files, one for TGE 1.3.0-1.5.0 and one for 1.5.2. (for 1.5.1, see below) Choose the right set and copy the files into your Torque SDK code base. The files will overwrite existing files of the same names, so you may want to make backups first. Re-compile, and you should be ready to go!

I couldn't get a hold of the Torque 1.5.1 SDK, so I'm not sure which set of files it uses.

The changes in the source code are all marked with the comment "BBAPI" for convenience.

Enjoy!!