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 Include/SpeedTree/Core/Memory.h. This includes virtually everything in the reference application, save heap allocations made by other libraries used there (DXUT, glew, etc.) and the graphics APIs 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 using the system. Imbalanced new and delete calls will be revealed in the report.

You must recompile the SpeedTree SDK in order to generate a report. Enable heap allocation tracking by adding #define ST_MEMORY_STATS at the top of Include/SpeedTree/Core/Allocator.h in the Core library (it is there by default, commented out around line 40). Comment #define ST_MEMORY_STATS_VERBOSE back in for a very detailed 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"
 
...
 
SpeedTree::CAllocator::Report("my_report.csv", true);

• 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. 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 #define ST_MEMORY_STATS active, a series of linker errors will be generated.