Edit

Share via

ID3D11Device3::ReadFromSubresource method (d3d11_3.h)

  • Article

Copies data from a D3D11_USAGE_DEFAULT texture which was mapped using ID3D11DeviceContext3::Map while providing a NULL D3D11_MAPPED_SUBRESOURCE parameter.

Syntax

void ReadFromSubresource(
  [out]          void            *pDstData,
  [in]           UINT            DstRowPitch,
  [in]           UINT            DstDepthPitch,
  [in]           ID3D11Resource  *pSrcResource,
  [in]           UINT            SrcSubresource,
  [in, optional] const D3D11_BOX *pSrcBox
);

Parameters

[out] pDstData

Type: void*

A pointer to the destination data in memory.

[in] DstRowPitch

Type: UINT

The size of one row of the destination data.

[in] DstDepthPitch

Type: UINT

The size of one depth slice of destination data.

[in] pSrcResource

Type: ID3D11Resource*

A pointer to the source resource (see ID3D11Resource).

[in] SrcSubresource

Type: UINT

A zero-based index, that identifies the destination subresource. For more details, see D3D11CalcSubresource.

[in, optional] pSrcBox

Type: const D3D11_BOX*

A pointer to a box that defines the portion of the destination subresource to copy the resource data from. If NULL, the data is read from the destination subresource with no offset. The dimensions of the destination must fit the destination (see D3D11_BOX).

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, this method doesn't perform any operation.

Return value

None

Remarks

The provided resource must be a D3D11_USAGE_DEFAULT texture which was mapped for writing by a previous call to ID3D11DeviceContext3::Map while providing a NULL D3D11_MAPPED_SUBRESOURCE parameter.

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 D3D 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 reading from 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.

Requirements

Requirement Value
Target Platform Windows
Header d3d11_3.h
Library D3D11.lib

See also

ID3D11Device3