Freigeben über


ID3D11DeviceContext2::UpdateTileMappings-Methode (d3d11_2.h)

Updates Zuordnungen von Kachelspeicherorten in kachelten Ressourcen zu Speicherspeicherorten in einem Kachelpool.

Syntax

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
);

Parameter

[in] pTiledResource

Typ: ID3D11Resource*

Ein Zeiger auf die kachelte Ressource.

[in] NumTiledResourceRegions

Typ: UINT

Die Anzahl der kachelten Ressourcenbereiche.

[in, optional] pTiledResourceRegionStartCoordinates

Typ: const D3D11_TILED_RESOURCE_COORDINATE*

Ein Array von D3D11_TILED_RESOURCE_COORDINATE Strukturen, die die Startkoordinaten der kachelten Ressourcenbereiche beschreiben. Der Parameter NumTiledResourceRegions gibt die Anzahl der D3D11_TILED_RESOURCE_COORDINATE Strukturen im Array an.

[in, optional] pTiledResourceRegionSizes

Typ: const D3D11_TILE_REGION_SIZE*

Ein Array von D3D11_TILE_REGION_SIZE Strukturen, die die Größe der kachelten Ressourcenbereiche beschreiben. Der Parameter NumTiledResourceRegions gibt die Anzahl der D3D11_TILE_REGION_SIZE Strukturen im Array an.

[in, optional] pTilePool

Typ: ID3D11Buffer*

Ein Zeiger auf den Kachelpool.

[in] NumRanges

Typ: UINT

Die Anzahl der Kachelpoolbereiche.

[in, optional] pRangeFlags

Typ: const UINT*

Ein Array von D3D11_TILE_RANGE_FLAG Werten, die jeden Kachelpoolbereich beschreiben. Der Parameter NumRanges gibt die Anzahl der Werte im Array an.

[in, optional] pTilePoolStartOffsets

Typ: const UINT*

Ein Array von Offsets im Kachelpool. Dies sind 0-basierte Kacheloffsets, die in Kacheln (nicht Bytes) zählen.

[in, optional] pRangeTileCounts

Typ: const UINT*

Ein Array von Kacheln.

Ein Array von Werten, die die Anzahl der Kacheln in jedem Kachelpoolbereich angeben. Der Parameter NumRanges gibt die Anzahl der Werte im Array an.

[in] Flags

Typ: UINT

Eine Kombination aus D3D11_TILE_MAPPING_FLAGS Werten, die mithilfe einer bitweisen OR-Operation kombiniert werden.

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK zurück. Gibt andernfalls eine der folgenden Rückgaben zurück:

  • Gibt E_INVALIDARG zurück, wenn verschiedene Bedingungen wie ungültige Flags dazu führen, dass der Aufruf gelöscht wird. Die Debugebene gibt einen Fehler aus.
  • Gibt E_OUTOFMEMORY zurück, wenn der Aufruf dazu führt, dass der Treiber Speicherplatz für neue Seitentabellenzuordnungen zuweisen muss, aber nicht genügend Arbeitsspeicher zur Verfügung steht. Wenn nicht genügend Arbeitsspeicher auftritt, wenn dies in einer Befehlsliste aufgerufen wird und die Befehlsliste ausgeführt wird, wird das Gerät entfernt. Apps können diese Situation vermeiden, indem sie nur Aktualisierungsaufrufe ausführen, die vorhandene Zuordnungen von gekachelten Ressourcen innerhalb von Befehlslisten ändern (sodass Treiber keinen Seitentabellenspeicher zuweisen müssen, nur die Zuordnung ändern).
  • Gibt DXGI_ERROR_DEVICE_REMOVED zurück, wenn das Video Karte physisch aus dem System entfernt wurde oder ein Treiberupgrade für das Video Karte erfolgt ist.

Hinweise

In einem einzelnen Aufruf von UpdateTileMappings können Sie einen oder mehrere Bereiche von Ressourcenkacheln einem oder mehreren Bereichen von Kachelpoolkacheln zuordnen.

Sie können die Parameter von UpdateTileMappings auf folgende Weise organisieren, um ein Update auszuführen:

  • Gekachelte Ressource, deren Zuordnungen aktualisiert werden. Dies ist eine Ressource, die mit dem flag D3D11_RESOURCE_MISC_TILED erstellt wurde. Zuordnungen beginnen mit NULL, wenn eine Ressource anfänglich erstellt wird.
  • Gruppe von Kachelbereichen in der kachelten Ressource, deren Zuordnungen aktualisiert werden. Sie können einen UpdateTileMappings-Aufruf ausführen, um viele Zuordnungen oder mehrere Aufrufe mit etwas mehr API-Aufrufe zu aktualisieren, wenn dies bequemer ist. NumTiledResourceRegions gibt an, wie viele Regionen vorhanden sind, pTiledResourceRegionStartCoordinates und pTiledResourceRegionSizes sind jeweils Arrays, die den Startstandort und die Erweiterung jeder Region identifizieren. Wenn NumTiledResourceRegions den Wert 1 aufweist, können entweder oder beide Arrays, die die Regionen beschreiben, NULL sein. NULL für pTiledResourceRegionStartCoordinates bedeutet, dass die Startkoordinate alle 0s ist, und NULL für pTiledResourceRegionSizes identifiziert einen Standardbereich, der den vollständigen Kachelsatz für die gesamte kachelte Ressource darstellt, einschließlich aller Mipmaps, Arrayslices oder beides. Wenn pTiledResourceRegionStartCoordinates nicht NULL und pTiledResourceRegionSizes null ist, wird die Regionsgröße für alle Regionen standardmäßig auf 1 Kachel festgelegt. Dies erleichtert das Definieren von Zuordnungen für eine Reihe einzelner Kacheln an unterschiedlichen Speicherorten, indem ein Array von Speicherorten in pTiledResourceRegionStartCoordinates bereitgestellt wird, ohne ein Array von pTiledResourceRegionSizes senden zu müssen, die alle auf 1 festgelegt sind.

    Die Updates werden von der ersten bis zur letzten Region angewendet. Wenn sich also Regionen in einem einzigen Aufruf überschneiden, überschreiben die Updates später in der Liste die Bereiche, die sich mit vorherigen Updates überschneiden.

  • Kachelpool, der Arbeitsspeicher bereitstellt, in den Kachelzuordnungen gespeichert werden können. Eine kachelnde Ressource kann jeweils auf einen einzelnen Kachelpool verweisen. Wenn ein neuer Kachelpool angegeben wird (zum ersten Mal oder anders als bei der letzten Angabe eines Kachelpools), werden alle vorhandenen Kachelzuordnungen für die kachelte Ressource gelöscht, und der neue Satz von Zuordnungen im aktuellen UpdateTileMappings-Aufruf wird auf den neuen Kachelpool angewendet. Wenn kein Kachelpool angegeben ist (NULL) oder derselbe Kachelpool wie ein vorheriger UpdateTileMappings-Aufruf bereitgestellt wird, fügt der UpdateTileMappings-Aufruf nur die neuen Zuordnungen zu vorhandenen hinzu (Überschreibung bei Überlappung). Wenn UpdateTileMappings nur NULL-Zuordnungen definiert, müssen Sie keinen Kachelpool angeben, da er irrelevant ist. Wenn Sie jedoch trotzdem einen Kachelpool angeben, gilt das gleiche Verhalten wie zuvor beim Bereitstellen eines Kachelpools.
  • Eine Reihe von Kachelbereichen, in denen Zuordnungen durchgeführt werden. Jeder angegebene Kachelbereich kann einen von einigen Arten von Bereichen angeben: einen Bereich von Kacheln in einem Kachelpool (Standard), eine Anzahl von Kacheln in der kachelten Ressource, die einer einzelnen Kachel in einem Kachelpool zugeordnet werden soll (freigaben die Kachel), die Anzahl der Kachelzuordnungen in der kachelten Ressource, die übersprungen und belassen werden sollen, wie sie sind, oder eine Anzahl von Kacheln im Kachelpool, die NULL zugeordnet werden sollen. NumRanges gibt die Anzahl der Kachelbereiche an, bei denen die Gesamtkacheln, die in allen Bereichen identifiziert werden, der Gesamtanzahl der Kacheln in den Kachelbereichen aus der zuvor beschriebenen kachelten Ressource entsprechen müssen. Zuordnungen werden definiert, indem die Kacheln in den Kachelbereichen in sequenzieller Reihenfolge durchlaufen werden ( x then y then y then z-Reihenfolge für Boxbereiche), während sie den Satz der Kachelbereiche in sequenzieller Reihenfolge durchlaufen. Die Aufschlüsselung der Kachelbereiche muss nicht mit der Aufschlüsselung der Kachelbereiche in Einklang stehen, aber die Gesamtanzahl der Kacheln auf beiden Seiten muss gleich sein, sodass für jede kachelnierte Ressourcenkachel eine Zuordnung angegeben ist.

    pRangeFlags, pTilePoolStartOffsets und pRangeTileCounts sind alle Arrays der Größe NumRanges, die die Kachelbereiche beschreiben. Wenn pRangeFlags NULL ist, sind alle Bereiche sequenzielle Kacheln im Kachelpool. Andernfalls identifiziert pRangeFlags[i] für jeden Bereich i, wie die Zuordnungen in diesem Kachelbereich funktionieren:

    • Wenn pRangeFlags[i] 0 ist, definiert dieser Bereich sequenzielle Kacheln im Kachelpool, wobei die Anzahl der Kacheln pRangeTileCounts[i] und die Startposition pTilePoolStartOffsets[i] ist. Wenn NumRanges den Wert 1 aufweist, kann pRangeTileCounts NULL sein und wird standardmäßig auf die Gesamtanzahl von Kacheln festgelegt, die von allen Kachelbereichen angegeben wird.
    • Wenn pRangeFlags[i] D3D11_TILE_RANGE_REUSE_SINGLE_TILE ist, identifiziert pTilePoolStartOffsets[i] die einzelne Kachel im Kachelpool, der zugeordnet werden soll, und pRangeTileCounts[i] gibt an, wie viele Kacheln aus den Kachelbereichen dem Speicherort des Kachelpools zugeordnet werden sollen. Wenn NumRanges den Wert 1 aufweist, kann pRangeTileCounts NULL sein und wird standardmäßig auf die Gesamtanzahl von Kacheln festgelegt, die von allen Kachelbereichen angegeben wird.
    • Wenn pRangeFlags[i] D3D11_TILE_RANGE_NULL ist, gibt pRangeTileCounts[i] an, wie viele Kacheln aus den Kachelbereichen NULL zugeordnet werden sollen. Wenn NumRanges den Wert 1 aufweist, kann pRangeTileCounts NULL sein und wird standardmäßig auf die Gesamtanzahl von Kacheln festgelegt, die von allen Kachelbereichen angegeben wird. pTilePoolStartOffsets[i] wird für NULL-Zuordnungen ignoriert.
    • Wenn pRangeFlags[i] D3D11_TILE_RANGE_SKIP ist, gibt pRangeTileCounts[i] an, wie viele Kacheln aus den Kachelbereichen übersprungen werden sollen, und vorhandene Zuordnungen unverändert lassen. Dies kann nützlich sein, wenn ein Kachelbereich bequem einen Bereich mit zu aktualisierenden Kachelzuordnungen eingrenzt, mit Ausnahme einiger Ausnahmen, die mit dem identisch bleiben müssen, was sie zuvor zugeordnet wurden. pTilePoolStartOffsets[i] wird für SKIP-Zuordnungen ignoriert.
  • Flags-Parameter für allgemeine Optionen.D3D11_TILE_MAPPING_NO_OVERWRITE bedeutet, dass der Aufrufer verspricht, dass zuvor an das Gerät übermittelte Befehle, die möglicherweise noch ausgeführt werden, nicht auf den Kachelbereich verweisen, der aktualisiert wird. Dadurch kann das Gerät vermeiden, dass zuvor übermittelte Arbeit geleert werden muss, um die Kachelzuordnung zu aktualisieren. Wenn die App gegen diese Zusage verstößt, indem sie Kachelzuordnungen für Speicherorte in gekachelten Ressourcen aktualisiert, auf die noch von ausstehenden Befehlen verwiesen wird, ergeben sich nicht definierte Renderingverhaltensergebnisse, was das Potenzial für erhebliche Verlangsamungen bei einigen Architekturen einschließt. Dies entspricht dem Konzept "Kein Überschreiben", das an anderer Stelle in der Direct3D-API vorhanden ist, außer auf die Datenstruktur der Kachelzuordnung selbst angewendet, bei der es sich bei der Hardware um eine Seitentabelle handelt. Das Fehlen dieses Flags erfordert, dass durch diesen UpdateTileMappings-Aufruf angegebene Aktualisierungen der Kachelzuordnung abgeschlossen werden müssen, bevor ein nachfolgender Direct3D-Befehl fortgesetzt werden kann.
Wenn sich Kachelzuordnungen für eine kachelbasierte Ressource geändert haben, die von der App über RenderTargetView oder DepthStencilView gerendert wird, muss die App mithilfe der festen Funktion Clear APIs die Kacheln löschen, die innerhalb des gerenderten Bereichs geändert wurden (zugeordnet oder nicht). Wenn eine App in diesen Situationen nicht gelöscht wird, empfängt die App nicht definierte Werte, wenn sie aus der gekachelten Ressource liest.
Hinweis In Direct3D 11.2 kann die Hardware clearView jetzt nur in Tiefenformaten unterstützen. Weitere Informationen finden Sie unter D3D11_FEATURE_DATA_D3D11_OPTIONS1.
 
Wenn eine App vorhandene Speicherinhalte von Bereichen in einer gekachelten Ressource beibehalten muss, in denen sich Zuordnungen geändert haben, kann die App zunächst den Inhalt speichern, an dem sich Kachelzuordnungen geändert haben, indem sie sie auf eine temporäre Oberfläche kopieren, z. B. mithilfe von CopyTiles, ausgibt das erforderliche Löschen und dann den Inhalt zurück kopieren.

Angenommen, eine Kachel wird mehreren kachelnden Ressourcen gleichzeitig zugeordnet, und Kachelinhalte werden mit allen Mitteln (Rendern, Kopieren usw.) über eine der kachelnden Ressourcen bearbeitet. Wenn dann dieselbe Kachel über eine andere kachelierte Ressource gerendert werden soll, muss die Kachel zuerst wie zuvor beschrieben gelöscht werden.

Weitere Informationen zu kachelnden Ressourcen finden Sie unter Gekachelte Ressourcen.

Hier sind einige Beispiele für häufige UpdateTileMappings-Fälle :

Beispiele

Löschen der Zuordnungen einer gesamten Oberfläche zu 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);

Zuordnen eines Kachelbereichs zu einer einzelnen Kachel:

// - 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);

Definieren von Zuordnungen für eine Reihe getrennter einzelner Kacheln:

// - 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);

Komplexes Beispiel: Definieren von Zuordnungen für Regionen mit einigen Übergängen, einigen NULL-Zuordnungen:

// - 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).

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8.1 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2012 R2 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile d3d11_2.h
Bibliothek D3D11.lib

Weitere Informationen

ID3D11DeviceContext2