ID3D12GraphicsCommandList::CopyResource method

Copies the entire contents of the source resource to the destination resource.

Syntax

void CopyResource(
  ID3D12Resource *pDstResource,
  ID3D12Resource *pSrcResource
);

Parameters

pDstResource

Type: ID3D12Resource*

A pointer to the ID3D12Resourceinterface that represents the destination resource.

pSrcResource

Type: ID3D12Resource*

A pointer to the ID3D12Resourceinterface that represents the source resource.

Return Value

This method does not return a value.

Remarks

CopyResource operations are performed on the GPU and do not incur a significant CPU workload linearly dependent on the size of the data to copy.

CopyResource may be used to initialize resources which alias the same heap memory. See CreatePlacedResource for more details.

Debug layer

The debug layer will issue an error if the source subresource is not in the D3D12_RESOURCE_STATE_COPY_SOURCE state.

The debug layer will issue an error if the destination subresource is not in the D3D12_RESOURCE_STATE_COPY_DEST state.

This method has a few restrictions designed for improving performance. For instance, the source and destination resources:

  • Must be different resources.
  • Must be the same type.
  • Must have identical dimensions (including width, height, depth, and size as appropriate).
  • Must have compatible DXGI formats, which means the formats must be identical or at least from the same type group. For example, a DXGI_FORMAT_R32G32B32_FLOAT texture can be copied to an DXGI_FORMAT_R32G32B32_UINT texture since both of these formats are in the DXGI_FORMAT_R32G32B32_TYPELESS group. CopyResource can copy between a few format types. For more info, see Format Conversion using Direct3D 10.1.
  • Can't be currently mapped.
CopyResource only supports copy; it doesn't support any stretch, color key, or blend. CopyResource can reinterpret the resource data between a few format types. For more info, see Format Conversion using Direct3D 10.1.

You can't use an Immutable resource as a destination. You can use a depth-stencil resource as either a source or a destination provided that the feature level is D3D_FEATURE_LEVEL_10_1 or greater. For feature levels 9_x, resources created with the D3D12_RESOURCE_MISC_ALLOW_DEPTH_STENCIL flag can only be used as a source for CopyResource. Resources created with multi-sampling capability (see DXGI_SAMPLE_DESC) can be used as source and destination only if both source and destination have identical multi-sampled count and quality. If source and destination differ in multi-sampled count and quality or if one is multi-sampled and the other is not multi-sampled, the call to CopyResource fails. Use ResolveSubresource to resolve a multi-sampled resource to a resource that is not multi-sampled.

The method is an asynchronous call, which may be added to the command-buffer queue. This attempts to remove pipeline stalls that may occur when copying data. For more info, see performance considerations.

Consider using CopyTextureRegion or CopyBufferRegion if you only need to copy a portion of the data in a resource.

Examples

The D3D12HeterogeneousMultiadapter sample uses CopyResource in the following way:

	// Command list to copy the render target to the shared heap on the primary adapter. 
 	{ 
 		const GraphicsAdapter adapter = Primary; 
 
 
 		// Reset the copy command allocator and command list. 
 		ThrowIfFailed(m_copyCommandAllocators[m_frameIndex]->Reset()); 
 		ThrowIfFailed(m_copyCommandList->Reset(m_copyCommandAllocators[m_frameIndex].Get(), nullptr)); 
 
 
 		// Copy the intermediate render target to the cross-adapter shared resource. 
 		// Transition barriers are not required since there are fences guarding against 
 		// concurrent read/write access to the shared heap. 
 		if (m_crossAdapterTextureSupport) 
 		{ 
 			// If cross-adapter row-major textures are supported by the adapter, 
 			// simply copy the texture into the cross-adapter texture. 
 			m_copyCommandList->CopyResource(m_crossAdapterResources[adapter][m_frameIndex].Get(), m_renderTargets[adapter][m_frameIndex].Get()); 
 		} 
 		else 
 		{ 
 			// If cross-adapter row-major textures are not supported by the adapter, 
 			// the texture will be copied over as a buffer so that the texture row 
 			// pitch can be explicitly managed. 
 
 
 			// Copy the intermediate render target into the shared buffer using the 
 			// memory layout prescribed by the render target. 
 			D3D12_RESOURCE_DESC renderTargetDesc = m_renderTargets[adapter][m_frameIndex]->GetDesc(); 
 			D3D12_PLACED_SUBRESOURCE_FOOTPRINT renderTargetLayout; 
 
 
 			m_devices[adapter]->GetCopyableFootprints(&renderTargetDesc, 0, 1, 0, &renderTargetLayout, nullptr, nullptr, nullptr); 
 
 
 			CD3DX12_TEXTURE_COPY_LOCATION dest(m_crossAdapterResources[adapter][m_frameIndex].Get(), renderTargetLayout); 
 			CD3DX12_TEXTURE_COPY_LOCATION src(m_renderTargets[adapter][m_frameIndex].Get(), 0); 
 			CD3DX12_BOX box(0, 0, m_width, m_height); 
 
 
 			m_copyCommandList->CopyTextureRegion(&dest, 0, 0, 0, &src, &box); 
		} 

 
		ThrowIfFailed(m_copyCommandList->Close()); 
	} 

Requirements

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

See Also

ID3D12GraphicsCommandList