ID3D11DeviceContext2::UpdateTileMappings メソッド (d3d11_2.h)

[アーティクル]
08/22/2023

タイルリソース内のタイルの場所とタイルプール内のメモリの場所のマッピングを更新します。

構文

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 を返します。これがコマンドリストで呼び出され、コマンドリストが実行されているときにメモリ不足が発生した場合、デバイスは削除されます。アプリは、コマンドリスト内のタイル化されたリソースから既存のマッピングを変更する更新呼び出しのみを実行することで、この状況を回避できます (そのため、ドライバーはページテーブルメモリを割り当てる必要はありません。マッピングのみを変更します)。
ビデオ カードがシステムから物理的に削除された場合、またはビデオカードのドライバーのアップグレードが発生した場合にDXGI_ERROR_DEVICE_REMOVEDを返します。

注釈

UpdateTileMappings を 1 回呼び出すと、1 つ以上のリソースタイルの範囲を 1 つ以上のタイルプールタイルの範囲にマップできます。

UpdateTileMappings のパラメーターは、次の方法で整理して更新を実行できます。

マッピングが更新されるタイルリソース。 これは、 D3D11_RESOURCE_MISC_TILED フラグを使用して作成されたリソースです。マッピングは、リソースが最初に作成されるときに、すべての NULL から開始されます。
マッピングが更新されるタイルリソース上のタイル領域のセット。 1 つの UpdateTileMappings 呼び出しを行って、API 呼び出しのオーバーヘッドを少し増やして、多くのマッピングまたは複数の呼び出しを更新できます(便利な場合)。 NumTiledResourceRegions は、リージョンの数を指定します。 pTiledResourceRegionStartCoordinates および pTiledResourceRegionSizes は、各リージョンの開始位置と拡張を識別する各配列です。 NumTiledResourceRegions が 1 の場合、便宜上、領域を記述する配列の一方または両方を NULL にすることができます。 pTiledResourceRegionStartCoordinates の場合、NULL は開始座標がすべて 0s であることを意味し、pTiledResourceRegionSizes の場合は NULL は、すべてのミップマップ、配列スライス、またはその両方を含む、タイル化されたリソース全体のタイルの完全なセットである既定の領域を識別します。 pTiledResourceRegionStartCoordinates が NULL ではなく、pTiledResourceRegionSizes が NULL の場合、リージョンサイズはすべてのリージョンに対して既定で 1 タイルになります。これにより、 pTiledResourceRegionStartCoordinates 内の場所の配列を提供することで、 pTiledResourceRegionSizes の配列をすべて 1 に設定せずに、個別のタイルのセットのマッピングを個別の場所に簡単に定義できます。
更新プログラムは最初のリージョンから最後のリージョンに適用されます。そのため、リージョンが 1 回の呼び出しで重複する場合は、一覧の後半で更新プログラムによって、以前の更新プログラムと重複する領域が上書きされます。
タイルマッピングが実行できるメモリを提供するタイルプール。 タイルリソースは、一度に 1 つのタイルプールを指すことができます。新しいタイルプールが指定されている場合 (タイルプールが最後に指定されたときとは異なる場合)、タイルリソースの既存のすべてのタイルマッピングがクリアされ、現在の UpdateTileMappings 呼び出しの新しいマッピングセットが新しいタイルプールに適用されます。タイルプールが指定されていない (NULL) か、以前の UpdateTileMappings 呼び出しと同じタイルプールが指定されている場合、 UpdateTileMappings 呼び出しでは、新しいマッピングが既存のマッピングに追加されます (重複時に上書きされます)。 UpdateTileMappings で NULL マッピングのみが定義されている場合、タイルプールは無関係であるため、指定する必要はありません。ただし、タイルプールを指定する場合は、タイルプールを提供するときに前に説明したのと同じ動作が実行されます。
マッピングが行われるタイル範囲のセット。 指定した各タイル範囲では、いくつかの種類の範囲のいずれかを指定できます。タイルプール内のタイルの範囲 (既定値)、タイルプール内の 1 つのタイルにマップするタイルの数 (タイルを共有する)、タイルリソース内のタイルマッピングの数をスキップしてそのままにできます。または、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] はマップ先のタイルプール内の 1 つのタイルを識別し、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] は、スキップして既存のマッピングを変更せずに残すタイル領域のタイルの数を指定します。これは、タイル領域がタイルマッピングの領域を適切にバインドして更新する場合に便利です。ただし、以前にマップされたものと同じままにする必要がある例外を除きます。 PTilePoolStartOffsets[i] は SKIP マッピングでは無視されます。
全体的なオプションの Flags パラメーター。D3D11_TILE_MAPPING_NO_OVERWRITE は、呼び出し元が、まだ実行している可能性があるデバイスに以前に送信されたコマンドが、更新されるタイル領域を参照しないことを約束することを意味します。これにより、デバイスは、タイルマッピングの更新を行うために、以前に送信された作業をフラッシュする必要がなくなります。未処理のコマンドによって引き続き参照されているタイルリソース内の場所のタイルマッピングを更新することで、アプリがこの約束に違反した場合、未定義のレンダリング動作の結果が発生します。これには、一部のアーキテクチャで大幅な速度低下が発生する可能性があります。これは、Direct3D API の他の場所に存在する "上書きなし" の概念に似ています。ただし、タイルマッピングデータ構造自体 (ハードウェアではページテーブル) に適用される点が異なっています。このフラグがない場合は、後続の Direct3D コマンドを続行する前に、この UpdateTileMappings 呼び出しで指定されたタイルマッピングの更新を完了する必要があります。

アプリが RenderTargetView または DepthStencilView を介してレンダリングするタイルリソースでタイルマッピングが変更された場合、アプリは固定関数 Clear API を使用して、レンダリングされる領域内で変更されたタイルをクリアする必要があります (マップされるかどうか)。このような状況でアプリがクリアされない場合、アプリはタイルリソースから読み取るときに未定義の値を受け取ります。

メモ Direct3D 11.2 では、ハードウェアが深度のみの形式で ClearView をサポートできるようになりました。詳細については、「 D3D11_FEATURE_DATA_D3D11_OPTIONS1」を参照してください。

マッピングが変更されたタイルリソース内の領域の既存のメモリコンテンツをアプリで保持する必要がある場合、アプリはまず、タイルマッピングが変更されたコンテンツを保存できます。そのためには、まず、CopyTiles を使用して、必要な Clear を発行し、コンテンツをコピーして戻します。

タイルが複数のタイルリソースに同時にマップされ、タイルコンテンツがタイルリソースの 1 つを介して任意の方法 (レンダリング、コピーなど) によって操作されるとします。次に、他のタイルリソースを介して同じタイルをレンダリングする場合は、前に説明したように最初にタイルをクリアする必要があります。

タイルリソースの詳細については、「タイルリソース」を参照してください。

一般的な 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);

タイルの領域を 1 つのタイルにマッピングする:

// - 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
Library	D3D11.lib

こちらもご覧ください

ID3D11DeviceContext2

次の方法で共有

ID3D11DeviceContext2::UpdateTileMappings メソッド (d3d11_2.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース