ID3D12XboxDmaCommandList::CopyTextureRegion Method

Copies a region of a source texture to a specified location in a destination texture.

Syntax

public:
void CopyTextureRegion(
         const D3D12_TEXTURE_COPY_LOCATION *pDst,
         UINT DstX,
         UINT DstY,
         UINT DstZ,
         const D3D12_TEXTURE_COPY_LOCATION *pSrc,
         const D3D12_BOX *pSrcBox
)

Parameters

pDst
Type: D3D12_TEXTURE_COPY_LOCATION *

[in] A pointer to a view description for the destination subresource. this pDstViewDesc parameter can point to a D3D12_TEXTURE_COPY_LOCATION or D3D12_PLACED_PITCHED_SUBRESOURCE_DESC structure.

DstX
Type: UINT

The x-coordinate of the upper left corner of the destination region.

DstY
Type: UINT

The y-coordinate of the upper left corner of the destination region. For a 1D subresource, this must be zero.

DstZ
Type: UINT

The z-coordinate of the upper left corner of the destination region. For a 1D or 2D subresource, this must be zero.

pSrc
Type: D3D12_TEXTURE_COPY_LOCATION *

[in] Specifies the source D3D12_TEXTURE_COPY_LOCATION.

pSrcBox
Type: D3D12_BOX *

[in, optional] Specifies an optional D3D12_BOX that sets the size of the source texture to copy.

Return value

None.

Remarks

This API is intended for calling at high frequency. Callers can reduce memory by making iterative calls that update progressive regions of the texture, while provide a small buffer during each call. It is most efficient to specify large enough regions, though, because this enables the driver to fill whole cache lines in the texture before returning.

For efficiency, ensure the bounds and alignment of the extents within the box are 64 / [Bytes per pixel] pixels horizontally. Vertical bounds and alignment should be 2 rows, except when 1 byte per pixel formats are used, in which case 4 rows are recommended. Single depth slices per call are handled efficiently. It is recommended but not necessary to provide pointers and strides which are 128-byte aligned.

When writing to sub mipmap levels, it is recommended to use larger width and heights than described above. This is because small mipmap levels may actually be stored within a larger block of memory, with an opaque amount of offsetting which can interfere with alignment to cache lines.

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 CopyTextureRegion is undefined. If you created a device that supports the debug layer, the debug output reports an error on this invalid CopyTextureRegion call. Invalid parameters to CopyTextureRegion 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.

CopyTextureRegion 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. CopyTextureRegion can copy between a few format types.
May not be currently mapped.

CopyTextureRegion only supports copy; it does not support any stretch, color key, or blend. CopyTextureRegion can reinterpret the resource data between a few format types.

If your app needs to copy an entire resource, we recommend to use ID3D12XboxDmaCommandList::CopyResource instead.

CopyTextureRegion 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.

Note If you use CopyTextureRegion with a depth-stencil buffer or a multisampled resource, you must copy the whole subresource. In this situation, you must pass 0 to the DstX, DstY, and DstZ parameters and NULL to the pSrcBox parameter. In addition, source and destination resources, which are represented by the pSrcResource and pDstResource parameters, should have identical sample count values.

Related: ID3D12GraphicsCommandList::CopyTextureRegion in the D3D12/PC documentation.

Example

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.

D3D12_BOX sourceRegion;
sourceRegion.left = 120;
sourceRegion.right = 200;
sourceRegion.top = 100;
sourceRegion.bottom = 220;
sourceRegion.front = 0;
sourceRegion.back = 1;


pDmaCmdList -> CopyTextureRegion( pDestTexture, 10, 20, 0, pSourceTexture, &sourceRegion );

Notice, that for a 2D texture, front and back are set to 0 and 1 respectively.

Requirements

Header: Declared in d3d12_x.h.

Library: Use d3d12_x.lib.