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

# CopyPageMappingsX (XBOX One 系列)

> 在 GPU 時間軸上操作 GPU 分頁表。可在圖形和 DMA 命令佇列上呼叫，但不能在計算佇列上呼叫。

在 GPU 時間軸上操作 GPU 分頁表。您可以在圖形和 DMA 命令佇列上呼叫 **CopyPageMappingsX**，但不能在計算佇列上呼叫。

## 語法

```cpp theme={null}
HRESULT CopyPageMappingsX(  
         D3D12_GPU_VIRTUAL_ADDRESS DestinationAddress,  
         UINT RangeCount,  
         const D3D12XBOX_PAGE_MAPPING_RANGE* pRanges,  
         D3D12_GPU_VIRTUAL_ADDRESS SourcePagePoolAddress,  
         UINT SourcePagePoolPageCount,  
         D3D12XBOX_PAGE_MAPPING_FLAGS Flags  
)  
```

### 參數

*DestinationAddress*   \_In\_\
類型：D3D12\_GPU\_VIRTUAL\_ADDRESS

以 **D3D12\_GPU\_VIRTUAL\_ADDRESS** (UINT64) 表示的目的地位址。

*RangeCount*   \_In\_\
類型：UINT

對應範圍的數目。

*pRanges*   \_In\_reads\_(RangeCount)\
類型：[D3D12XBOX\_PAGE\_MAPPING\_RANGE\*](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_page_mapping_range)

指向長度為 *RangeCount* 之 **D3D12XBOX\_PAGE\_MAPPING\_RANGE** 結構陣列的指標。結構的 *RangeType* 成員指定範圍的解譯方式。如需詳細資訊，請參閱 [D3D12XBOX\_PAGE\_MAPPING\_RANGE\_TYPE](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_page_mapping_range_type)。

*SourcePagePoolAddress*   \_In\_\
類型：D3D12\_GPU\_VIRTUAL\_ADDRESS

以 **D3D12\_GPU\_VIRTUAL\_ADDRESS** (UINT64) 表示的來源位址。

如果未設定範圍類型為 **D3D12XBOX\_PAGE\_MAPPING\_RANGE\_TYPE\_INCREMENTING\_PAGE\_INDICES** 或 **D3D12XBOX\_PAGE\_MAPPING\_RANGE\_TYPE\_CONSTANT\_PAGE\_INDEX** 的對應範圍，則 **SourcePagePoolAddress** 和 **SourcePagePoolPageCount** 參數都可以是 0。否則，**SourcePagePoolAddress** 和 **SourcePagePoolPageCount** 都必須為非零值，且 **SourcePagePoolPageAddress** 必須以 64KB 對齊

*SourcePagePoolPageCount*   \_In\_\
類型：UINT

來源分頁計數。

*Flags*   \_In\_\
類型：[D3D12XBOX\_PAGE\_MAPPING\_FLAGS](/zh-TW/reference/graphics/d3d12_x/enums/d3d12xbox_page_mapping_flags)

指定分頁對應方式之其他詳細資料的旗標。

### 傳回值

類型：HRESULT

其中一個 [Direct3D 12 傳回碼](https://msdn.microsoft.com/library/windows/desktop/dn706075\(v=vs.85\).aspx)。

## 備註

此方法類似於使用 **MapTitlePhysicalPages** 和 **D3DMapEsramMemory**，差別在於來源分頁取自現有的對應，而非分頁編號清單。此 API 會將 64KB 分頁對應從 GPU 分頁表內的來源位置複製到目的地位置。此 API 不會修改 CPU 分頁表。每次呼叫 **CopyPageMappingsX** 期間，會先排清 GPU 管線再執行分頁表更新，並在分頁表更新之後排清 GPU TLB 快取。

**CopyPageMappingsX** 的預期使用案例如下：

1. 在初始化時，準備一個「來源分頁集區」，作為分頁對應複製的來源。
   * 使用 [XMemVirtualAlloc](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/reference/system/xmem/functions/xmemvirtualalloc) 為來源分頁集區保留虛擬記憶體範圍，**AllocationType** 參數使用 **MEM\_64K\_PAGES** | **MEM\_RESERVE**，**XMemFlags** 則使用 **XMEM\_GRAPHICS** | **XMEM\_MAPPABLE**。
   * 如果使用系統記憶體分頁，請使用 [XMemAllocatePhysicalPages](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/reference/system/xmem/functions/xmemallocatephysicalpages) 配置系統記憶體分頁。
   * 使用 [XMemMapPhysicalPages](/zh-TW/reference/system/xmem/functions/xmemmapphysicalpages) 將系統記憶體分頁對應到保留的位址範圍，和/或使用 D3DMapEsramMemory 將 ESRAM 分頁對應到保留的位址範圍。
2. 針對需要在執行階段更新對應的每個資源：
   1. 使用 XG 程式庫計算資源的大小 (以 64KB 分頁為單位)。
   2. 使用 [XMemVirtualAlloc](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/reference/system/xmem/functions/xmemvirtualalloc) 為資源保留虛擬記憶體範圍，**AllocationType** 參數使用 **MEM\_64K\_PAGES** | **MEM\_RESERVE**，**XMemFlags** 則使用 **XMEM\_GRAPHICS** | **XMEM\_MAPPABLE**。
   3. 將資源的保留虛擬位址傳遞給 [CreatePlacedResourceX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12device/methods/id3d12device_createplacedresourcex)，以建立放置資源 API 物件。
3. 在執行階段需要更新對應時，在命令佇列上呼叫 **CopyPageMappingsX**，將對應從來源分頁集區複製到資源的保留位址範圍。

每個複製作業可以是在目的地位址範圍中執行的多個連續對應範圍的組合。每個對應範圍都以 [D3D12XBOX\_PAGE\_MAPPING\_RANGE](/zh-TW/reference/graphics/d3d12_x/structs/d3d12xbox_page_mapping_range) 結構描述，依類型指定來源分頁集區內的分頁範圍、Null 對應，或略過該範圍的指示。

使用 **CopyPageMappingsX** 建立 GPU 分頁對應之後，取消對應來源分頁集區並不是有效的動作。遊戲必須確保只要複製的對應仍在使用中，來源分頁集區的分頁就會保持對應，且不會被釋放以供其他地方重複使用。**CopyPageMappingsX** 不會對來源分頁採取任何類型的參考計數或鎖定。

使用 **CopyPageMappingsX** 的好處在於其效能，而且允許在單一呼叫中混合系統、ESRAM 和 Null 對應 (前提是來源分頁集區已建立系統和 ESRAM 對應的組合)。此外，使用預先定義的來源分頁集區有助於確保實體分頁不會在 GPU 執行對應之前意外釋放。

使用此 API 的代價是必須事先建立來源分頁集區。

## 需求

**標頭:** d3d12\_x.h

**程式庫:** d3d12\_x.lib

**支援的平台:** XBOX One 系列

## 另請參閱

[ID3D12CommandQueue](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/id3d12commandqueue)\
[ClearPageMappingsX](/zh-TW/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_clearpagemappingsx)


## Related topics

- [CopyTileMappings](/zh-CN/reference/graphics/d3d12/interfaces/id3d12commandqueue/methods/id3d12commandqueue_copytilemappings_public.md)
- [NDA topic directory - live Microsoft Learn links](/nda/nda-topic-directory.md)
- [CopyDescriptors](/zh-CN/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_copydescriptors_public.md)
- [CopyTiles](/zh-CN/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copytiles_public.md)
- [OpenExistingHeapFromFileMapping](/zh-CN/reference/graphics/d3d12/interfaces/id3d12device3/methods/id3d12device3_openexistingheapfromfilemapping_public.md)