Edit

Subresources (Direct3D 12 Graphics)

  • Article

Describes how a resource is divided into subresources, and how to reference a single, multiple or slice of subresources.

Example subresources

If a resource contains a buffer, then it simply contains one subresource with an index of 0. If the resource contains a texture (or texture array), then referencing the subresources is more complex.

Some APIs access an entire resource (such as the ID3D12GraphicsCommandList::CopyResource method), others access a portion of a resource (for example the ID3D12Resource::ReadFromSubresource method). The methods that access a portion of a resource generally use a view description (such as the D3D12_TEX2D_ARRAY_SRV structure) to specify the subresources to access. Refer to the Subresource APIs section for a complete list.

Subresource indexing

To index a particular subresource, the mip levels are indexed first as each array entry is indexed.

subresource indexing

Mip slice

A mip slice includes one mipmap level for every texture in an array, as shown in the following image.

subresource mip slices

Array slice

Given an array of textures, each texture with mipmaps, an array slice includes one texture and all of its mip levels, as shown in the following image.

subresource array slices

Plane slice

Typically planar formats are not used to store RGBA data, but in the cases where it is (perhaps 24bpp RGB data), one plane could represent the red image, one the green, and one the blue image. One plane though is not necessarily one color, two or more colors could be combined into one plane. More typically planar data is used for sub-sampled YCbCr and Depth-Stencil data. Depth-Stencil is the only format that fully supports mipmaps, arrays, and multiple planes (often plane 0 for Depth and plane 1 for Stencil).

The subresource indexing for an array of two Depth-Stencil images, each with three mip levels, is shown below.

depth stencil indexing

Sub-sampled YCbCr supports arrays and has planes, but does not support mipmaps. YCbCr images have two planes, one for the luminance (Y) that the human eye is most sensitive to, and one for the chrominance (both Cb, and Cr, interleaved) which the human eye is less sensitive to. This format enables compression of the chrominance values in order to compress an image without affecting the luminance, and is a common video compression format for that reason, although it is used to compress still images. The image below shows the NV12 format, noting the chrominance has been compressed to one quarter of the resolution of the luminance, meaning the width of each plane is identical, and the chrominance plane is half the height of the luminance plane. The planes would be indexed as subresources in an identical way to the Depth-Stencil example above.

the nv12 format

Planar formats existed in Direct3D 11, but individual planes could not be addressed individually, say for copy or mapping operations. This was changed in Direct3D 12 so that each plane received its own subresource ID. Compare the following two methods for calculating the subresource ID.

Direct3D 11

inline UINT D3D11CalcSubresource( UINT MipSlice, UINT ArraySlice, UINT MipLevels )
{
    return MipSlice + (ArraySlice * MipLevels); 
}

Direct3D 12

inline UINT D3D12CalcSubresource( UINT MipSlice, UINT ArraySlice, UINT PlaneSlice, UINT MipLevels, UINT ArraySize )
{ 
    return MipSlice + (ArraySlice * MipLevels) + (PlaneSlice * MipLevels * ArraySize); 
}

Most hardware assumes that the memory for plane N is always immediately allocated after plane N-1.

An alternative to using subresources is that an app could allocate a completely separate resource per plane. In this case, the application understands the data is planar and uses multiple resources to represent it.

Multiple subresources

A shader-resource view can select any rectangular region of subresources, using one of the slices described above and judicious use of fields in the view structures (such as D3D12_TEX2D_ARRAY_SRV), as shown in the image.

multiple subresource selection

A render-target view can only use a single subresource or mip slice and cannot include subresources from more than one mip slice. That is, every texture in a render-target view must be the same size. A shader-resource view can select any rectangular region of subresources, as shown in the image.

Subresource APIs

The following APIs reference and work with subresources:

Enumerations:

The following structures contain PlaneSlice indexes, most contain MipSlice indexes.

The following structures contain ArraySlice indexes, most contain MipSlice indexes.

The following structures contain MipSlice indexes, but neither ArraySlice nor PlaneSlice indexes.

The following structures also reference subresources:

Methods:

Textures must be in the D3D12_RESOURCE_STATE_COMMON state for CPU access through WriteToSubresource and ReadFromSubresource to be legal; but buffers do not. CPU access to a resource is typically done through Map/Unmap.

Resource Binding