From TDN

Contents 1 What is the Profiler? 2 Using the Profiler 2.1 Enabling It 2.2 Accessing It 2.3 Manipulating Profiler Blocks 3 Stupid Profiler Tricks 3.1 Trick to help balance profiler blocks 3.2 Trick to only profile a single frame or range thereof (ie, how to track down spikes and hitches). 3.3 Trick to profile whenever you darn well please.

What is the Profiler?

The profiler is a module of Torque which can be used to do performance analysis. It isn't as stringent an analysis tool as VTune (it won't tell you what instructions are causing stalls) but it is very useful for getting an overview of where the time in your game is being spent, and particularly during optimization to track down exactly where your time is being spent.

Using the Profiler

Please see the Profiler Doxygen docs for a brief overview of how to use the profiler.

Enabling It

NOTE: The profiler by default turns on in the DEBUG build of the engine. You don't have to define anything if you want to profile a debug build.

Otherwise, you need to make a build of your game with the following define in torqueConfig.h enabled:

1. define TORQUE_ENABLE_PROFILER

This will enable the PROFILER_START/PROFILER_END macros and allow profiler data to be gathered.

Accessing It

profilerEnable/profilerDump/profilerReset and more!

Manipulating Profiler Blocks

PROFILE_START/PROFILER_END()

Stupid Profiler Tricks

Trick to help balance profiler blocks

The following code when placed near the top of a C++ file, will make the profiler macros emit a LOT of console spam, which looks like:

stack Forest_renderBlock (d=3)
stack Forest_renderBlock (d=4)
stack Forest_renderBlock (d=5)
pop
pop
pop
stack Forest_cleanup (d=3)
pop

You can use this to spot places where you aren't pushing/popping properly - you'll see a peer block showing up as a child (ie, with a great d (depth) value). For instance, you might see:

//  Source code

void bar(bool foo)
{
   PROFILE_START(pony);
   if(foo)
      return;     // This return sets up an unbalanced situation.
   PROFILE_END();
}

PROFILE_START(zing);
bar(false);
PROFILE_END();
PROFILE_START(zong);
bar(true); // We break here!
PROFILE_END();
PROFILE_START(post);
// Do some stuff.
PROFILE_END();

// Resulting output with the below macro block placed above the code snippet:

stack zing (d=0)
stack pony (d=1)
pop
pop
stack zong (d=0)
stack pony (d=1)
pop              // Only one pop here; should be two.
stack post (d=1) // Post is shown as being depth 1 when it is really depth 0! 
pop

#undef PROFILE_START
#undef PROFILE_END

#define PROFILE_START(name) \
   static ProfilerRootData pdata##name##obj (#name); \
   Con::printf("stack %s (d=%d)", #name, gProfiler->mStackDepth); \
   if(gProfiler) gProfiler->hashPush(& pdata##name##obj )

#define PROFILE_END()    Con::printf("pop"); \
                           if(gProfiler) gProfiler->hashPop()

Trick to only profile a single frame or range thereof (ie, how to track down spikes and hitches).

Trick to profile whenever you darn well please.

To set up the profiler so that you can profile for a few seconds here and a few seconds there, whenever you feel like it, add the following lines to your game/client/scripts/default.bind.cs file:

function doProfile(%val)
{
   if (%val)
   {
      // key down -- start profile
      echo("Starting profile session...");
      // This will cause it to crash if the profiler has not been 
      //  run before this is pressed (tested on Torque version 1.4.2).
      //profilerDump(); 
      profilerEnable(true);
   }
   else
   {
      // key up -- finish off profile
      echo("Ending profile session...");
      profilerDump();
      profilerEnable(false);
   }
}

GlobalActionMap.bind(keyboard, "ctrl F3", doProfile);

Here is another version:

//
// Start profiler by pressing ctrl f3
// ctrl f3 - starts profile that will dump to console and file
// 
function doProfile(%val)
{
   if (%val)
   {
      // key down -- start profile
      echo("Starting profile session...");
      //profilerDump(); // if profiler has not been run then this will crash
      profilerReset();      
      profilerEnable(true);
   }
   else
   {
      // key up -- finish off profile
      echo("Ending profile session...");
      
      profilerDump();      
      profilerDumpToFile("profilerDumpToFile" @ getSimTime() @ ".txt");
      profilerEnable(false);
   }
}

GlobalActionMap.bind(keyboard, "ctrl F3", doProfile);

Now whenever you want to see why your framerate is so slow when standing in a given location looking at a given angle, simply hold down ctrl-F3 and you will get a profile of the code for as long as you hold the keys down.