Generating a Heap Report

The SpeedTree SDK has a mechanism for generating a report that describes every heap allocation made by the SDK and anything else that uses the memory management functions in Core/Memory.h. This includes virtually everything in the reference application, save heap allocations made by other libraries used there (DXUT, glut, glew, etc.) and the graphics API themselves. All of the SpeedTree-related classes in the reference application are set up to use the SDK memory interface.

This section of the document details how to generate a report of every heap allocation routed through this interface. This report is also a good way to track memory leaks for anything that's using the allocation interface. Imbalanced new/delete calls will be revealed in the report.

Generating a Report

You must recompile the SpeedTree SDK in order to generate a report. Enable heap allocation tracking by #defining ST_MEMORY_STATS at the top of Allocator.h in the Core library (it is there by default, commented out). Comment in #define ST_MEMORY_STATS_VERBOSE back in for a very detail heap allocation report (warning: it can be lengthy).

Note: Please be sure to comment ST_MEMORY_STATS and ST_MEMORY_STATS_VERBOSE out when performance is a concern, as they will add overhead to the SDK's execution.

The next step will be to make a single call from within the client engine or application:

#include "Core/Memory.h"
using namespace SpeedTree;
 
...
 
CAllocator::Report("my_report.csv", true);

Notes

The boolean parameter to CAllocator::Report() specifies whether the current tracking records should be flushed after the report is complete. If true, only allocations made after the report is generated will be tracked. If false, it will only provide a snapshot of that instant in time without modifying the table.

The CAllocator::Report() function generates a “.csv” file (Comma Separated Values). Files of this format can be imported into most spreadsheets.

Any new calls that have not been released with a corresponding delete will be shown in the report. Therefore, be sure to place the report call appropriately.

If a call is made to CAllocator::Report() and the SDK has not been compiled with ST_MEMORY_STATS #defined, a series of linker errors will be generated