Gets a pointer to the data contained in a subresource, and denies the GPU access to that subresource.
HRESULT Map( [in] ID3D11Resource *pResource, [in] UINT Subresource, [in] D3D11_MAP MapType, [in] UINT MapFlags, [out, optional] D3D11_MAPPED_SUBRESOURCE *pMappedResource );
- pResource [in]
A pointer to a ID3D11Resource interface.
- Subresource [in]
Index number of the subresource.
- MapType [in]
A D3D11_MAP-typed value that specifies the CPU's read and write permissions for a resource.
- MapFlags [in]
Flag that specifies what the CPU does when the GPU is busy. This flag is optional.
- pMappedResource [out, optional]
A pointer to the D3D11_MAPPED_SUBRESOURCE structure for the mapped subresource. See the Remarks section regarding NULL pointers.
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.
For info about how to use Map, see How to: Use dynamic resources.
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.
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.