Edit

Share via

IDXGIOutputDuplication::MapDesktopSurface method (dxgi1_2.h)

  • Article

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

[out] pLockedRect

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

Requirement Value
Minimum supported client Windows 8 [desktop apps only]
Minimum supported server Windows Server 2012 [desktop apps only]
Target Platform Windows
Header dxgi1_2.h
Library Dxgi.lib

See also

IDXGIOutputDuplication