Skip to main content

​
XMemMapPhysicalPagesScatter

Maps physical pages into virtual memory.

​
Syntax

​
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 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. NumberOfPages   _In_
Type: ULONG_PTR The number of entries in PageArray and VirtualAddressArray. Only 64k pages reserved through 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.

​
Return value

Type: BOOL Returns TRUE if mapping was successful, otherwise, FALSE if there was a mapping failure.

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

​
Requirements

Header: xmem.h Library: xmem.lib Supported platforms: XBOX One family consoles and XBOX Series consoles

​
See also

XMemVirtualAlloc
XMem
Last modified on August 20, 2026

Related topics

XMemMapPhysicalPagesWorking with the Microsoft GDK Game OS memory managerXMemFreePhysicalPagesMapPAGE 106 · Accessible web content and applications