ID3D11DeviceContext2 ::UpdateTileMappings, méthode (d3d11_2.h)

Mises à jour mappages d’emplacements de vignettes dans des ressources en mosaïques à des emplacements de mémoire dans un pool de vignettes.

Syntaxe

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

Paramètres

[in] pTiledResource

Type : ID3D11Resource*

Pointeur vers la ressource en mosaïque.

[in] NumTiledResourceRegions

Type : UINT

Nombre de régions de ressources en mosaïque.

[in, optional] pTiledResourceRegionStartCoordinates

Type : const D3D11_TILED_RESOURCE_COORDINATE*

Tableau de structures D3D11_TILED_RESOURCE_COORDINATE qui décrivent les coordonnées de départ des régions de ressources en mosaïques. Le paramètre NumTiledResourceRegions spécifie le nombre de structures D3D11_TILED_RESOURCE_COORDINATE dans le tableau.

[in, optional] pTiledResourceRegionSizes

Type : const D3D11_TILE_REGION_SIZE*

Tableau de structures D3D11_TILE_REGION_SIZE qui décrivent les tailles des régions de ressources mosaïques. Le paramètre NumTiledResourceRegions spécifie le nombre de structures D3D11_TILE_REGION_SIZE dans le tableau.

[in, optional] pTilePool

Type : ID3D11Buffer*

Pointeur vers le pool de vignettes.

[in] NumRanges

Type : UINT

Nombre de plages de pool de mosaïques.

[in, optional] pRangeFlags

Type : const UINT*

Tableau de valeurs D3D11_TILE_RANGE_FLAG qui décrivent chaque plage de pool de vignettes. Le paramètre NumRanges spécifie le nombre de valeurs dans le tableau.

[in, optional] pTilePoolStartOffsets

Type : const UINT*

Tableau de décalages dans le pool de vignettes. Il s’agit de décalages de vignette basés sur 0, qui comptent dans les vignettes (et non dans les octets).

[in, optional] pRangeTileCounts

Type : const UINT*

Tableau de vignettes.

Tableau de valeurs qui spécifient le nombre de vignettes dans chaque plage de pool de vignettes. Le paramètre NumRanges spécifie le nombre de valeurs dans le tableau.

[in] Flags

Type : UINT

Combinaison de valeurs D3D11_TILE_MAPPING_FLAGS combinées à l’aide d’une opération OR au niveau du bit.

Valeur retournée

Type : HRESULT

Retourne S_OK en cas de réussite ; dans le cas contraire, retourne l’un des éléments suivants :

• Retourne E_INVALIDARG si diverses conditions telles que des indicateurs non valides entraînent la suppression de l’appel. La couche de débogage émet une erreur.
• Retourne E_OUTOFMEMORY si l’appel entraîne le fait que le pilote doit allouer de l’espace pour les nouveaux mappages de tables de pages, mais manque de mémoire. Si une mémoire insuffisante se produit lorsque cela est appelé dans une liste de commandes et que la liste de commandes est en cours d’exécution, l’appareil est supprimé. Les applications peuvent éviter cette situation en effectuant uniquement des appels de mise à jour qui modifient les mappages existants à partir de ressources en mosaïques dans les listes de commandes (par conséquent, les pilotes n’auront pas à allouer de mémoire de table de pages, mais modifient uniquement le mappage).
• Retourne DXGI_ERROR_DEVICE_REMOVED si le carte vidéo a été physiquement supprimé du système ou si une mise à niveau du pilote pour la carte vidéo s’est produite.

Remarques

Dans un seul appel à UpdateTileMappings, vous pouvez mapper une ou plusieurs plages de vignettes de ressources à une ou plusieurs plages de vignettes de pool de vignettes.

Vous pouvez organiser les paramètres de UpdateTileMappings de manière à effectuer une mise à jour :

• Ressource en mosaïque dont les mappages sont mis à jour. Il s’agit d’une ressource qui a été créée avec l’indicateur D3D11_RESOURCE_MISC_TILED . Les mappages démarrent avec la totalité de la valeur NULL lors de la création initiale d’une ressource.
• Ensemble de régions de vignette sur la ressource en mosaïque dont les mappages sont mis à jour. Vous pouvez effectuer un appel UpdateTileMappings pour mettre à jour de nombreux mappages ou plusieurs appels avec un peu plus de surcharge d’appel d’API, si cela est plus pratique. NumTiledResourceRegions spécifie le nombre de régions, pTiledResourceRegionStartCoordinates et pTiledResourceRegionSizes sont des tableaux qui identifient l’emplacement de début et l’extension de chaque région. Si NumTiledResourceRegions a la valeur 1, par souci de commodité, les tableaux qui décrivent les régions peuvent avoir la valeur NULL. NULL pour pTiledResourceRegionStartCoordinates signifie que la coordonnée de début est toutes les 0s, et NULL pour pTiledResourceRegionSizes identifie une région par défaut qui est l’ensemble complet de vignettes pour l’ensemble de la ressource en mosaïque, y compris tous les mipmaps, les tranches de tableau ou les deux. Si pTiledResourceRegionStartCoordinates n’a pas la valeur NULL et que pTiledResourceRegionSizes a la valeur NULL, la taille de région est définie par défaut sur 1 vignette pour toutes les régions. Cela permet de définir facilement des mappages pour un ensemble de vignettes individuelles à des emplacements disparates en fournissant un tableau d’emplacements dans pTiledResourceRegionStartCoordinates sans avoir à envoyer un tableau de pTiledResourceRegionSizes tous définis sur 1.

  Les mises à jour sont appliquées de la première région à la dernière ; Ainsi, si les régions se chevauchent en un seul appel, les mises à jour plus loin dans la liste remplacent les zones qui chevauchent les mises à jour précédentes.

• Pool de vignettes qui fournit de la mémoire où les mappages de vignettes peuvent aller. Une ressource en mosaïque peut pointer vers un pool de vignettes unique à la fois. Si un nouveau pool de vignettes est spécifié (pour la première fois ou différent de la dernière fois qu’un pool de vignettes a été spécifié), tous les mappages de vignettes existants pour la ressource en mosaïques sont effacés et le nouvel ensemble de mappages dans l’appel UpdateTileMappings actuel est appliqué pour le nouveau pool de vignettes. Si aucun pool de vignettes n’est spécifié (NULL) ou si le même pool de vignettes qu’un appel UpdateTileMappings précédent n’est fourni, l’appel UpdateTileMappings ajoute simplement les nouveaux mappages aux mappages existants (remplacement en cas de chevauchement). Si UpdateTileMappings définit uniquement des mappages NULL, vous n’avez pas besoin de spécifier un pool de vignettes, car il n’est pas pertinent. Toutefois, si vous spécifiez un pool de vignettes, le comportement est identique à celui décrit précédemment lors de la fourniture d’un pool de vignettes.
• Ensemble de plages de vignettes où les mappages sont en cours. Chaque plage de vignettes donnée peut spécifier l’un des types de plages : une plage de vignettes dans un pool de vignettes (par défaut), un nombre de vignettes dans la ressource en mosaïque à mapper à une seule vignette dans un pool de vignettes (partage de la vignette), un nombre de mappages de vignettes dans la ressource mosaïque à ignorer et à laisser tels quels, ou un nombre de vignettes dans le pool de vignettes à mapper à NULL. NumRanges spécifie le nombre de plages de vignettes, où le nombre total de vignettes identifiées dans toutes les plages doit correspondre au nombre total de vignettes dans les régions de vignettes de la ressource en mosaïque décrite précédemment. Les mappages sont définis en itérant les vignettes dans les régions de mosaïques dans l’ordre séquentiel (x, puis y, puis z order pour les zones) tout en parcourant l’ensemble de plages de vignettes dans l’ordre séquentiel. La répartition des régions de vignettes n’a pas besoin de correspondre à la répartition des plages de vignettes, mais le nombre total de vignettes des deux côtés doit être égal afin que chaque vignette de ressource en mosaïque spécifiée ait un mappage spécifié.

  pRangeFlags, pTilePoolStartOffsets et pRangeTileCounts sont tous des tableaux, de taille NumRanges, qui décrivent les plages de vignettes. Si pRangeFlags a la valeur NULL, toutes les plages sont des vignettes séquentielles dans le pool de vignettes ; sinon, pour chaque plage i, pRangeFlags[i] identifie le fonctionnement des mappages de cette plage de vignettes :

  • Si pRangeFlags[i] est 0, cette plage définit des vignettes séquentielles dans le pool de vignettes, le nombre de vignettes étant pRangeTileCounts[i] et l’emplacement de départ pTilePoolStartOffsets[i]. Si NumRanges a la valeur 1, pRangeTileCounts peut être NULL et correspond par défaut au nombre total de vignettes spécifié par toutes les régions de vignette.
  • Si pRangeFlags[i] est D3D11_TILE_RANGE_REUSE_SINGLE_TILE, pTilePoolStartOffsets[i] identifie la vignette unique dans le pool de vignettes à mapper et pRangeTileCounts[i] spécifie le nombre de vignettes des régions de mosaïques à mapper à cet emplacement de pool de vignettes. Si NumRanges a la valeur 1, pRangeTileCounts peut être NULL et correspond par défaut au nombre total de vignettes spécifié par toutes les régions de vignette.
  • Si pRangeFlags[i] est D3D11_TILE_RANGE_NULL, pRangeTileCounts[i] spécifie le nombre de vignettes des régions de vignette à mapper à NULL. Si NumRanges a la valeur 1, pRangeTileCounts peut être NULL et correspond par défaut au nombre total de vignettes spécifié par toutes les régions de vignette. pTilePoolStartOffsets[i] est ignoré pour les mappages NULL.
  • Si pRangeFlags[i] est D3D11_TILE_RANGE_SKIP, pRangeTileCounts[i] spécifie le nombre de vignettes des régions de vignettes à ignorer et laisse les mappages existants inchangés. Cela peut être utile si une région de vignettes limite facilement une zone de mappages de vignettes à mettre à jour, sauf avec quelques exceptions qui doivent être laissées comme celles auxquelles elles ont été mappées auparavant. pTilePoolStartOffsets[i] est ignoré pour les mappages SKIP.
• Paramètre Flags pour les options globales.D3D11_TILE_MAPPING_NO_OVERWRITE signifie que l’appelant promet que les commandes précédemment envoyées à l’appareil qui peut encore s’exécuter ne référencent aucune des régions de vignette en cours de mise à jour. Cela permet à l’appareil d’éviter d’avoir à vider le travail précédemment soumis afin d’effectuer la mise à jour du mappage de vignettes. Si l’application ne respecte pas cette promesse en mettant à jour les mappages de vignettes pour les emplacements dans les ressources en mosaïques toujours référencés par des commandes en attente, les résultats de comportement de rendu non définis, qui incluent le risque de ralentissements significatifs sur certaines architectures. Cela ressemble au concept « pas de remplacement » qui existe ailleurs dans l’API Direct3D, sauf appliqué à la structure de données de mappage de vignettes elle-même, qui, dans le matériel, est une table de pages. L’absence de cet indicateur nécessite que les mises à jour de mappage de vignettes spécifiées par cet appel UpdateTileMappings soient effectuées avant qu’une commande Direct3D suivante puisse continuer.

Si les mappages de vignettes ont changé sur une ressource en mosaïque que l’application rendra via RenderTargetView ou DepthStencilView, l’application doit effacer, à l’aide de la fonction fixe Clear API, les vignettes qui ont changé dans la zone en cours de rendu (mappées ou non). Si une application ne s’efface pas dans ces situations, l’application reçoit des valeurs non définies lorsqu’elle lit à partir de la ressource en mosaïque. Si une application doit conserver le contenu de la mémoire existante des zones d’une ressource en mosaïque où les mappages ont été modifiés, l’application peut d’abord enregistrer le contenu là où les mappages de vignettes ont été modifiés, en les copiant sur une surface temporaire, par exemple à l’aide de CopyTiles, en émettant le clear requis, puis en recopiant le contenu.

Supposons qu’une vignette soit mappée en plusieurs ressources en mosaïques en même temps et que le contenu des vignettes soit manipulé par n’importe quel moyen (rendu, copie, etc.) via l’une des ressources en mosaïques. Ensuite, si la même vignette doit être affichée via une autre ressource en mosaïque, la vignette doit d’abord être effacée comme décrit précédemment.

Pour plus d’informations sur les ressources en mosaïque, consultez Ressources en mosaïque.

Voici quelques exemples de cas updateTileMappings courants :

Exemples

Effacer les mappages d’une surface entière sur 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);

Mappage d’une région de vignettes à une vignette unique :

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

Définition de mappages pour un ensemble de vignettes individuelles disjointes :

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

Exemple complexe : définition de mappages pour des régions avec quelques sauts, certains mappages 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).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8.1 [applications de bureau | Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 R2 [applications de bureau | Applications UWP]
Plateforme cible	Windows
En-tête	d3d11_2.h
Bibliothèque	D3D11.lib

Voir aussi

ID3D11DeviceContext2