Gets a pointer to the data contained in a subresource, and denies the GPU access to that subresource.
HRESULT Map( ID3D11Resource *pResource, UINT Subresource, D3D11_MAP MapType, UINT MapFlags, D3D11_MAPPED_SUBRESOURCE *pMappedResource );
A pointer to a ID3D11Resource interface.
Index number of the subresource.
A D3D11_MAP-typed value that specifies the CPU's read and write permissions for a resource.
Flag that specifies what the CPU does when the GPU is busy. This flag is optional.
A pointer to the D3D11_MAPPED_SUBRESOURCE structure for the mapped subresource.
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.
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.
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.
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.
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.
*((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.