This section provides a high-level overview of the key Scaleform memory-management concepts, their interaction and effect on memory use. It is recommended that developers understand these concepts before customizing the allocator and/or profiling Scaleform memory use.
All external memory allocations made by Scaleform go through a central interface installed on GFx::System during startup, allowing developers to plug in their own memory management system. Memory management can be customized by following several different approaches:
The approach chosen depends on the memory strategy adopted by the application. Case (2) is common on consoles with fixed memory budgets for sub-systems. The different implementations are described in detail in Section 2: Memory Allocation.
Regardless of the memory management approach developers choose externally, all internal Scaleform allocations are organized into heaps, broken down by file and by purpose. Developers will most likely first encounter these while looking at AMP or MemReport output. The most common heaps are:
However, heaps can also have a significant disadvantage – they are subject to internal fragmentation. Internal fragmentation occurs when small memory blocks freed within the heap don’t get released to the rest of the application, because all of their associated pages are not free, resulting in effectively “unused” memory being held by the heap.
Scaleform 3.3 addressed this challenge by providing a new Scaleform::SysAlloc-based heap implementation that frees memory much more aggressively. Scaleform 3.3 and higher also allows GFx::Movie objects located on the same thread to share a single memory heap, which can result in less memory held by partially-filled blocks.
Scaleform 3.0 introduced ActionScript (AS) garbage collection, eliminating memory leaks caused by circular references within AS data structures. Proper collection is critical for operation of CLIK and any involved ActionScript program.
In Scaleform, garbage collection is contained within the GFx::Movie object, which serves as an execution sandbox for the AS Virtual Machine. With Scaleform 3.3 and higher, it is possible to share Movie heaps, which also shares and unifies the associated garbage collector. In most cases collection will be triggered automatically when the Movie heap grows due to ActionScript allocations; however, it is also possible to trigger it explicitly or instruct Scaleform to collect as explicit frame-based intervals. The details of collection and its configuration options are described in Garbage Collection.
The Scaleform memory system has the ability to mark allocations with “stat ID” tags that describe the purpose of those allocations. Allocated memory can then be reported by heap, broken down into stat ID categories, or by stat ID, broken down into heaps. This memory reporting functionality is exposed primarily by the Analyzer for Memory and Performance (AMP), which is shipped as a stand-alone profiling application starting with Scaleform 3.2. For details on using AMP, please refer to AMP User Guide. Memory reports can also be obtained programmatically in string format by calling the Scaleform::MemoryHeap::MemReport function.
The stat ID tags described above are stored separately from the actual memory allocations, as debug data. Debug data are also kept for memory leak detection. When a debug version of Scaleform shuts down, a leaked memory report is generated in the Visual Studio output window or console. Since Scaleform doesn’t have any known internal memory leaks, any leaks detected are most likely caused by improper use of reference counting on Scaleform objects. The extra associated debug data are not allocated in Shipping configurations.