ID3D12CommandQueue：：UpdateTileMappings 方法 (d3d12.h)

發行項
08/23/2023

更新將保留資源中的磚位置對應至資源堆積中的記憶體位置。

語法

void UpdateTileMappings(
  [in]           ID3D12Resource                        *pResource,
                 UINT                                  NumResourceRegions,
  [in, optional] const D3D12_TILED_RESOURCE_COORDINATE *pResourceRegionStartCoordinates,
  [in, optional] const D3D12_TILE_REGION_SIZE          *pResourceRegionSizes,
  [in, optional] ID3D12Heap                            *pHeap,
                 UINT                                  NumRanges,
  [in, optional] const D3D12_TILE_RANGE_FLAGS          *pRangeFlags,
  [in, optional] const UINT                            *pHeapRangeStartOffsets,
  [in, optional] const UINT                            *pRangeTileCounts,
                 D3D12_TILE_MAPPING_FLAGS              Flags
);

參數

[in] pResource

保留資源的指標。

NumResourceRegions

保留的資源區域數目。

[in, optional] pResourceRegionStartCoordinates

描述保留資源區域的開始座標的 D3D12_TILED_RESOURCE_COORDINATE 結構陣列。 NumResourceRegions參數會指定陣列中D3D12_TILED_RESOURCE_COORDINATE結構的數目。

[in, optional] pResourceRegionSizes

描述保留資源區域大小的 D3D12_TILE_REGION_SIZE 結構陣列。 NumResourceRegions參數會指定陣列中D3D12_TILE_REGION_SIZE結構的數目。

[in, optional] pHeap

資源堆積的指標。

NumRanges

圖格範圍的數目。

[in, optional] pRangeFlags

描述每個磚範圍的 D3D12_TILE_RANGE_FLAGS 值陣列指標。 NumRanges參數會指定陣列中的值數目。

[in, optional] pHeapRangeStartOffsets

資源堆積中位移的陣列。這些是以 0 為基礎的磚位移，以磚計算 (不是位元組) 。

[in, optional] pRangeTileCounts

圖格的陣列。值的陣列，指定每個磚範圍中的磚數目。 NumRanges參數會指定陣列中的值數目。

Flags

使用位 OR 運算結合 D3D12_TILE_MAPPING_FLAGS 值的組合。

傳回值

無

備註

使用 UpdateTileMappings 將保留資源的虛擬頁面對應至堆積的實體頁面。對應不需要依序排列。此作業類似于 ID3D11DeviceCoNtext2：：UpdateTileMappings ，其中一個主要差異是 D3D12 可讓保留資源具有多個堆積的磚。

在 UpdateTileMappings的單一呼叫中，您可以將一或多個資源磚範圍對應至一或多個堆積磚範圍。

您可以透過下列方式來組織 UpdateTileMappings 的參數，以執行更新：

已更新其對應的保留資源。 一開始建立資源時，對應會從所有 Null 開始。
保留資源上的圖格區域集，其對應已更新。 您可以進行一個 UpdateTileMappings 呼叫，以更新許多對應或多個呼叫，如果更方便的話，也會有一些 API 呼叫額外負荷。
- NumResourceRegions 會指定有多少區域。
- pResourceRegionStartCoordinates 和 pResourceRegionSizes 是每個陣列，可識別每個區域的開始位置和擴充。如果 NumResourceRegions 為 1，為了方便起見，描述區域的陣列或兩者可以是 Null。 pResourceRegionStartCoordinates的 Null 表示開始座標全部為 0，pResourceRegionSizes會識別預設區域，這是整個保留資源的完整磚集，包括所有 mipmap、陣列配量或兩者。
- 如果 pResourceRegionStartCoordinates 不是 Null， 且 pResourceRegionSizes 為 Null，則區域大小預設為所有區域的 1 個圖格。這可讓您輕鬆地在不同的位置定義一組個別磚的對應，方法是在 pResourceRegionStartCoordinates 中提供位置陣列，而不需要傳送 pResourceRegionSizes 全部設定為 1 的陣列。
更新會從第一個區域套用到最後一個區域;因此，如果區域在單一呼叫中重迭，則清單中的更新稍後會覆寫與先前更新重迭的區域。
堆積，提供磚對應可以前往的記憶體。 如果 UpdateTileMappings 只定義 Null 對應，則不需要指定堆積。
一組圖格範圍，其中會進行對應。 每個指定的磚範圍都可以指定數種範圍的其中一種：堆積中的磚範圍 (預設) 、保留資源中的磚計數，以對應至堆積中的單一磚 (共用磚) 、保留資源中的磚對應計數，以略過和離開它們一樣或堆積中要對應至 Null 的圖格計數。NumRanges 會指定磚範圍的數目，其中所有範圍中識別的磚總數必須符合先前所描述保留資源磚區域中的磚總數。對應是透過依循序順序逐一查看磚區域中的圖格來定義 - x，y 然後方塊區域的 z 順序 - 同時依循序順序逐步流覽一組磚範圍。磚區域的細目不需要與磚範圍的明細一致，但兩端的磚總數必須相等，因此指定的每個保留資源磚都有指定的對應。
pRangeFlags、 pHeapRangeStartOffsets和 pRangeTileCounts 都是大小 為 NumRanges的陣列，描述磚範圍。如果 pRangeFlags 為 Null，則所有範圍都是堆積中的循序磚;否則，針對每個範圍 i，pRangeFlags[i] 會識別該圖格範圍中的對應運作方式：
- 如果 pRangeFlags[i]是D3D12_TILE_RANGE_FLAG_NONE，該範圍會在堆積中定義循序磚，其中磚數目為 pRangeTileCounts[i] 和開始位置 pHeapRangeStartOffsets[i]。如果 NumRanges 是 1， pRangeTileCounts 可以是 Null，而且預設為所有磚區域所指定的磚總數。
- 如果 pRangeFlags[i]是D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE， pHeapRangeStartOffsets[i] 會識別堆積中要對應的單一磚， 而 pRangeTileCounts[i] 會指定要對應到該堆積位置的磚區域有多少圖格。如果 NumRanges 是 1， pRangeTileCounts 可以是 Null，而且預設為所有磚區域所指定的磚總數。
- 如果 pRangeFlags[i]是D3D12_TILE_RANGE_FLAG_Null， pRangeTileCounts[i] 會指定要從磚區域對應到 Null 的圖格數目。如果 NumRanges 是 1， pRangeTileCounts 可以是 Null，而且預設為所有磚區域所指定的磚總數。 null 對應會忽略pHeapRangeStartOffsets[i] 。
- 如果 pRangeFlags[i] 是 D3D12_TILE_RANGE_FLAG_SKIP， pRangeTileCounts[i] 會指定要略過磚區域的圖格數目，並讓現有的對應保持不變。如果磚區域方便系結要更新的磚區域，但有些例外狀況必須與之前對應的任何專案相同，這非常有用。 skip 對應會忽略pHeapRangeStartOffsets[i] 。

保留的資源必須遵循相同的規則，才能將磚別名、初始化和資料繼承作為放置的資源。如需詳細資訊，請參閱 CreatePlacedResource 。

以下是常見 UpdateTileMappings 案例的一些範例：

範例

這些範例參考下列結構和列舉：

清除整個表面與 Null 的對應

// - NULL for pResourceRegionStartCoordinates and pResourceRegionSizes defaults to the entire resource
// - NULL for pHeapRangeStartOffsets since it isn't needed for mapping tiles to NULL
// - NULL for pRangeTileCounts when NumRanges is 1 defaults to the same number of tiles as the resource region (which is
//   the entire surface in this case)
//
UINT RangeFlags = D3D12_TILE_RANGE_FLAG_NULL;
pCommandQueue->UpdateTileMappings(pResource, 1, NULL, NULL, NULL, 1, &RangeFlags, NULL, NULL, D3D12_TILE_MAPPING_FLAG_NONE);

將磚的區域對應至單一磚：

// - This maps a 2x3 tile region at tile offset (1,1) in a resource to tile [12] in a heap
// 
D3D12_TILED_RESOURCE_COORDINATE TRC;
TRC.X = 1;
TRC.Y = 1;
TRC.Z = 0;
TRC.Subresource = 0;

D3D12_TILE_REGION_SIZE TRS;
TRS.bUseBox = TRUE;
TRS.Width = 2;
TRS.Height = 3; 
TRS.Depth = 1;
TRS.NumTiles = TRS.Width * TRS.Height * TRS.Depth;

UINT RangeFlags = D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE;
UINT StartOffset = 12;

pCommandQueue->UpdateTileMappings(pResource,1,&TRC,&TRS,pHeap,1,&RangeFlags,&StartOffset,NULL,D3D12_TILE_MAPPING_FLAG_NONE);

定義一組脫離個別磚的對應：

// - This can also be accomplished in multiple calls. 
//   A single call to define multiple mapping updates can reduce CPU call overhead slightly,
//   at the cost of having to pass arrays as parameters.
// - Passing NULL for pResourceRegionSizes defaults to each region in the resource
//   being a single tile.  So all that is needed are the coordinates of each one.
// - Passing NULL for pRangeFlags defaults to no flags (since none are needed in this case)
// - Passing NULL for pRangeTileCounts defaults to each range in the heap being size 1.
//   So all that is needed are the start offsets for each tile in the heap
//
D3D12_TILED_RESOURCE_COORDINATE TRC[3];
UINT StartOffsets[3];
UINT NumSingleTiles = 3;
TRC[0].X = 1;
TRC[0].Y = 1; 
TRC[0].Subresource = 0;

StartOffsets[0] = 1;
TRC[1].X = 4;
TRC[1].Y = 7; 
TRC[1].Subresource = 0;
StartOffsets[1] = 4;

TRC[2].X = 2;
TRC[2].Y = 3; 
TRC[2].Subresource = 0;
StartOffsets[2] = 7;

pCommandQueue->UpdateTileMappings(pResource,NumSingleTiles,&TRC,NULL,pHeap,NumSingleTiles,NULL,StartOffsets,
NULL,D3D12_TILE_MAPPING_FLAG_NONE);

複雜範例 - 定義具有一些略過的區域對應，一些 Null 對應。

// - This complex example hard codes the parameter arrays, whereas in practice the 
//   application would likely configure the parameters programatically or in a data driven way.
// - Suppose we have 3 regions in a resource to configure mappings for, 2x3 at coordinate (1,1),
//   3x3 at coordinate (4,7), and 7x1 at coordinate (20,30)
// - The tiles in the regions are walked from first to last, in X then Y then Z order,
//   while stepping forward through the specified Tile Ranges to determine each mapping.
//   In this example, 22 tile mappings need to be defined.
// - Suppose we want the first 3 tiles to be mapped to a contiguous range in the heap starting at
//   heap location [9], the next 8 to be skipped (left unchanged), the next 2 to map to NULL, 
//   the next 5 to share a single tile (heap location [17]) and the remaining 
//   4 tiles to each map to to unique heap locations, [2], [9], [4] and [17]:
//
D3D12_TILED_RESOURCE_COORDINATE TRC[3];
D3D12_TILE_REGION_SIZE TRS[3];
UINT NumRegions = 3;

TRC[0].X = 1;
TRC[0].Y = 1; 
TRC[0].Subresource = 0;
TRS[0].bUseBox = TRUE;
TRS[0].Width = 2;
TRS[0].Height = 3; 
TRS[0].NumTiles = TRS[0].Width * TRS[0].Height;

TRC[1].X = 4;
TRC[1].Y = 7; 
TRC[1].Subresource = 0;
TRS[1].bUseBox = TRUE;
TRS[1].Width = 3;
TRS[1].Height = 3; 
TRS[1].NumTiles = TRS[1].Width * TRS[1].Height;

TRC[2].X = 20;
TRC[2].Y = 30; 
TRC[2].Subresource = 0;
TRS[2].bUseBox = TRUE;
TRS[2].Width = 7;
TRS[2].Height = 1; 
TRS[2].NumTiles = TRS[2].Width * TRS[2].Height;

UINT NumRanges = 8;
UINT RangeFlags[8];
UINT HeapRangeStartOffsets[8];
UINT RangeTileCounts[8];

RangeFlags[0] = 0;
HeapRangeStartOffsets[0] = 9;
RangeTileCounts[0] = 3;

RangeFlags[1] = D3D12_TILE_RANGE_FLAG_SKIP;
HeapRangeStartOffsets[1] = 0; // offset is ignored for skip mappings
RangeTileCounts[1] = 8;

RangeFlags[2] = D3D12_TILE_RANGE_FLAG_NULL;
HeapRangeStartOffsets[2] = 0; // offset is ignored for NULL mappings
RangeTileCounts[2] = 2;

RangeFlags[3] = D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE;
HeapRangeStartOffsets[3] = 17; 
RangeTileCounts[3] = 5;

RangeFlags[4] = 0;
HeapRangeStartOffsets[4] = 2; 
RangeTileCounts[4] = 1;

RangeFlags[5] = 0;
HeapRangeStartOffsets[5] = 9; 
RangeTileCounts[5] = 1;

RangeFlags[6] = 0;
HeapRangeStartOffsets[6] = 4; 
RangeTileCounts[6] = 1;

RangeFlags[7] = 0;
HeapRangeStartOffsets[7] = 17; 
RangeTileCounts[7] = 1;

pCommandQueue->UpdateTileMappings(pResource,NumRegions,TRC,TRS,pHeap,NumRanges,RangeFlags,
HeapRangeStartOffsets,RangeTileCounts,D3D12_TILE_MAPPING_FLAG_NONE);