This macro allocates a memory block of a specific type.
Arguments
s
The size of the memory block to allocate, in bytes.
t
Flags that specify the type, alignment, and fill characteristics of memory to allocate.
One of the following flags must be set:
MEMTYPE_ANY
Any memory can be allocated.
MEMTYPE_VRAM
Allocate only video random-access memory (VRAM).
MEMTYPE_DRAM
Allocate only dynamic random-access memory (DRAM).
If a block of VRAM must come from a specific VRAM bank, the following flag must be set:
MEMTYPE_BANKSELECT
Allocate VRAM from a specific VRAM bank. In addition, one of the following two VRAM bank selection flags must be set:
MEMTYPE_BANK1
Allocate only memory from VRAM bank 1.
MEMTYPE_BANK2
Allocate only memory from VRAM bank 2.
The following flags are provided for compatibility with future hardware. You can set them in addition to the preceding flags.
MEMTYPE_DMA
Allocate only memory that is accessible via direct memory access (DMA). Currently, all memory is accessible via DMA, but this may not be true in future hardware. Set this flag if you know the memory must be accessible via DMA.
MEMTYPE_CEL
Allocate only memory that is accessible to the cel engine. Currently, all memory is accessible to the cel engine, but this may not be true in future hardware. Set this flag if you know the memory will be used for graphics.
MEMTYPE_AUDIO
Allocate only memory that can be used for audio data (such as digitized sound). Currently, all memory can be used for audio, but this may not be true in future hardware. Set this flag if you know the memory will be used for audio data.
MEMTYPE_DSP
Allocate only memory that is accessible to the digital signal processor (DSP). Currently, all memory is accessible to the DSP, but this may not be true in future hardware. Set this flag if you know the memory must be accessible to the DSP.
The following flags specify alignment, fill, and other allocation characteristics:
MEMTYPE_FILL
Set every byte in the memory block to the value of the lower eight bits of the flags. If this flag is not set, the previous contents of the memory block are not changed. (Using 0 as the fill value can be useful for debugging: Any memory that is inadvertently changed can easily be detected.)
MEMTYPE_INPAGE
Allocate a memory block that does not cross page boundaries.
MEMTYPE_STARTPAGE
Allocate a memory block that starts on a page boundary.
MEMTYPE_MYPOOL
Specifies that the memory block must be allocated only from the task's free memory pool. This means that if there is not sufficient memory in the task's pool, the kernel must not allocate additional memory from the system-wide free memory pool (see Notes).
MEMTYPE_SYSTEMPAGESIZE
Use the system's protection page size for that type of memory and not the special feature page size. This is necessary for MEMTYPE_VRAM to distinguish between allocations on page boundaries for graphics operations (normally 2 K) and task page sizes (normally 16 K).
Return Value
The procedure returns a pointer to the memory block that was allocated or NULL if the memory couldn't be allocated.
Implementation
Macro implemented in mem.h V20.
Associated Files
mem.h
C Macro Definition
Notes
Use FreeMem() to free a block of memory that was allocated with AllocMem().
If there is insufficient memory in a task's free memory pool to allocate the requested memory, the kernel automatically transfers the necessary pages of additional memory from the system-wide free memory pool to the task's free memory pool. The only exceptions are (1) when there is not enough memory in both pools together to satisfy the request, or (2) when the MEMTYPE_MYPOOL memory flag-which specifies that the memory block must be allocated only from the task's free memory pool-is set.
You can enable memory debugging in your application by compiling your entire project with the MEMDEBUG value defined on the compiler's command-line. Refer to the CreateMemDebug() function for more details.