Skip to main content

​
XMemCreateWin32Heap

Creates a Win32 heap.

​
Syntax

​
Parameters

HeapFlags   _In_
Type: ULONGLONG Indicates the source of memory for the heap to be created. baseAddress   _In_
Type: PVOID The base address for the in-place heap allocation. If HeapFlags is set to XMEM_HEAP_INPLACE, this value must point to an address in committed memory that is aligned to a 4-KB boundary; otherwise, this value must be set to NULL.

​
Return value

Type: HANDLE Returns a handle to the created Win32 heap, if successful; otherwise, returns NULL. If it’s available, extended error information is provided to the current XErrorCallback callback for your app.

​
Remarks

This function creates a Win32 heap, allocating memory for the heap from the source and base address indicated by HeapFlags and baseAddress, respectively. If XMEM_HEAP_INPLACE was not specified in HeapFlags when the heap was created, the heap is backed by either 2MB pages (or 64KB pages if XMEM_HEAP_64K_PAGES is specified). If an error occurs while attempting to create a Win32 heap, this method returns NULL and, if available, the error is reported to the current XErrorCallback callback for your app. For more information about handling exceptional error cases, see XError. For more information about configuring and accessing memory, see Configuring memory for your title and dev kit.

​
Allocating tooling memory

If XMEM_HEAP_TOOL is specified in HeapFlags, the function attempts to allocate memory from the tools partition to create the Win32 heap, depending on Profiling Mode and Iteration Mode settings:
  • If Iteration Mode is disabled and Profiling Mode is enabled, the function attempts to allocate the requested amount of memory from the tools partition. If the requested amount is unavailable, an error occurs.
  • If Iteration Mode is disabled and Profiling Mode is disabled, an error occurs.
  • If Iteration Mode is enabled, the function attempts to allocate the requested amount of memory from the title partition. If the requested amount is unavailable, an error occurs.
When Profiling Mode is enabled, extra memory is made available to your title that can be used during development for anything from game engine tools to unoptimized game assets. For more information about Profiling Mode, see Profiling Mode. The tools partition is unavailable when Iteration Mode is enabled. You can use the XMemIsToolsMemAvailable function to check whether memory from the tools partition is available in Profiling Mode.

​
Requirements

Header: xmem.h Library: xmem.lib Supported platforms: XBOX One family consoles and XBOX Series consoles

​
See also

Memory
XMem
Last modified on August 20, 2026

Related topics

PHEAP_TRACK_ALLOC_ROUTINE callbackPHEAP_TRACK_FREE_ROUTINE callbackPHEAP_TRACK_REALLOC_ROUTINE callbackXMemSetWin32HeapNameXMemGetWin32HeapName