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

# XMemCreateWin32Heap

> XMemCreateWin32Heap

# XMemCreateWin32Heap

创建 Win32 堆。

## 语法

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

### 参数

*HeapFlags*   \_In\_\
类型：ULONGLONG

指示要创建的堆的内存来源。

| 标志 | 说明 |
| - | - |
| `XMEM_HEAP_DEFAULT` | 堆内存从游戏分区分配。使用此标志时，必须为 *baseAddress* 指定 `NULL`。 |
| `XMEM_HEAP_TOOL` | 如果工具分区可用，则从工具分区分配堆内存。使用此标志时，必须为 *baseAddress* 指定 `NULL`。 |
| `XMEM_HEAP_INPLACE` | 堆使用 *baseAddress* 中指定的内存块。使用此标志时，必须为 *baseAddress* 指定已提交内存中的一个地址。 |
| `XMEM_HEAP_64K_PAGES` | 堆内存使用 64KB 页而非 2MB 页进行分配。 |

*baseAddress*   \_In\_\
类型：PVOID

原位堆分配的基地址。如果 `HeapFlags` 设置为 `XMEM_HEAP_INPLACE`，则此值必须指向已提交内存中对齐到 4-KB 边界的地址；否则，此值必须设置为 `NULL`。

### 返回值

类型：HANDLE

如果成功，则返回所创建 Win32 堆的句柄；否则返回 `NULL`。如果可用，扩展错误信息将提供给应用当前的 [XErrorCallback](https://docs.xbox.com/zh-CN/reference/system/xerror/functions/xerrorcallback.md) 回调。

## 备注

此函数创建一个 Win32 堆，分别从 `HeapFlags` 和 `baseAddress` 指示的源和基地址为该堆分配内存。如果创建堆时未在 `HeapFlags` 中指定 `XMEM_HEAP_INPLACE`，则堆由 2MB 页支持（如果指定了 XMEM\_HEAP\_64K\_PAGES，则为 64KB 页）。如果在尝试创建 Win32 堆时发生错误，此方法将返回 `NULL`，并且（如果可用）错误将报告给应用当前的 [XErrorCallback](https://docs.xbox.com/zh-CN/reference/system/xerror/functions/xerrorcallback.md) 回调。有关处理异常错误情况的更多信息，请参阅 [XError](https://docs.xbox.com/zh-CN/reference/system/xerror/xerror_members.md)。

有关配置和访问内存的更多信息，请参阅[为游戏和开发工具包配置内存](https://docs.xbox.com/zh-CN/build/console-features/memory/system-memory-tooling.md)。

### 分配工具内存

如果在 `HeapFlags` 中指定了 `XMEM_HEAP_TOOL`，则函数将尝试从工具分区分配内存以创建 Win32 堆，具体取决于分析模式和迭代模式设置：

* 如果迭代模式被禁用且分析模式已启用，则函数尝试从工具分区分配请求的内存量。如果请求的量不可用，则会发生错误。
* 如果迭代模式被禁用且分析模式也被禁用，则会发生错误。
* 如果迭代模式已启用，则函数尝试从游戏分区分配请求的内存量。如果请求的量不可用，则会发生错误。

启用分析模式后，你的游戏将可以使用额外的内存，可在开发期间用于任何用途，从游戏引擎工具到未优化的游戏资源。有关分析模式的更多信息，请参阅[分析模式](https://docs.xbox.com/zh-CN/build/console-features/debugging-diagnostics/profiling-mode.md)。启用迭代模式时，工具分区不可用。

你可以使用 [XMemIsToolsMemAvailable](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/xmemistoolsmemavailable.md) 函数来检查在分析模式下工具分区中的内存是否可用。

## 要求

**标头：** xmem.h

**库：** xmem.lib

**支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## 请参阅

[内存](https://docs.xbox.com/zh-CN/build/console-features/memory/system-memory-overview.md)\
[XMem](https://docs.xbox.com/zh-CN/reference/system/xmem/xmem_members.md)


## Related topics

- [PHEAP_TRACK_ALLOC_ROUTINE callback](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/pheap_track_alloc_routine.md)
- [PHEAP_TRACK_FREE_ROUTINE callback](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/pheap_track_free_routine.md)
- [PHEAP_TRACK_REALLOC_ROUTINE callback](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/pheap_track_realloc_routine.md)
- [XMemSetWin32HeapName](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/xmemsetwin32heapname.md)
- [XMemGetWin32HeapName](https://docs.xbox.com/zh-CN/reference/system/xmem/functions/xmemgetwin32heapname.md)