ID3D11DeviceContext::Map method (d3d11.h)

Article
10/13/2021

Gets a pointer to the data contained in a subresource, and denies the GPU access to that subresource.

Syntax

HRESULT Map(
  [in]            ID3D11Resource           *pResource,
  [in]            UINT                     Subresource,
  [in]            D3D11_MAP                MapType,
  [in]            UINT                     MapFlags,
  [out, optional] D3D11_MAPPED_SUBRESOURCE *pMappedResource
);

Parameters

[in] pResource

Type: ID3D11Resource*

A pointer to a ID3D11Resource interface.

[in] Subresource

Type: UINT

Index number of the subresource.

[in] MapType

Type: D3D11_MAP

A D3D11_MAP-typed value that specifies the CPU's read and write permissions for a resource.

[in] MapFlags

Type: UINT

Flag that specifies what the CPU does when the GPU is busy. This flag is optional.

[out, optional] pMappedResource

Type: D3D11_MAPPED_SUBRESOURCE*

A pointer to the D3D11_MAPPED_SUBRESOURCE structure for the mapped subresource. See the Remarks section regarding NULL pointers.

Return value

Type: HRESULT

This method returns one of the Direct3D 11 Return Codes.

This method also returns DXGI_ERROR_WAS_STILL_DRAWING if MapFlags specifies D3D11_MAP_FLAG_DO_NOT_WAIT and the GPU is not yet finished with the resource.

This method also returns DXGI_ERROR_DEVICE_REMOVED if MapType allows any CPU read access and the video card has been removed.

For more information about these error codes, see DXGI_ERROR.

Remarks

If you call Map on a deferred context, you can only pass D3D11_MAP_WRITE_DISCARD, D3D11_MAP_WRITE_NO_OVERWRITE, or both to the MapType parameter. Other D3D11_MAP-typed values are not supported for a deferred context.

Note The Direct3D 11.1 runtime, which is available starting with Windows 8, enables mapping dynamic constant buffers and shader resource views (SRVs) of dynamic buffers with D3D11_MAP_WRITE_NO_OVERWRITE. The Direct3D 11 and earlier runtimes limited mapping to vertex or index buffers. To determine if a Direct3D device supports these features, call ID3D11Device::CheckFeatureSupport with D3D11_FEATURE_D3D11_OPTIONS. CheckFeatureSupport fills members of a D3D11_FEATURE_DATA_D3D11_OPTIONS structure with the device's features. The relevant members here are MapNoOverwriteOnDynamicConstantBuffer and MapNoOverwriteOnDynamicBufferSRV.

For info about how to use Map, see How to: Use dynamic resources.

NULL pointers for pMappedResource

The pMappedResource parameter may be NULL when a texture is provided that was created with D3D11_USAGE_DEFAULT, and the API is called on an immediate context. This allows a default texture to be mapped, even if it was created using D3D11_TEXTURE_LAYOUT_UNDEFINED. Following this API call, the texture may be accessed using ID3D11DeviceContext3::WriteToSubresource and/or ID3D11DeviceContext3::ReadFromSubresource.

Don't read from a subresource mapped for writing

When you pass D3D11_MAP_WRITE, D3D11_MAP_WRITE_DISCARD, or D3D11_MAP_WRITE_NO_OVERWRITE to the MapType parameter, you must ensure that your app does not read the subresource data to which the pData member of D3D11_MAPPED_SUBRESOURCE points because doing so can cause a significant performance penalty. The memory region to which pData points can be allocated with PAGE_WRITECOMBINE, and your app must honor all restrictions that are associated with such memory.

Note

Even the following C++ code can read from memory and trigger the performance penalty because the code can expand to the following x86 assembly code.

C++ code:

*((int*)MappedResource.pData) = 0;

x86 assembly code:

AND DWORD PTR [EAX],0

Use the appropriate optimization settings and language constructs to help avoid this performance penalty. For example, you can avoid the xor optimization by using a volatile pointer or by optimizing for code speed instead of code size.

Windows Phone 8: This API is supported.

Requirements

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