ID3D11DeviceContext2::UpdateTileMappings Method

Updates mappings of tile locations in tiled resources to memory locations in a tile pool.

Syntax

public:
HRESULT UpdateTileMappings(
         ID3D11Resource *pTiledResource,
         UINT NumTiledResourceRegions,
         const D3D11_TILED_RESOURCE_COORDINATE *pTiledResourceRegionStartCoordinates,
         const D3D11_TILE_REGION_SIZE *pTiledResourceRegionSizes,
         ID3D11Buffer *pTilePool,
         UINT NumRanges,
         const UINT *pRangeFlags,
         const UINT *pTilePoolStartOffsets,
         const UINT *pRangeTileCounts,
         UINT Flags
)

Parameters

pTiledResource
Type: ID3D11Resource *

[in] The tiled resource, as a pointer to ID3D11Resource.

NumTiledResourceRegions
Type: UINT 

[in] The number of tiled resource regions.

pTiledResourceRegionStartCoordinates
Type: D3D11_TILED_RESOURCE_COORDINATE *

[in, optional] An array of D3D11_TILED_RESOURCE_COORDINATE structures that describe the starting coordinates of the tiled resource regions. The NumTiledResourceRegions parameter specifies the number of D3D11_TILED_RESOURCE_COORDINATE structures in the array.

pTiledResourceRegionSizes
Type: D3D11_TILE_REGION_SIZE *

[in, optional] An array of D3D11_TILE_REGION_SIZE structures that describe the sizes of the tiled resource regions. The NumTiledResourceRegions parameter specifies the number of D3D11_TILE_REGION_SIZE structures in the array.

pTilePool
Type: ID3D11Buffer *

[in, optional] The tile pool, as a pointer to ID3D11Buffer.

NumRanges
Type: UINT 

[in] The number of tile-pool ranges.

pRangeFlags
Type: UINT *

[in, optional] An array of values that describe each tile-pool range. The NumRanges parameter specifies the number of values in the array. Each value can be a bitwise-OR’d combination of D3D11_TILE_RANGE_FLAG-typed values.

pTilePoolStartOffsets
Type: UINT *

[in, optional] An array of offsets into the tile pool. These are 0-based tile offsets, counting in tiles (not bytes).

pRangeTileCounts
Type: UINT *

[in, optional] An array of tiles. An array of values that specify the number of tiles in each tile-pool range. The NumRanges parameter specifies the number of values in the array.

Flags
Type: UINT 

[in] A combination of D3D11_TILE_MAPPING_FLAG enumeration values that are combined by using a bitwise-OR operation.

Return value

Type: HRESULT 

Returns S_OK if successful; otherwise, returns one of the following:

Remarks

In a single call to UpdateTileMappings, you can map one or more ranges of resource tiles to one or more ranges of tile-pool tiles.

You can organize the parameters of UpdateTileMappings in these ways to perform an update:

If pTiledResourceRegionStartCoordinates isn’t NULL and pTiledResourceRegionSizes is NULL, the region size defaults to 1 tile for all regions. This makes it easy to define mappings for a set of individual tiles each at disparate locations by providing an array of locations in pTiledResourceRegionStartCoordinates without having to send an array of pTiledResourceRegionSizes all set to 1. The updates are applied from first region to last; so, if regions overlap in a single call, the updates later in the list overwrite the areas that overlap with previous updates.

NumRanges specifies the number of tile ranges, where the total tiles identified across all ranges must match the total number of tiles in the tile regions from the previously described tiled resource. Mappings are defined by iterating through the tiles in the tile regions in sequential order (x then y then z order for box regions) while walking through the set of tile ranges in sequential order. The breakdown of tile regions doesn’t have to line up with the breakdown of tile ranges, but the total number of tiles on both sides must be equal so that each tiled resource tile specified has a mapping specified. pRangeFlags, pTilePoolStartOffsets, and pRangeTileCounts are all arrays, of size NumRanges, that describe the tile ranges. If pRangeFlags is NULL, all ranges are sequential tiles in the tile pool; otherwise, for each range i, pRangeFlags[i] identifies how the mappings in that range of tiles work:

* If pRangeFlags[i] is 0, that range defines sequential tiles in the tile pool, with the number of tiles being pRangeTileCounts[i] and the starting location pTilePoolStartOffsets[i]. If NumRanges is 1, pRangeTileCounts can be NULL and defaults to the total number of tiles specified by all the tile regions.
* If pRangeFlags[i] is D3D11_TILE_RANGE_REUSE_SINGLE_TILE, pTilePoolStartOffsets[i] identifies the single tile in the tile pool to map to, and pRangeTileCounts[i] specifies how many tiles from the tile regions to map to that tile pool location. If NumRanges is 1, pRangeTileCounts can be NULL and defaults to the total number of tiles specified by all the tile regions.
* If pRangeFlags[i] is D3D11_TILE_RANGE_NULL, pRangeTileCounts[i] specifies how many tiles from the tile regions to map to NULL. If NumRanges is 1, pRangeTileCounts can be NULL and defaults to the total number of tiles specified by all the tile regions. pTilePoolStartOffsets[i] is ignored for NULL mappings.
* If pRangeFlags[i] is D3D11_TILE_RANGE_SKIP, pRangeTileCounts[i] specifies how many tiles from the tile regions to skip over and leave existing mappings unchanged for. This can be useful if a tile region conveniently bounds an area of tile mappings to update except with some exceptions that need to be left the same as whatever they were mapped to before. pTilePoolStartOffsets[i] is ignored for SKIP mappings.

If tile mappings have changed on a tiled resource that the app will render via ID3D11RenderTargetView or ID3D11DepthStencilView, the app must clear, by using the fixed function Clear APIs, the tiles that have changed within the area being rendered (mapped or not). If an app doesn’t clear in these situations, the app receives undefined values when it reads from the tiled resource.

Note In Direct3D 11.2, hardware can now support ID3D11DeviceContext1::ClearView on depth-only formats. For more info, see D3D11_FEATURE_DATA_D3D11_OPTIONS1 structure.

If an app needs to preserve existing memory contents of areas in a tiled resource where mappings have changed, the app can first save the contents where tile mappings have changed, by copying them to a temporary surface - such as by using ID3D11DeviceContext2::CopyTiles, issuing the required Clear, and then copying the contents back.

Suppose a tile is mapped into multiple tiled resources at the same time and tile contents are manipulated by any means (such as by render or copy) via one of the tiled resources. Then, if the same tile is to be rendered via any other tiled resource, the tile must be cleared first as previously described.

Here are some examples of common UpdateTileMappings cases:

Example

Clearing an entire surface’s mappings to NULL:

C++

// - 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,0,D3D11_TILE_MAPPING_NO_OVERWRITE);

Mapping a region of tiles to a single tile:

C++

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

Defining mappings for a set of disjoint individual tiles:

C++

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

Complex example - defining mappings for regions with some skips, some NULL mappings:

C++

// - This complex example hard codes the parameter arrays, whereas in practice the
//   application would likely configure the paramaters 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 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

C++

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

Requirements

Header: Declared in d3d11_x.h (d3d11_2.h on other Windows platforms).

Library: Use d3d11_x.lib (d3d11.lib on other Windows platforms).

See also

ID3D11DeviceContext2

ID3D11DeviceContext2 Members