IDXGIOutputDuplication::MapDesktopSurface method

Provides the CPU with efficient access to a desktop image if that desktop image is already in system memory.

Syntax

HRESULT MapDesktopSurface(
  [out] DXGI_MAPPED_RECT *pLockedRect
);

Parameters

pLockedRect [out]

A pointer to a DXGI_MAPPED_RECT structure that receives the surface data that the CPU needs to directly access the surface data.

Return value

MapDesktopSurface returns:

• S_OK if it successfully retrieved the surface data.
• DXGI_ERROR_ACCESS_LOST if the desktop duplication interface is invalid. The desktop duplication interface typically becomes invalid when a different type of image is displayed on the desktop. Examples of this situation are:
  • Desktop switch
  • Mode change
  • Switch from DWM on, DWM off, or other full-screen application
  In this situation, the application must release the IDXGIOutputDuplication interface and create a new IDXGIOutputDuplication for the new content.
• DXGI_ERROR_INVALID_CALL if the application already has an outstanding map on the desktop image. The application must call UnMapDesktopSurface before it calls MapDesktopSurface again. DXGI_ERROR_INVALID_CALL is also returned if the application did not own the desktop image when it called MapDesktopSurface.
• DXGI_ERROR_UNSUPPORTED if the desktop image is not in system memory. In this situation, the application must first transfer the image to a staging surface and then lock the image by calling the IDXGISurface::Map method.
• E_INVALIDARG if the pLockedRect parameter is incorrect; for example, if pLockedRect is NULL.
• Possibly other error codes that are described in the DXGI_ERROR topic.

Remarks

You can successfully call MapDesktopSurface if the DesktopImageInSystemMemory member of the DXGI_OUTDUPL_DESC structure is set to TRUE. If DesktopImageInSystemMemory is FALSE, MapDesktopSurface returns DXGI_ERROR_UNSUPPORTED. Call IDXGIOutputDuplication::GetDesc to retrieve the DXGI_OUTDUPL_DESC structure.

Requirements

See also

IDXGIOutputDuplication