d3d/archive/D3D11_3_FunctionalSpec.htm [6467:6661]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// --------------------------------------------------------------------------------------------------------------------------------
// UpdateTileMappings
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters after validation of most parameters except that tile regions actually
// fit on the specified resource. The driver should ignore individual regions that are invalidly specified and then drop the
// remainder of the call (no need to back out progress so far). The debug runtime validates the parameters fully.
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory
// (possible if memory allocation for page table storage fails), tile mappings are left in their original state before the call.
//
// If a driver implements commandlists and out of memory occurs when executing UpdateTileMappings in a commandlist,
// the driver must invoke device removed. Applications can avoid this situation by only doing update calls that change existing
// mappings from Tiled Resources within command lists (so drivers will not have to allocate page table memory, only change the mapping).
//
// Note that many of the array parameters are optional and take special meaning if NULL as follows:
// If pTiledResourceRegionStartCoordinates is NULL at the API (only allowed if NumTiledResourceRegions is 1), the runtime fills in a default
// coordinate of {0,0,0,0} that is passed to the DDI (so the DDI will never see NULL).
// If pTiledResourceRegionSizes is NULL at the DDI, all regions are assumed to be a single tile. At the API if NumTiledResourceRegions 1,
// pTiledResourceregionStartCoordinates is NULL and pTiledResourceRegionSizes is NULL, the runtime calls the DDI with pTiledResourceRegionSizes
// filled in to cover the entire resource (so the DDI won't see NULL for pTiledResourceRegionSizes in this case).
//
// If pRangeFlags is NULL, all tile ranges have 0 for Range Flags.
// If pRangeTileCounts is NULL, all tile ranges have size 1 tile.
// If pRangeFlags[i] specifies WDDM1_3DDI_TILE_MAPPING_NULL or _SKIP, the corresponding entry in pTilePoolStartOffsets[i] is ignored,
// and if the call defines nothing but NULL/SKIPs pTilePoolStartOffsets can be NULL.
//
// At the API if NumRanges is 1 and pRangeTileCounts is 0, the runtime automatically fills in pRangeTileCounts[0] with the
// total number of tiles specified by all the Tile Regions.
//
// See the API description for examples of common calling patterns - it might make sense for drivers to special-case some of
// these if it turns out they could be executed more efficiently than through the path that handles the most general case.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_UPDATETILEMAPPINGS )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
UINT NumTiledResourceRegions,
_In_reads_(NumTiledResourceRegions) const D3DWDDM1_3DDI_TILED_RESOURCE_COORDINATE* pTiledResourceRegionStartCoordinates,
_In_reads_opt_(NumTiledResourceRegions) const D3DWDDM1_3DDI_TILE_REGION_SIZE* pTiledResourceRegionSizes,
D3D10DDI_HRESOURCE hTilePool,
UINT NumRanges,
_In_reads_opt_(NumRanges) const UINT* pRangeFlags, // D3DWDDM1_3DDI_TILE_RANGE_FLAG
_In_reads_opt_(NumRanges) const UINT* pTilePoolStartOffsets,
_In_reads_opt_(NumRanges) const UINT* pRangeTileCounts,
UINT Flags // D3DWDDM1_3DDI_TILE_MAPPING_FLAG
);
// --------------------------------------------------------------------------------------------------------------------------------
// CopyTileMappings
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation (it does drop the call if the regions don't fit).
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory
// (possible if memory allocation for page table storage fails), tile mappings are left in their original state before the call.
//
// If a driver implements commandlists and out of memory occurs when executing CopyTileMappings in a commandlist,
// the driver must invoke device removed. Applications can avoid this situation by only doing copy calls that change existing
// mappings from Tiled Resources within command lists (so drivers will not have to allocate page table memory, only change the mapping).
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_COPYTILEMAPPINGS )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hDestTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pDestRegionStartCoordinate,
D3D10DDI_HRESOURCE hSourceTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pSourceRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pTileRegionSize,
UINT Flags // WDDM1_3DDI_TILE_MAPPING_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// CopyTiles
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_COPYTILES )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pTileRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pTileRegionSize,
D3D10DDI_HRESOURCE hBuffer, // Default, dynamic or staging buffer
UINT64 BufferStartOffsetInBytes,
UINT Flags // WDDM1_3DDI_TILE_COPY_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// UpdateTiles
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_UPDATETILES )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hDestTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pDestTileRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pDestTileRegionSize,
_In_ const VOID* pSourceTileData, // caller memory
UINT Flags // WDDM1_3DDI_TILE_COPY_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// TiledResourceBarrier
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_TILEDRESOURCEBARRIER )(
D3D10DDI_HDEVICE hDevice,
D3D11DDI_HANDLETYPE TiledResourceAccessBeforeBarrierHandleType,
_In_opt_ const VOID* hTiledResourceAccessBeforeBarrier,
D3D11DDI_HANDLETYPE TiledResourceAccessAfterBarrierHandleType,
_In_opt_ const VOID* hTiledResourceAccessAfterBarrier
);
// --------------------------------------------------------------------------------------------------------------------------------
// GetMipPacking
// --------------------------------------------------------------------------------------------------------------------------------
// For a given tiled resource, returns how many mips are packed
// are packed and how many tiles are needed to store all the packed mips.
// Packed mips include cases where multiple small mips share tile(s) and
// also mips for which a given device cannot use standard tile shapes. It is possible
// for an entire resource to be considered packed.
//
// Applications are not told the tile shapes/layout for packed mips and must simply map
// all or none of the packed tiles if any of the mipmaps with are to be accessed.
// Otherwise the observed mapping of individual pixels accessed will be undefined - IHV specific.
//
// For array surfaces, the returned values are the counts for a single array slice,
// given the tile breakdown is identical for the mipmaps of each array slice.
//
// Mipmaps whose pixel dimensions fully fill at least one standard shaped tile in all
// dimensions are not allowed to be considered part of the set of packed mips, otherwise
// the runtime will remove the device on an invalid driver.
// One example of dimensions that a device can validly lump into
// the packed tiles (meaning the IHV can use its own custom tile breakdown) is
// a mip that is at least one tile wide but less than a tile high. Ideally though,
// a device would stick with the standard tile breakdown for this case (so the application can
// manage the tiles in a standard way). If a device does need to use a custom tiling,
// the application is not told what the tile breakdown is (only how many tiles are involved
// in the packing overall), and thus loses some freedom.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_GETMIPPACKING )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
_Out_ UINT* pNumPackedMips, // How many mips are packed, for a given array slice,
// including any mips that don't use the standard tile
// shapes. If there is no packing, return 0.
_Out_ UINT* pNumTilesForPackedMips, // How many tiles the packed mips fit into,
// for a given array slice. Ignored if
// *pNumPackedMips returned 0.
);
// --------------------------------------------------------------------------------------------------------------------------------
// CheckMultisampleQualityLevels
// --------------------------------------------------------------------------------------------------------------------------------
// Variant of the existing DDI for checking multisample quality level support with a new flags field that allows
// tiled resource to be specified.
//
typedef enum WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_FLAGS
{
WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_TILED_RESOURCE = 0x00000001,
};
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_CHECKMULTISAMPLEQUALITYLEVELS )(
D3D10DDI_HDEVICE hDevice,
DXGI_FORMAT Format,
UINT SampleCount,
UINT Flags, // WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_FLAGS
_Out_ UINT* pNumQualityLevels
);
// --------------------------------------------------------------------------------------------------------------------------------
// ResizeTilePool
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation (it does fail the API call if the size is not a multiple
// of tile size or 0).
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory,
// tile mappings are left in their original state before the call.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_RESIZETILEPOOL )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTilePool,
UINT64 NewSizeInBytes
);
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
d3d/archive/images/d3d11/D3D11_3_FunctionalSpec.htm [5834:6028]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// --------------------------------------------------------------------------------------------------------------------------------
// UpdateTileMappings
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters after validation of most parameters except that tile regions actually
// fit on the specified resource. The driver should ignore individual regions that are invalidly specified and then drop the
// remainder of the call (no need to back out progress so far). The debug runtime validates the parameters fully.
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory
// (possible if memory allocation for page table storage fails), tile mappings are left in their original state before the call.
//
// If a driver implements commandlists and out of memory occurs when executing UpdateTileMappings in a commandlist,
// the driver must invoke device removed. Applications can avoid this situation by only doing update calls that change existing
// mappings from Tiled Resources within command lists (so drivers will not have to allocate page table memory, only change the mapping).
//
// Note that many of the array parameters are optional and take special meaning if NULL as follows:
// If pTiledResourceRegionStartCoordinates is NULL at the API (only allowed if NumTiledResourceRegions is 1), the runtime fills in a default
// coordinate of {0,0,0,0} that is passed to the DDI (so the DDI will never see NULL).
// If pTiledResourceRegionSizes is NULL at the DDI, all regions are assumed to be a single tile. At the API if NumTiledResourceRegions 1,
// pTiledResourceregionStartCoordinates is NULL and pTiledResourceRegionSizes is NULL, the runtime calls the DDI with pTiledResourceRegionSizes
// filled in to cover the entire resource (so the DDI won't see NULL for pTiledResourceRegionSizes in this case).
//
// If pRangeFlags is NULL, all tile ranges have 0 for Range Flags.
// If pRangeTileCounts is NULL, all tile ranges have size 1 tile.
// If pRangeFlags[i] specifies WDDM1_3DDI_TILE_MAPPING_NULL or _SKIP, the corresponding entry in pTilePoolStartOffsets[i] is ignored,
// and if the call defines nothing but NULL/SKIPs pTilePoolStartOffsets can be NULL.
//
// At the API if NumRanges is 1 and pRangeTileCounts is 0, the runtime automatically fills in pRangeTileCounts[0] with the
// total number of tiles specified by all the Tile Regions.
//
// See the API description for examples of common calling patterns - it might make sense for drivers to special-case some of
// these if it turns out they could be executed more efficiently than through the path that handles the most general case.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_UPDATETILEMAPPINGS )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
UINT NumTiledResourceRegions,
_In_reads_(NumTiledResourceRegions) const D3DWDDM1_3DDI_TILED_RESOURCE_COORDINATE* pTiledResourceRegionStartCoordinates,
_In_reads_opt_(NumTiledResourceRegions) const D3DWDDM1_3DDI_TILE_REGION_SIZE* pTiledResourceRegionSizes,
D3D10DDI_HRESOURCE hTilePool,
UINT NumRanges,
_In_reads_opt_(NumRanges) const UINT* pRangeFlags, // D3DWDDM1_3DDI_TILE_RANGE_FLAG
_In_reads_opt_(NumRanges) const UINT* pTilePoolStartOffsets,
_In_reads_opt_(NumRanges) const UINT* pRangeTileCounts,
UINT Flags // D3DWDDM1_3DDI_TILE_MAPPING_FLAG
);
// --------------------------------------------------------------------------------------------------------------------------------
// CopyTileMappings
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation (it does drop the call if the regions don't fit).
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory
// (possible if memory allocation for page table storage fails), tile mappings are left in their original state before the call.
//
// If a driver implements commandlists and out of memory occurs when executing CopyTileMappings in a commandlist,
// the driver must invoke device removed. Applications can avoid this situation by only doing copy calls that change existing
// mappings from Tiled Resources within command lists (so drivers will not have to allocate page table memory, only change the mapping).
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_COPYTILEMAPPINGS )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hDestTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pDestRegionStartCoordinate,
D3D10DDI_HRESOURCE hSourceTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pSourceRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pTileRegionSize,
UINT Flags // WDDM1_3DDI_TILE_MAPPING_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// CopyTiles
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_COPYTILES )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pTileRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pTileRegionSize,
D3D10DDI_HRESOURCE hBuffer, // Default, dynamic or staging buffer
UINT64 BufferStartOffsetInBytes,
UINT Flags // WDDM1_3DDI_TILE_COPY_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// UpdateTiles
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_UPDATETILES )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hDestTiledResource,
_In_ const WDDM1_3DDI_TILED_RESOURCE_COORDINATE* pDestTileRegionStartCoordinate,
_In_ const WDDM1_3DDI_TILE_REGION_SIZE* pDestTileRegionSize,
_In_ const VOID* pSourceTileData, // caller memory
UINT Flags // WDDM1_3DDI_TILE_COPY_FLAGS
);
// --------------------------------------------------------------------------------------------------------------------------------
// TiledResourceBarrier
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation.
//
// This DDI is not expected to fail (runtime will not check).
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_TILEDRESOURCEBARRIER )(
D3D10DDI_HDEVICE hDevice,
D3D11DDI_HANDLETYPE TiledResourceAccessBeforeBarrierHandleType,
_In_opt_ const VOID* hTiledResourceAccessBeforeBarrier,
D3D11DDI_HANDLETYPE TiledResourceAccessAfterBarrierHandleType,
_In_opt_ const VOID* hTiledResourceAccessAfterBarrier
);
// --------------------------------------------------------------------------------------------------------------------------------
// GetMipPacking
// --------------------------------------------------------------------------------------------------------------------------------
// For a given tiled resource, returns how many mips are packed
// are packed and how many tiles are needed to store all the packed mips.
// Packed mips include cases where multiple small mips share tile(s) and
// also mips for which a given device cannot use standard tile shapes. It is possible
// for an entire resource to be considered packed.
//
// Applications are not told the tile shapes/layout for packed mips and must simply map
// all or none of the packed tiles if any of the mipmaps with are to be accessed.
// Otherwise the observed mapping of individual pixels accessed will be undefined - IHV specific.
//
// For array surfaces, the returned values are the counts for a single array slice,
// given the tile breakdown is identical for the mipmaps of each array slice.
//
// Mipmaps whose pixel dimensions fully fill at least one standard shaped tile in all
// dimensions are not allowed to be considered part of the set of packed mips, otherwise
// the runtime will remove the device on an invalid driver.
// One example of dimensions that a device can validly lump into
// the packed tiles (meaning the IHV can use its own custom tile breakdown) is
// a mip that is at least one tile wide but less than a tile high. Ideally though,
// a device would stick with the standard tile breakdown for this case (so the application can
// manage the tiles in a standard way). If a device does need to use a custom tiling,
// the application is not told what the tile breakdown is (only how many tiles are involved
// in the packing overall), and thus loses some freedom.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_GETMIPPACKING )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTiledResource,
_Out_ UINT* pNumPackedMips, // How many mips are packed, for a given array slice,
// including any mips that don't use the standard tile
// shapes. If there is no packing, return 0.
_Out_ UINT* pNumTilesForPackedMips, // How many tiles the packed mips fit into,
// for a given array slice. Ignored if
// *pNumPackedMips returned 0.
);
// --------------------------------------------------------------------------------------------------------------------------------
// CheckMultisampleQualityLevels
// --------------------------------------------------------------------------------------------------------------------------------
// Variant of the existing DDI for checking multisample quality level support with a new flags field that allows
// tiled resource to be specified.
//
typedef enum WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_FLAGS
{
WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_TILED_RESOURCE = 0x00000001,
};
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_CHECKMULTISAMPLEQUALITYLEVELS )(
D3D10DDI_HDEVICE hDevice,
DXGI_FORMAT Format,
UINT SampleCount,
UINT Flags, // WDDM1_3DDI_CHECK_MULTISAMPLE_QUALITY_LEVELS_FLAGS
_Out_ UINT* pNumQualityLevels
);
// --------------------------------------------------------------------------------------------------------------------------------
// ResizeTilePool
// --------------------------------------------------------------------------------------------------------------------------------
// See API - runtime simply passes through parameters with minimal validation (it does fail the API call if the size is not a multiple
// of tile size or 0).
//
// Errors are reported via the call back pfnSetErrorCb. Valid errors are out of memory and device removed. On out of memory,
// tile mappings are left in their original state before the call.
//
typedef VOID ( APIENTRY* PFND3DWDDM1_3DDI_RESIZETILEPOOL )(
D3D10DDI_HDEVICE hDevice,
D3D10DDI_HRESOURCE hTilePool,
UINT64 NewSizeInBytes
);
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -