ID3D11DeviceContext2：：UpdateTileMappings 方法 (d3d11_2.h)

發行項
03/05/2024

匯報磚資源中的磚位置對應至磚集區中的記憶體位置。

語法

HRESULT UpdateTileMappings(
  [in]           ID3D11Resource                        *pTiledResource,
  [in]           UINT                                  NumTiledResourceRegions,
  [in, optional] const D3D11_TILED_RESOURCE_COORDINATE *pTiledResourceRegionStartCoordinates,
  [in, optional] const D3D11_TILE_REGION_SIZE          *pTiledResourceRegionSizes,
  [in, optional] ID3D11Buffer                          *pTilePool,
  [in]           UINT                                  NumRanges,
  [in, optional] const UINT                            *pRangeFlags,
  [in, optional] const UINT                            *pTilePoolStartOffsets,
  [in, optional] const UINT                            *pRangeTileCounts,
  [in]           UINT                                  Flags
);

參數

[in] pTiledResource

類型： ID3D11Resource*

圖格資源的指標。

[in] NumTiledResourceRegions

類型： UINT

圖格資源區域的數目。

[in, optional] pTiledResourceRegionStartCoordinates

類型： const D3D11_TILED_RESOURCE_COORDINATE*

描述磚資源區域的開始座標之 D3D11_TILED_RESOURCE_COORDINATE 結構的陣列。 NumTiledResourceRegions 參數會指定數位中D3D11_TILED_RESOURCE_COORDINATE結構的數目。

[in, optional] pTiledResourceRegionSizes

類型： const D3D11_TILE_REGION_SIZE*

描述磚資源區域大小的 D3D11_TILE_REGION_SIZE 結構數位。 NumTiledResourceRegions 參數會指定陣列中D3D11_TILE_REGION_SIZE結構的數目。

[in, optional] pTilePool

類型： ID3D11Buffer*

圖格集區的指標。

[in] NumRanges

類型： UINT

圖格集區範圍的數目。

[in, optional] pRangeFlags

類型： const UINT*

描述每個磚集區範圍的 D3D11_TILE_RANGE_FLAG 值數位。 NumRanges 參數會指定數位中的值數目。

[in, optional] pTilePoolStartOffsets

類型： const UINT*

圖格集區中位移的陣列。這些是以 0 為基礎的磚位移，以磚計算 (不是位元組) 。

[in, optional] pRangeTileCounts

類型： const UINT*

圖格的陣列。

值的陣列，指定每個磚集區範圍中的磚數目。 NumRanges 參數會指定數位中的值數目。

[in] Flags

類型： UINT

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

傳回值

類型： HRESULT

如果成功，則傳回S_OK;否則，傳回下列其中一項：

如果各種條件無效，例如無效的旗標會導致呼叫中斷，則傳回 E_INVALIDARG 。偵錯層會發出錯誤。
如果呼叫導致驅動程式必須為新的分頁表對應配置空間，但記憶體不足，則傳回 E_OUTOFMEMORY 。如果在命令清單中呼叫此專案且正在執行 commandlist 時發生記憶體不足，將會移除裝置。應用程式只能執行更新呼叫來變更命令清單內磚資源的現有對應， (因此驅動程式不需要配置分頁表記憶體，只變更對應) 。
如果已從系統實際移除視訊卡，或發生視訊卡的驅動程序升級，則傳回 DXGI_ERROR_DEVICE_REMOVED 。

備註

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

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

已更新其對應的磚資源。 這是使用 D3D11_RESOURCE_MISC_TILED 旗標所建立的資源。一開始建立資源時，對應會從所有NULL 開始。
磚資源上的圖格區域集，其對應已更新。 您可以進行一個 UpdateTileMappings 呼叫，以更新許多對應或多個呼叫，如果更方便的話，也會有一些 API 呼叫額外負荷。 NumTiledResourceRegions 會指定有多少區域， pTiledResourceRegionStartCoordinates 和 pTiledResourceRegionSizes 是每個數位，可識別每個區域的開始位置和擴充。如果 NumTiledResourceRegions 為 1，為了方便起見，描述區域的兩個陣列可以是 NULL。 pTiledResourceRegionStartCoordinates 的 NULL 表示開始座標全部為 0，而 pTiledResourceRegionSizes 的 NULL 會識別預設區域，這是整個磚資源的完整磚集，包括所有 mipmap、陣組配量或兩者。如果 pTiledResourceRegionStartCoordinates 不是 NULL， 且 pTiledResourceRegionSizes 為 NULL，則區域大小預設為所有區域的 1 個圖格。這可讓您輕鬆地定義一組個別磚的對應，方法是在 pTiledResourceRegionStartCoordinates 中提供 pTiledResourceRegionStartCoordinates 中的位置陣列，而不需要傳送 pTiledResourceRegionSizes 全部設定為 1 的陣列。
更新會從第一個區域套用到最後一個區域;因此，如果區域在單一呼叫中重疊，則清單中的更新稍後會覆寫與先前更新重疊的區域。
磚集區，提供磚對應可以前往的記憶體。 磚化資源一次可以指向單一磚集區。如果第一次指定新的磚集區 (，或與上次指定磚集區不同的是) ，則會清除磚資源的所有現有磚對應，並針對新的磚集區套用目前 UpdateTileMappings 呼叫中的一組新對應。如果未指定磚集區 (NULL) 或與先前 UpdateTileMappings 呼叫相同的磚集區， 則 UpdateTileMappings 呼叫只會在重疊) 覆寫時，將新的對應新增至現有的對應 (覆寫。如果 UpdateTileMappings 只定義 NULL 對應，則不需要指定圖格集區，因為它無關。但是，如果您仍然指定磚集區，它會採用與先前提供磚集區時所述的相同行為。
一組圖格範圍，其中會進行對應。 每個指定的磚範圍都可以指定數種範圍的其中一種：磚集區中的磚範圍 (預設) 、磚資源中的磚計數，以對應至磚集區中的單一磚， (共用磚) 、磚資源中要略過並保留的磚對應計數，或圖格集區中要對應至NULL的磚計數。NumRanges 會指定磚範圍的數目，其中所有範圍中所識別的磚總數必須符合先前描述磚資源磚區域中的磚總數。對應是透過依循序順序逐一查看磚區域中的圖格來定義 - x，y 然後方塊區域的 z 順序 - 同時依循序順序逐步流覽一組磚範圍。磚區域的明細不需要與磚範圍的明細一致，但兩端的磚總數必須相等，如此一來，指定的每個磚資源磚都有指定的對應。
pRangeFlags、 pTilePoolStartOffsets 和 pRangeTileCounts 都是大小 為 NumRanges 的陣列，描述磚範圍。如果 pRangeFlags 為 NULL，則所有範圍都是磚集區中的循序磚;否則，針對每個範圍 i，pRangeFlags[i] 會識別該圖格範圍中的對應如何運作：
- 如果 pRangeFlags[i] 為 0，該範圍會在磚集區中定義循序磚，且磚數目為 pRangeTileCounts[i] 和開始位置 pTilePoolStartOffsets[i]。如果 NumRanges 是 1，pRangeTileCounts 可以是 NULL，而且預設為所有磚區域所指定的磚總數。
- 如果 pRangeFlags[i] 是D3D11_TILE_RANGE_REUSE_SINGLE_TILE，pTilePoolStartOffsets[i] 會識別磚集區中要對應的單一磚，而 pRangeTileCounts[i] 會指定要對應到該磚集區位置的磚區域有多少磚。如果 NumRanges 是 1，pRangeTileCounts 可以是 NULL，而且預設為所有磚區域所指定的磚總數。
- 如果 pRangeFlags[i] 是D3D11_TILE_RANGE_NULL，pRangeTileCounts[i] 會指定要從磚區域對應至 NULL 的圖格數目。如果 NumRanges 是 1，pRangeTileCounts 可以是 NULL，而且預設為所有磚區域所指定的磚總數。 pTilePoolStartOffsets[i] 會忽略 NULL 對應。
- 如果 pRangeFlags[i] 是D3D11_TILE_RANGE_SKIP，pRangeTileCounts[i] 會指定要略過磚區域的圖格數目，並讓現有的對應保持不變。如果磚區域方便系結要更新的磚區域，但有些例外狀況必須與之前對應的任何專案相同，這非常有用。針對 SKIP 對應，會忽略 pTilePoolStartOffsets[i] 。
標幟整體選項的參數。D3D11_TILE_MAPPING_NO_OVERWRITE 表示呼叫端承諾先前提交命令給可能仍在執行的裝置，不會參考正在更新的任何磚區域。這可讓裝置避免必須排清先前提交的工作，才能進行磚對應更新。如果應用程式藉由更新磚資源中仍受未定義命令參考的位置對應、未定義的轉譯行為結果，而違反此承諾，其中包括某些架構上可能會大幅變慢的可能性。這類似於 Direct3D API 中其他地方的「無覆寫」概念，但套用至磚對應數據結構本身，而硬體中則是分頁表。缺少此旗標時，必須先完成這個 UpdateTileMappings 呼叫所指定的磚對應更新，才能繼續任何後續的 Direct3D 命令。

如果應用程式透過 RenderTargetView 或 DepthStencilView 轉譯的磚資源上變更了磚對應，則應用程式必須使用固定函式 Clear API 來 清除，這些磚在轉譯區域內已變更， (對應或未) 。如果應用程式在這些情況下未清除，當應用程式從磚資源讀取時，就會收到未定義的值。

注意在 Direct3D 11.2 中，硬體現在可以支援僅限深度格式的 ClearView 。如需詳細資訊，請參閱 D3D11_FEATURE_DATA_D3D11_OPTIONS1。

如果應用程式需要保留磚資源中已變更之區域的現有記憶體內容，應用程式可以先儲存磚對應已變更的內容，方法是將它們複製到暫存表面，例如使用 CopyTiles、發出必要的 Clear，然後將內容複製回。

假設磚同時對應到多個磚資源，並透過其中一個磚資源 (轉譯、複製) 等方式操作磚內容。然後，如果要透過任何其他磚資源轉譯相同的磚，必須先清除磚，如先前所述。

如需磚資源的詳細資訊，請參閱磚資源。

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

範例

清除整個表面對應至 NULL：

// - No-overwrite is specified, assuming it is known nothing else the GPU could be doing is referencing the previous mappings
// - NULL for pTiledResourceRegionStatCoordinates and pTiledResourceRegionSizes defaults to the entire resource
// - NULL for pTilePoolStartOffsets 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 tiled resource region (which is
//   the entire surface in this case)
//
// UINT RangeFlags = D3D11_TILE_MAPPING_NULL;
// pDeviceContext2->UpdateTileMappings(pTiledResource,1,NULL,NULL,NULL,1,&RangeFlags,NULL,NULL,D3D11_TILE_MAPPING_NO_OVERWRITE);

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

// - This maps a 2x3 tile region at tile offset (1,1) in a Tiled Resource to tile [12] in a Tile Pool
// 
// D3D11_TILED_RESOURCE_COORDINATE TRC;
// TRC.X = 1;
// TRC.Y = 1;
// TRC.Z = 0;
// TRC.Subresource = 0;
//
// D3D11_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 = D3D11_TILE_MAPPING_REUSE_SINGLE_TILE;
// UINT StartOffset = 12;
// pDeviceContext2->UpdateTileMappings(pTiledResource,1,&TRC,&TRS,pTilePool,1,&RangeFlags,&StartOffset,
//                                     NULL,D3D11_TILE_MAPPING_NO_OVERWRITE);

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

// - This can also be accomplished in multiple calls.  Using a single call to define multiple
//   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 pTiledResourceRegionSizes defaults to each region in the Tiled Resource
//   being a single tile.  So all that is needed are the coordinates of each one.
// - Passing NULL for Range Flags defaults to no flags (since none are needed in this case)
// - Passing NULL for pRangeTileCounts defaults to each range in the Tile Pool being size 1.
//   So all that is needed are the start offsets for each tile in the Tile Pool
//
// D3D11_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;
//
// pDeviceContext2->UpdateTileMappings(pTiledResource,NumSingleTiles,&TRC,NULL,pTilePool,NumSingleTiles,NULL,StartOffsets,
//                                     NULL,D3D11_TILE_MAPPING_NO_OVERWRITE);

複雜範例 - 定義具有一些略過之區域的對應，一些 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 Tiled 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 Tile Pool starting at
//   tile pool 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 (tile pool location [17]) and the remaining 
//   4 tiles to each map to to unique tile pool locations, [2], [9], [4] and [17]:
//
// D3D11_TILED_RESOURCE_COORDINATE TRC[3];
// D3D11_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 TilePoolStartOffsets[8];
// UINT RangeTileCounts[8];
//
// RangeFlags[0] = 0;
// TilePoolStartOffsets[0] = 9;
// RangeTileCounts[0] = 3;
//
// RangeFlags[1] = D3D11_TILE_MAPPING_SKIP;
// TilePoolStartOffsets[1] = 0; // offset is ignored for skip mappings
// RangeTileCounts[1] = 8;
//
// RangeFlags[2] = D3D11_TILE_MAPPING_NULL;
// TilePoolStartOffsets[2] = 0; // offset is ignored for NULL mappings
// RangeTileCounts[2] = 2;
//
// RangeFlags[3] = D3D11_TILE_MAPPING_REUSE_SINGLE_TILE;
// TilePoolStartOffsets[3] = 17; 
// RangeTileCounts[3] = 5;
//
// RangeFlags[4] = 0;
// TilePoolStartOffsets[4] = 2; 
// RangeTileCounts[4] = 1;
//
// RangeFlags[5] = 0;
// TilePoolStartOffsets[5] = 9; 
// RangeTileCounts[5] = 1;
//
// RangeFlags[6] = 0;
// TilePoolStartOffsets[6] = 4; 
// RangeTileCounts[6] = 1;
//
// RangeFlags[7] = 0;
// TilePoolStartOffsets[7] = 17; 
// RangeTileCounts[7] = 1;
//
// pDeviceContext2->UpdateTileMappings(pTiledResource,NumRegions,TRC,TRS,pTilePool,NumRanges,RangeFlags,
//                                     TilePoolStartOffsets,RangeTileCounts,D3D11_TILE_MAPPING_NO_OVERWRITE);

CopyTileMappings

// CopyTileMappings helps with tasks such as shifting mappings around within/across Tiled Resources, e.g. scrolling tiles.
// The source and dest region can overlap - the result of the copy in this case is as if the source was saved to a temp and then
// from there written to the dest, though the implementation may be able to do better. 
//
// The Flags field allows D3D11_TILE_MAPPING_NO_OVERWRITE to be specified, means the caller promises that previously 
//      submitted commands to the device that may still be executing do not reference any of the tile region being updated.
//      This allows the device to avoid having to flush previously submitted work in order to do the tile mapping 
//      update.  If the application violates this promise by updating tile mappings for locations in Tiled Resouces 
//      still being referenced by outstanding commands, undefined rendering behavior results, including the potential 
//      for significant slowdowns on some architectures.  This is like the "no overwrite" concept that exists 
//      elsewhere in the API, except applied to Tile Mapping data structure itself (which in hardware is a page table).
//      The absence of this flag requires that tile mapping updates specified by this call must be completed before any
//      subsequent D3D command can proceed.
//
// Return Values:
//
// Returns S_OK or E_INVALIDARG or E_OUTOFMEMORY.  The latter can happen if the call results in the driver having to 
// allocate space for new page table mappings but running out of memory.
//
// If out of memory occurs when this is called in a commandlist and the commandlist is being executed, the device will be removed.
// Applications can avoid this situation by only doing update calls that change existing mappings from Tiled Resources 
// within commandlists (so drivers will not have to allocate page table memory, only change the mapping).
//
// Various other basic conditions such as invalid flags or passing in non Tiled Resources result in call being dropped 
// with E_INVALIDARG.
// 
// Validation remarks:
//
// The dest and the source regions must each entirely fit in their resource or behavior is undefined 
// (debug layer will emit an error).

規格需求

需求	值
最低支援的用戶端	Windows 8.1 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2012 R2 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	d3d11_2.h
程式庫	D3D11.lib

另請參閱

ID3D11DeviceContext2

共用方式為

ID3D11DeviceContext2：：UpdateTileMappings 方法 (d3d11_2.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源