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

# XMemMapPhysicalPagesScatter

> XMemMapPhysicalPagesScatter

# XMemMapPhysicalPagesScatter

将物理页映射到虚拟内存中。

<a id="syntaxSection" />

## 语法

```cpp theme={null}
BOOL XMemMapPhysicalPagesScatter(  
         PVOID *VirtualAddressArray,  
         ULONG_PTR NumberOfPages,  
         PULONG_PTR PageArray  
)  
```

<a id="parametersSection" />

### 参数

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

页应被映射到的虚拟地址的数组。此参数不能设置为 `NULL`。使用带有 `MEM_RESERVE` 和 `XMEM_MAPPABLE` 的 [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) 来预留供 **XMemMapPhysicalPagesScatter** 使用的内存地址范围。预留的虚拟地址还必须通过 [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) 的 `MEM_64K_PAGES` 选项以 64k 页创建。

*NumberOfPages*   \_In\_\
类型：ULONG\_PTR

*PageArray* 和 *VirtualAddressArray* 中的条目数。仅支持通过使用 MEM\_64K\_PAGES 选项的 [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) 预留的 64k 页。

*PageArray*   \_In\_reads\_opt\_(NumberOfPages)\
类型：PULONG\_PTR

表示要映射的物理页的页帧编号 (PFN) 数组。此参数可以设置为 `NULL`。如果 *PageArray* 设置为 `NULL`，则此函数将执行取消映射操作。如果数组中的单个条目设置为 `NULL`，则相应的虚拟地址将被取消映射。

<a id="retvalSection" />

### 返回值

类型：BOOL

如果映射成功，则返回 `TRUE`；否则，如果发生映射失败，则返回 `FALSE`。

<a id="remarksSection" />

### 备注

此函数将 `VirtualAddressArray` 和 `PageArray` 视为具有相同长度的并行数组，长度由 `NumberOfPages` 指定。`VirtualAddressArray` 每个数组元素中的每个虚拟地址将根据 `PageArray` 被映射或取消映射：

* 如果 `PageArray` 中的数组元素设置为一个 PFN，则 `VirtualAddressArray` 中相应数组元素的虚拟地址将映射到该 PFN。
* 如果 `PageArray` 中的数组元素设置为 `NULL`，则 `VirtualAddressArray` 中相应数组元素的虚拟地址将被取消映射。
* 如果 `PageArray` 设置为 `NULL`，则 `VirtualAddressArray` 中的每个虚拟地址都将被取消映射。

为获得最佳性能，位于同一 2 MB 窗口内（大小和对齐都在其中）的虚拟地址应连续且按升序提供。这允许操作系统机会性地进行前瞻，并确定是否可以将某些以 CPU 页粒度进行的操作推迟到组的末尾。有关将物理页映射到虚拟地址的详细信息，请参阅[使用 Microsoft GDK Game OS 内存管理器](/build/console-features/memory/system-memory-working)。

<a id="requirementsSection" />

## 要求

**头文件：** xmem.h

**库：** xmem.lib

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

<a id="seealsoSection" />

## 另请参阅

[XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc)\
[XMem](/reference/system/xmem/xmem_members)


## Related topics

- [XMemMapPhysicalPages](/zh-CN/reference/system/xmem/functions/xmemmapphysicalpages.md)
- [使用 Microsoft GDK 游戏 OS 内存管理器](/zh-CN/build/console-features/memory/system-memory-working.md)
- [XMemFreePhysicalPages](/zh-CN/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [Map](/zh-CN/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [DSTORAGE_REQUEST_OPTIONS](/zh-CN/reference/system/dstorage/structs/dstorage_request_options.md)