> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XMemCreateWin32Heap

> XMemCreateWin32Heap

# XMemCreateWin32Heap

Creates a Win32 heap.

<a id="syntaxSection" />

## Syntax

```cpp theme={null}
HANDLE XMemCreateWin32Heap(  
         ULONGLONG HeapFlags,  
         PVOID baseAddress  
)  
```

<a id="parametersSection" />

### Parameters

*HeapFlags*   \_In\_<br />Type: ULONGLONG

Indicates the source of memory for the heap to be created.

| Flag                  | Description                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `XMEM_HEAP_DEFAULT`   | Heap memory is allocated from the title partition. You must specify `NULL` for *baseAddress* when using this flag.                                       |
| `XMEM_HEAP_TOOL`      | Heap memory is allocated from the tools partition, if the partition is available. You must specify `NULL` for *baseAddress* when using this flag.        |
| `XMEM_HEAP_INPLACE`   | The memory block specified in *baseAddress* is used by the heap. You must specify an address in committed memory for *baseAddress* when using this flag. |
| `XMEM_HEAP_64K_PAGES` | Heap memory is allocated using 64KB pages instead of 2MB pages.                                                                                          |

*baseAddress*   \_In\_<br />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`.

<a id="retvalSection" />

### 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](/reference/system/xerror/functions/xerrorcallback) callback for your app.

<a id="remarksSection" />

## 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](/reference/system/xerror/functions/xerrorcallback) callback for your app. For more information about handling exceptional error cases, see [XError](/reference/system/xerror/xerror_members).

For more information about configuring and accessing memory, see [Configuring memory for your title and dev kit](/build/console-features/memory/system-memory-tooling).

<a id="remarks_tooling" />

### 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](/build/console-features/debugging-diagnostics/profiling-mode). The tools partition is unavailable when Iteration Mode is enabled.

You can use the [XMemIsToolsMemAvailable](/reference/system/xmem/functions/xmemistoolsmemavailable) function to check whether memory from the tools partition is available in Profiling Mode.

<a id="requirementsSection" />

## Requirements

**Header:** xmem.h

**Library:** xmem.lib

**Supported platforms:** XBOX One family consoles and XBOX Series consoles

<a id="seealsoSection" />

## See also

[Memory](/build/console-features/memory/system-memory-overview)<br />[XMem](/reference/system/xmem/xmem_members)


## Related topics

- [PHEAP_TRACK_ALLOC_ROUTINE callback](/reference/system/xmem/functions/pheap_track_alloc_routine.md)
- [PHEAP_TRACK_FREE_ROUTINE callback](/reference/system/xmem/functions/pheap_track_free_routine.md)
- [PHEAP_TRACK_REALLOC_ROUTINE callback](/reference/system/xmem/functions/pheap_track_realloc_routine.md)
- [XMemSetWin32HeapName](/reference/system/xmem/functions/xmemsetwin32heapname.md)
- [XMemGetWin32HeapName](/reference/system/xmem/functions/xmemgetwin32heapname.md)