Copy a region from a source resource to a destination resource.
void CopySubresourceRegion( [in] ID3D11Resource *pDstResource, [in] UINT DstSubresource, [in] UINT DstX, [in] UINT DstY, [in] UINT DstZ, [in] ID3D11Resource *pSrcResource, [in] UINT SrcSubresource, [in, optional] const D3D11_BOX *pSrcBox );
- pDstResource [in]
A pointer to the destination resource (see ID3D11Resource).
- DstSubresource [in]
Destination subresource index.
- DstX [in]
The x-coordinate of the upper left corner of the destination region.
- DstY [in]
The y-coordinate of the upper left corner of the destination region. For a 1D subresource, this must be zero.
- DstZ [in]
The z-coordinate of the upper left corner of the destination region. For a 1D or 2D subresource, this must be zero.
- pSrcResource [in]
A pointer to the source resource (see ID3D11Resource).
- SrcSubresource [in]
Source subresource index.
- pSrcBox [in, optional]
Type: const D3D11_BOX*
A pointer to a 3D box (see D3D11_BOX) that defines the source subresource that can be copied. If NULL, the entire source subresource is copied. The box must fit within the source resource.
An empty box results in a no-op. A box is empty if the top value is greater than or equal to the bottom value, or the left value is greater than or equal to the right value, or the front value is greater than or equal to the back value. When the box is empty, CopySubresourceRegion doesn't perform a copy operation.
The source box must be within the size of the source resource. The destination offsets, (x, y, and z), allow the source box to be offset when writing into the destination resource; however, the dimensions of the source box and the offsets must be within the size of the resource. If you try and copy outside the destination resource or specify a source box that is larger than the source resource, the behavior of CopySubresourceRegion is undefined. If you created a device that supports the debug layer, the debug output reports an error on this invalid CopySubresourceRegion call. Invalid parameters to CopySubresourceRegion cause undefined behavior and might result in incorrect rendering, clipping, no copy, or even the removal of the rendering device.
If the resources are buffers, all coordinates are in bytes; if the resources are textures, all coordinates are in texels. D3D11CalcSubresource is a helper function for calculating subresource indexes.
CopySubresourceRegion performs the copy on the GPU (similar to a memcpy by the CPU). As a consequence, the source and destination resources:
- Must be different subresources (although they can be from the same resource).
- Must be the same type.
- Must have compatible DXGI formats (identical or 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. CopySubresourceRegion can copy between a few format types. For more info, see Format Conversion using Direct3D 10.1.
- May not be currently mapped.
CopySubresourceRegion only supports copy; it does not support any stretch, color key, or blend. CopySubresourceRegion can reinterpret the resource data between a few format types. For more info, see Format Conversion using Direct3D 10.1.
If your app needs to copy an entire resource, we recommend to use ID3D11DeviceContext::CopyResource instead.
CopySubresourceRegion 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 information about pipeline stalls, see performance considerations.
The following code snippet copies a box (located at (120,100),(200,220)) from a source texture into a reqion (10,20),(90,140) in a destination texture.
D3D11_BOX sourceRegion; sourceRegion.left = 120; sourceRegion.right = 200; sourceRegion.top = 100; sourceRegion.bottom = 220; sourceRegion.front = 0; sourceRegion.back = 1; pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion );
Notice, that for a 2D texture, front and back are set to 0 and 1 respectively.