> ## 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

创建 Win32 堆。

<a id="syntaxSection" />

## 语法

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

<a id="parametersSection" />

### 参数

*HeapFlags*   \_In\_<br />类型：ULONGLONG

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

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

*baseAddress*   \_In\_<br />类型：PVOID

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

<a id="retvalSection" />

### 返回值

类型：HANDLE

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

<a id="remarksSection" />

## 备注

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

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

<a id="remarks_tooling" />

### 分配工具内存

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

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

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

你可以使用 [XMemIsToolsMemAvailable](/reference/system/xmem/functions/xmemistoolsmemavailable) 函数来检查在分析模式下工具分区中的内存是否可用。

<a id="requirementsSection" />

## 要求

**标头：** xmem.h

**库：** xmem.lib

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

<a id="seealsoSection" />

## 请参阅

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


## Related topics

- [PHEAP_TRACK_ALLOC_ROUTINE callback](/zh-CN/reference/system/xmem/functions/pheap_track_alloc_routine.md)
- [PHEAP_TRACK_FREE_ROUTINE callback](/zh-CN/reference/system/xmem/functions/pheap_track_free_routine.md)
- [PHEAP_TRACK_REALLOC_ROUTINE callback](/zh-CN/reference/system/xmem/functions/pheap_track_realloc_routine.md)
- [XMemGetWin32HeapName](/zh-CN/reference/system/xmem/functions/xmemgetwin32heapname.md)
- [XMemGetWin32HeapStatistics](/zh-CN/reference/system/xmem/functions/xmemgetwin32heapstatistics.md)