Partager via


ID3D12CommandQueue::UpdateTileMappings, méthode (d3d12.h)

Mises à jour mappages d’emplacements de vignette dans des ressources réservées à des emplacements de mémoire dans un tas de ressources.

Syntaxe

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

Paramètres

[in] pResource

Pointeur vers la ressource réservée.

NumResourceRegions

Nombre de régions de ressources réservées.

[in, optional] pResourceRegionStartCoordinates

Tableau de structures D3D12_TILED_RESOURCE_COORDINATE qui décrivent les coordonnées de départ des régions de ressources réservées. Le paramètre NumResourceRegions spécifie le nombre de structures D3D12_TILED_RESOURCE_COORDINATE dans le tableau.

[in, optional] pResourceRegionSizes

Tableau de structures D3D12_TILE_REGION_SIZE qui décrivent les tailles des régions de ressources réservées. Le paramètre NumResourceRegions spécifie le nombre de structures D3D12_TILE_REGION_SIZE dans le tableau.

[in, optional] pHeap

Pointeur vers le tas de ressources.

NumRanges

Nombre de plages de vignettes.

[in, optional] pRangeFlags

Pointeur vers un tableau de valeurs D3D12_TILE_RANGE_FLAGS qui décrit chaque plage de vignettes. Le paramètre NumRanges spécifie le nombre de valeurs dans le tableau.

[in, optional] pHeapRangeStartOffsets

Tableau de décalages dans le tas de ressources. 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

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

Flags

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

Valeur de retour

None

Notes

Utilisez UpdateTileMappings pour mapper les pages virtuelles d’une ressource réservée aux pages physiques d’un tas. Le mappage n’a pas besoin d’être dans l’ordre. L’opération est similaire à ID3D11DeviceContext2::UpdateTileMappings avec la seule différence clé que D3D12 permet à une ressource réservée d’avoir des vignettes provenant de plusieurs tas.

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

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

  • Ressource réservée dont les mappages sont mis à jour. 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 réservée 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.
    • NumResourceRegions spécifie le nombre de régions.
    • pResourceRegionStartCoordinates et pResourceRegionSizes sont des tableaux qui identifient l’emplacement de début et l’extension de chaque région. Si NumResourceRegions a la valeur 1, l’un ou l’autre des tableaux qui décrivent les régions peuvent être NULL par souci de commodité. NULL pour pResourceRegionStartCoordinates signifie que la coordonnée de début est toutes 0s, et NULL pour pResourceRegionSizes identifie une région par défaut qui est l’ensemble complet de vignettes pour l’ensemble de la ressource réservée, y compris tous les mipmaps, les tranches de tableau ou les deux.
    • Si pResourceRegionStartCoordinates n’a pas la valeur NULL et que pResourceRegionSizes a la valeur NULL, la taille de région est par défaut 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 pResourceRegionStartCoordinates sans avoir à envoyer un tableau de pResourceRegionSizes 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.
  • Tas qui fournit de la mémoire à l’endroit où les mappages de vignettes peuvent aller. Si UpdateTileMappings définit uniquement des mappages NULL, vous n’avez pas besoin de spécifier un tas.
  • 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 tas (par défaut), un nombre de vignettes dans la ressource réservée à mapper à une seule vignette d’un tas (partage de la vignette), un nombre de mappages de vignettes dans la ressource réservée à ignorer et à laisser tels quels, ou un nombre de vignettes dans le tas à 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 vignette de la ressource réservée 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 s’aligner sur 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 réservée spécifiée ait un mappage spécifié.

    pRangeFlags, pHeapRangeStartOffsets 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 tas ; sinon, pour chaque plage i,pRangeFlags[i] identifie le fonctionnement des mappages dans cette plage de vignettes :

    • Si pRangeFlags[i] est D3D12_TILE_RANGE_FLAG_NONE, cette plage définit des vignettes séquentielles dans le tas, le nombre de vignettes étant pRangeTileCounts[i] et l’emplacement de départ pHeapRangeStartOffsets[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 D3D12_TILE_RANGE_FLAG_REUSE_SINGLE_TILE, pHeapRangeStartOffsets[i] identifie la vignette unique dans le tas à mapper et pRangeTileCounts[i] spécifie le nombre de vignettes des régions de vignette à mapper à cet emplacement de tas. 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 D3D12_TILE_RANGE_FLAG_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. pHeapRangeStartOffsets[i] est ignoré pour les mappages NULL.
    • Si pRangeFlags[i] est D3D12_TILE_RANGE_FLAG_SKIP, pRangeTileCounts[i] spécifie le nombre de vignettes des régions de vignette à 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. pHeapRangeStartOffsets[i] est ignoré pour les mappages SKIP.
Les ressources réservées doivent suivre les mêmes règles pour l’aliasing, l’initialisation et l’héritage des données que les ressources placées. Pour plus d’informations, consultez CreatePlacedResource .

Voici quelques exemples de cas updateTileMappings courants :

Exemples

Les exemples font référence aux structures et énumérations suivantes :

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

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

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

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

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

Exemple complexe : définition de mappages pour des régions avec des 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 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);

Spécifications

   
Plateforme cible Windows
En-tête d3d12.h

Voir aussi

CopyTileMappings

ID3D12CommandQueue

Ressources en mosaïque de volume