ID3D12Device::GetCopyableFootprints method (d3d12.h)

Article
10/13/2021

Gets a resource layout that can be copied. Helps the app fill-in D3D12_PLACED_SUBRESOURCE_FOOTPRINT and D3D12_SUBRESOURCE_FOOTPRINT when suballocating space in upload heaps.

Syntax

void GetCopyableFootprints(
  [in]            const D3D12_RESOURCE_DESC          *pResourceDesc,
  [in]            UINT                               FirstSubresource,
  [in]            UINT                               NumSubresources,
                  UINT64                             BaseOffset,
  [out, optional] D3D12_PLACED_SUBRESOURCE_FOOTPRINT *pLayouts,
  [out, optional] UINT                               *pNumRows,
  [out, optional] UINT64                             *pRowSizeInBytes,
  [out, optional] UINT64                             *pTotalBytes
);

Parameters

[in] pResourceDesc

Type: const D3D12_RESOURCE_DESC*

A description of the resource, as a pointer to a D3D12_RESOURCE_DESC structure.

[in] FirstSubresource

Type: UINT

Index of the first subresource in the resource. The range of valid values is 0 to D3D12_REQ_SUBRESOURCES.

[in] NumSubresources

Type: UINT

The number of subresources in the resource. The range of valid values is 0 to (D3D12_REQ_SUBRESOURCES - FirstSubresource).

BaseOffset

Type: UINT64

The offset, in bytes, to the resource.

[out, optional] pLayouts

Type: D3D12_PLACED_SUBRESOURCE_FOOTPRINT*

A pointer to an array (of length NumSubresources) of D3D12_PLACED_SUBRESOURCE_FOOTPRINT structures, to be filled with the description and placement of each subresource.

[out, optional] pNumRows

Type: UINT*

A pointer to an array (of length NumSubresources) of integer variables, to be filled with the number of rows for each subresource.

[out, optional] pRowSizeInBytes

Type: UINT64*

A pointer to an array (of length NumSubresources) of integer variables, each entry to be filled with the unpadded size in bytes of a row, of each subresource.

For example, if a Texture2D resource has a width of 32 and bytes per pixel of 4,

then pRowSizeInBytes returns 128.

pRowSizeInBytes should not be confused with row pitch, as examining pLayouts and getting the row pitch from that will give you 256 as it is aligned to D3D12_TEXTURE_DATA_PITCH_ALIGNMENT.

[out, optional] pTotalBytes

Type: UINT64*

A pointer to an integer variable, to be filled with the total size, in bytes.

Return value

None

Remarks

This routine assists the application in filling out D3D12_PLACED_SUBRESOURCE_FOOTPRINT and D3D12_SUBRESOURCE_FOOTPRINT structures, when suballocating space in upload heaps. The resulting structures are GPU adapter-agnostic, meaning that the values will not vary from one GPU adapter to the next. GetCopyableFootprints uses specified details about resource formats, texture layouts, and alignment requirements (from the D3D12_RESOURCE_DESC structure) to fill out the subresource structures. Applications have access to all these details, so this method, or a variation of it, could be written as part of the app.

Examples

The D3D12Multithreading sample uses ID3D12Device::GetCopyableFootprints as follows:

// Returns required size of a buffer to be used for data upload
inline UINT64 GetRequiredIntermediateSize(
    _In_ ID3D12Resource* pDestinationResource,
    _In_range_(0,D3D12_REQ_SUBRESOURCES) UINT FirstSubresource,
    _In_range_(0,D3D12_REQ_SUBRESOURCES-FirstSubresource) UINT NumSubresources)
{
    D3D12_RESOURCE_DESC Desc = pDestinationResource->GetDesc();
    UINT64 RequiredSize = 0;
    
    ID3D12Device* pDevice;
    pDestinationResource->GetDevice(__uuidof(*pDevice), reinterpret_cast<void**>(&pDevice));
    pDevice->GetCopyableFootprints(&Desc, FirstSubresource, NumSubresources, 0, nullptr, nullptr, nullptr, &RequiredSize);
    pDevice->Release();
    
    return RequiredSize;
}

Refer to the Example Code in the D3D12 Reference.

Requirements

Requirement	Value
Target Platform	Windows
Header	d3d12.h
Library	D3d12.lib
DLL	D3d12.dll