Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

ID3D11DeviceContext::Map method

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

Syntax


HRESULT Map(
  ID3D11Resource *pResource,
  UINT Subresource,
  D3D11_MAP MapType,
  UINT MapFlags,
  D3D11_MAPPED_SUBRESOURCE *pMappedResource
);

Parameters

pResource

Type: ID3D11Resource*

A pointer to a ID3D11Resource interface.

Subresource

Type: UINT

Index number of the subresource.

MapType

Type: D3D11_MAP

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

MapFlags

Type: UINT

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

pMappedResource

Type: D3D11_MAPPED_SUBRESOURCE*

A pointer to the D3D11_MAPPED_SUBRESOURCE structure for the mapped subresource.

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.

Don't pass NULL pointers

If you pass NULL to the pResource or pMappedResource parameter, the behavior of Map is undefined. If you created a device that supports the debug layer, the debug output reports an error on this invalid Map call. Invalid parameters to Map cause undefined behavior and might cause the operating system to crash.

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

Header

D3D11.h

Library

D3D11.lib

 

 

Community Additions

Show:
© 2014 Microsoft