FSOUND_SetMemorySystem

##### [API function]

## FSOUND_SetMemorySystem

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.
This is useful for systems that want FMOD to use their own memory management, or fixed memory devices such as PocketPC, XBox, PS2 and GameCube that dont want any allocations occuring out of their control causing fragmentation or unpredictable overflows in a tight memory space.
See remarks for more useful information.

DLL_API signed char F_API FSOUND_SetMemorySystem(
void *poolmem,
int poollen,
FSOUND_ALLOCCALLBACK useralloc,
FSOUND_REALLOCCALLBACK userrealloc,
FSOUND_FREECALLBACK userfree
);

### Parameters

pool | If you want a fixed block of memory for FMOD to use, pass it in here. Specify the length in poollen. Specifying NULL doesnt use internal management and it relies on callbacks.
poollen | Length in bytes of the pool of memory for FMOD to use specified in. 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().

### Return Value

void

### Remarks

FMOD has been tested to stay in a limit and fail gracefully if the fixed pool size is not large enough with FMOD_ERR_MEMORY errors.
FMOD only does allocation when creating streams, music or samples and the FSOUND_Init stage. It never allocates or deallocates memory during the course of runtime processing.
To find out the required fixed size the user can call FSOUND_GetMemoryStats with a larger than nescessary pool size (or no pool), and find out the maximum ram usage at any one time within FMOD.
-------------------------------------
FMOD behaves differently based on what you pass into this function in 3 different combinations.
Here are the examples.
NULL, 0, NULL, NULL, NULL : Falls back purely to ansi C malloc, realloc and free.
NULL, 0, myalloc, myrealloc, myfree : Calls user supplied callbacks every time fmod does a memory allocation or deallocation.
ptr, len, NULL, NULL, NULL : Uses "ptr" and manages memory internally. NO extra mallocs or frees are performed from this point.
-------------------------------------
Callbacks and memory pools cannot be combined, as if a pool is specified FMOD, manipulates the pool of memory internally with its own allocate and free scheme.
The memory management algorithm to work within a fixed size of ram is extremely efficient and faster than the standard C malloc or free.
-------------------------------------
On XBox you MUST specify a pointer and length. The memory provided must be enough to store all sample data.
___________________
Supported on the following platforms : Win32, WinCE, Linux, Macintosh, XBox, PlayStation 2, GameCube

### See Also

FSOUND_ALLOCCALLBACK , FSOUND_Close , FSOUND_FREECALLBACK , FSOUND_GetFreeHWRam , FSOUND_GetMemoryStats , FSOUND_Init , FSOUND_IOP_Alloc , FSOUND_REALLOCCALLBACK

This document copyright ©Firelight Technologies, Pty, Ltd, 1999-2002. All rights reserved.
Generated Thu Dec 15 17:31:33 2005 by SourceDoc v0.10, the automated source code documenter.