Edit

Share via

ID3D11Device3::WriteToSubresource method (d3d11_3.h)

  • Article

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

Syntax

void WriteToSubresource(
  [in]           ID3D11Resource  *pDstResource,
  [in]           UINT            DstSubresource,
  [in, optional] const D3D11_BOX *pDstBox,
  [in]           const void      *pSrcData,
  [in]           UINT            SrcRowPitch,
  [in]           UINT            SrcDepthPitch
);

Parameters

[in] pDstResource

Type: ID3D11Resource*

A pointer to the destination resource (an ID3D11Resource).

[in] DstSubresource

Type: UINT

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

[in, optional] pDstBox

Type: const D3D11_BOX*

A pointer to a box that defines the portion of the destination subresource to copy the resource data into. If NULL, the data is written to the destination subresource with no offset. The dimensions of the source 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.

[in] pSrcData

Type: const void*

A pointer to the source data in memory.

[in] SrcRowPitch

Type: UINT

The size of one row of the source data.

[in] SrcDepthPitch

Type: UINT

The size of one depth slice of source data.

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

Requirements

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

See also

ID3D11Device3