work on programmatic DTS billboards

A while back I mentioned I had been experimenting with adding billboards to DTS shapes, programmatically. This is the idea where your game code can add billboards to any DTS shape, without involving an art tool (Blender, Max, etc.) exporter. You'd simply write Torquescript calls (or something) to add the billboards at run-time. This seems like something that would make a useful resource.


So finally, I've gotten around to working on this idea in earnest.

The good news is, I've got it working - in certain cases. It works when the DTS shape is used by Player / AIPlayer objects, or by RTSUnit objects (from the RTS-Starter Kit).

The bad news is, this resource doesn't work for all cases. The biggest problem is that it doesn't work when the DTS is used by a TSStatic. That's a pretty big drawback, if I understand the purpose of TSStatics correctly. TSStatics are for when you've got lots of a certain kind of object in a game, like trees. Unfortunately, that's exactly the situation where billboards are most likely to be wanted.

The resource can also crash if the billboard is for a Player object, and the Player object has shadows turned on.

I think I know what the problem is (or at least one of them) with TSStatics, so I'm going to keep trying to get this resource working with TSStatics.

Despite its current limitations, I thought I'd go ahead and post the code I have, so that anyone who wants to can play with it or comment on it can do that. I should note that the code *sometimes* works with TSStatics. In fact the example below uses TSStatics from the Stronghold mission; by luck those don't seem to crash it. But it's definitely not guaranteed to be stable.

For more info about DTS billboards in general, check out e.g. the docs on the Blender .dts exporter.

Here's what I've got so far for the resource. Again, this is only a prototype, hopefully in the future there'll be a more bulletproof version.

--------

Programmatic DTS billboards

Summary:
This resource allows you to programmatically add billboards to a DTS shape. The DTS shape does not need to have been exported with billboards.

Article:
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, since rendering a 2-D bitmap is much faster than rendering a 3-D shape.

Until now, billboards had to be turned on or off at the time the DTS was exported from the art tool (Blender, Max, etc) that created the DTS. With this resource, you can now turn on billboards in your game rather than in the art tool. This can be done for any DTS shape that doesn't already have billboards. The programmatic API supports all the same parameters that the art tool exporters support (and, arguably, slightly more).

API:
This resource adds a single Torquescript function (brackets denote optional params):

setupBillboards(shapeName, numEquatorSteps, numPolarSteps, bitmapSize, detailSize [, polarAngle [, includePoles [, bitmapDetailLevel ]]] )

For more info on the parameters, see the Blender DTS exporter docs.

Code
snipped - see comments below

Example
You can test this resource using the starter.fps example in Torque 1.5. Run Starter.FPS.bat, and start the mission "A Stronghold". Once in the mission, bring down the console window (~) and type

setupBillboards("starter.fps/data/shapes/Winter/TreeNoSnow03.dts",8,4,32,64);
setupBillboards("starter.fps/data/shapes/Winter/TreeNoSnow04.dts",8,4,32,64);
setupBillboards("starter.fps/data/shapes/Winter/TreeNoSnow05.dts",8,4,32,64);

That'll create billboards for three of the tree models. As you run around the mission area you should notice some of the trees transition between 3-D shapes and billboards. The billboards will be pretty ugly, but that's intentional to make them more noticable. (normally, of course, you'd select the billboard parameters to make the transition as invisible as possible).

up-close: 3-D shapes.

step back a bit: they become billboards.