IDXGIOutputDuplication::AcquireNextFrame method

Indicates that the application is ready to process the next desktop image.


HRESULT AcquireNextFrame(
  UINT                    TimeoutInMilliseconds,
  IDXGIResource           **ppDesktopResource



The time-out interval, in milliseconds. This interval specifies the amount of time that this method waits for a new frame before it returns to the caller. This method returns if the interval elapses, and a new desktop image is not available.

For more information about the time-out interval, see Remarks.


A pointer to a memory location that receives the DXGI_OUTDUPL_FRAME_INFO structure that describes timing and presentation statistics for a frame.


A pointer to a variable that receives the IDXGIResource interface of the surface that contains the desktop bitmap.

Return Value

AcquireNextFrame returns:

  • S_OK if it successfully received the next desktop image.
  • 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_WAIT_TIMEOUT if the time-out interval elapsed before the next desktop frame was available.
  • DXGI_ERROR_INVALID_CALL if the application called AcquireNextFrame without releasing the previous frame.
  • E_INVALIDARG if one of the parameters to AcquireNextFrame is incorrect; for example, if pFrameInfo is NULL.
  • Possibly other error codes that are described in the DXGI_ERROR topic.


When AcquireNextFrame returns successfully, the calling application can access the desktop image that AcquireNextFrame returns in the variable at ppDesktopResource. If the caller specifies a zero time-out interval in the TimeoutInMilliseconds parameter, AcquireNextFrame verifies whether there is a new desktop image available, returns immediately, and indicates its outcome with the return value. If the caller specifies an INFINITE time-out interval in the TimeoutInMilliseconds parameter, the time-out interval never elapses.

Note  You cannot cancel the wait that you specified in the TimeoutInMilliseconds parameter. Therefore, if you must periodically check for other conditions (for example, a terminate signal), you should specify a non-INFINITE time-out interval. After the time-out interval elapses, you can check for these other conditions and then call AcquireNextFrame again to wait for the next frame.
AcquireNextFrame acquires a new desktop frame when the operating system either updates the desktop bitmap image or changes the shape or position of a hardware pointer. The new frame that AcquireNextFrame acquires might have only the desktop image updated, only the pointer shape or position updated, or both.


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