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

Maps physical pages into virtual memory.

<a id="syntaxSection" />

## Syntax

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

<a id="parametersSection" />

### Parameters

\**VirtualAddressArray*   \_In\_\
Type: PVOID

The array of virtual addresses at which the pages should be mapped. This parameter cannot be set to `NULL`. Use [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) with `MEM_RESERVE` and `XMEM_MAPPABLE` to reserve a memory address range to use with **XMemMapPhysicalPagesScatter**. The reserved virtual addresses must also be created with 64k pages through the `MEM_64K_PAGES` option with [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc).

*NumberOfPages*   \_In\_\
Type: ULONG\_PTR

The number of entries in *PageArray* and *VirtualAddressArray*. Only 64k pages reserved through [XMemVirtualAlloc](/reference/system/xmem/functions/xmemvirtualalloc) using the MEM\_64K\_PAGES option are supported.

*PageArray*   \_In\_reads\_opt\_(NumberOfPages)\
Type: PULONG\_PTR

The array of Page Frame Numbers (PFNs) representing the physical pages to map. This parameter can be set to `NULL`. If *PageArray* is set to `NULL`, then this function performs an unmap operation.  If an individual entry in the array is set to `NULL`, then the corresponding Virtual Address is unmapped.

<a id="retvalSection" />

### Return value

Type: BOOL

Returns `TRUE` if mapping was successful, otherwise, `FALSE` if there was a mapping failure.

<a id="remarksSection" />

### Remarks

This function treats `VirtualAddressArray` and `PageArray` as parallel arrays with the same length, as specified by `NumberOfPages`. Each virtual address in an array element of `VirtualAddressArray` is mapped or unmapped depending on `PageArray`:

* If an array element in `PageArray` is set to a PFN, then the virtual address in the corresponding array element in `VirtualAddressArray` is mapped to that PFN.
* If an array element in `PageArray` is set to `NULL`, then the virtual address in the corresponding array element in `VirtualAddressArray` is unmapped.
* If `PageArray` is set to `NULL`, then every virtual address in `VirtualAddressArray` is unmapped.

For best performance, virtual addresses within the same 2 MB window (both size and alignment) should be provided consecutively and in ascending order.  This allows the OS to opportunistically look ahead and determine if it can defer some operations that operate at CPU page granularities until the end of the group. For more information about mapping physical pages to virtual addresses, see [Working with the Microsoft GDK Game OS memory manager](/build/console-features/memory/system-memory-working).

<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

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


## Related topics

- [XMemMapPhysicalPages](/reference/system/xmem/functions/xmemmapphysicalpages.md)
- [Working with the Microsoft GDK Game OS memory manager](/build/console-features/memory/system-memory-working.md)
- [XMemFreePhysicalPages](/reference/system/xmem/functions/xmemfreephysicalpages.md)
- [Map](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [PAGE 106 · Accessible web content and applications](/build/game-principles/accessibility/page/page-106-web-content-applications.md)