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 的 NULL 标识默认区域，即整个保留资源（包括所有 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);