Firelight Technologies FMOD Studio API
Memory_Initialize
Specifies a method for FMOD to allocate memory, either through callbacks or its own internal memory management. You can also supply a pool of memory for FMOD to work with and it will do so with no extra calls to malloc or free.
C++ Syntax
FMOD_RESULT Memory_Initialize(
void *poolmem,
int poollen,
FMOD_MEMORY_ALLOC_CALLBACK useralloc,
FMOD_MEMORY_REALLOC_CALLBACK userrealloc,
FMOD_MEMORY_FREE_CALLBACK userfree,
FMOD_MEMORY_TYPE memtypeflags
);
C Syntax
FMOD_RESULT FMOD_Memory_Initialize(
void *poolmem,
int poollen,
FMOD_MEMORY_ALLOC_CALLBACK useralloc,
FMOD_MEMORY_REALLOC_CALLBACK userrealloc,
FMOD_MEMORY_FREE_CALLBACK userfree,
FMOD_MEMORY_TYPE memtypeflags
);
C# Syntax
static RESULT Memory.Initialize(
IntPtr poolmem,
int poollen,
MEMORY_ALLOC_CALLBACK useralloc,
MEMORY_REALLOC_CALLBACK userrealloc,
MEMORY_FREE_CALLBACK userfree,
MEMORY_TYPE memtypeflags
);
JavaScript Syntax
FMOD.Memory_Initialize(
poolmem,,
poollen,,
useralloc,,
userrealloc,,
userfree,,
memtypeflags,
);
Parameters
poolmem
If you want a fixed block of memory for FMOD to use, pass it in here. Specify the length in poollen. Specifying NULL doesn't use internal management and it relies on callbacks.
poollen
Length in bytes of the pool of memory for FMOD to use specified in poolmem. Specifying 0 turns off internal memory management and relies purely on callbacks. Length must be a multiple of 512.
useralloc
Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to alloc. Compatible with ansi malloc().
userrealloc
Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to realloc. Compatible with ansi realloc().
userfree
Only supported if pool is NULL. Otherwise it overrides the FMOD internal calls to free. Compatible with ansi free().
memtypeflags
FMOD_MEMORY_TYPE flags you wish to receive through your memory callbacks. See FMOD_MEMORY_TYPE. Bitwise OR these together for multiple types.
Return Values
If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.
Remarks
This function must be called before any FMOD System object is created.
This function is useful for systems that want FMOD to use their own memory management or for fixed memory devices such as Xbox360 that don't want any allocations occurring out of their control causing fragmentation or unpredictable overflows in a tight memory space.
FMOD mainly does allocation when creating streams, music or samples and the System::init stage. It will rarely allocate or deallocate memory during the course of runtime processing.
To find out the required fixed size the user can call Memory_Initialize with an overly large pool size (or no pool) and find out the maximum RAM usage at any one time with Memory_GetStats.
FMOD behaves differently based on what you pass into this function in 3 different combinations. For example:
FMOD::Memory_Initialize(NULL, 0, NULL, NULL, NULL, FMOD_MEMORY_ALL); // Falls back purely to ansi C malloc, realloc and free. FMOD_MEMORY_ALL is irrelevant in this case.
FMOD::Memory_Initialize(NULL, 0, myalloc, myrealloc, myfree, FMOD_MEMORY_ALL); // Calls user supplied callbacks every time FMOD does a memory allocation or deallocation.
FMOD::Memory_Initialize(ptr, len, NULL, NULL, NULL, FMOD_MEMORY_ALL); // Uses "ptr" and manages memory internally. NO extra mallocs or frees are performed from this point. FMOD_MEMORY_ALL is irrelevant in this case.
Callbacks and memory pools cannot be combined. If a memory pool is provided by the user, FMOD accesses that pool using its own memory management scheme. FMOD's internal memory management scheme is extremely efficient and also faster than the standard C malloc and free.
NOTE! Your memory callbacks must be threadsafe otherwise unexpected behaviour may occur. FMOD calls memory allocation functions from other threads (such as the asynchronous loading thread used when you specify FMOD_NONBLOCKING) and sometimes from the mixer thread.
NOTE! If you specify a fixed size pool that is too small, FMOD will return FMOD_ERR_MEMORY when the limit of the fixed size pool is exceeded. At this point, it's possible that FMOD may become unstable. To maintain stability, do not allow FMOD to run out of memory.
See Also
Version 1.10.03 Built on Feb 1, 2018