Edit

Share via

IDXGIOutputDuplication::AcquireNextFrame method (dxgi1_2.h)

  • Article

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

Syntax

HRESULT AcquireNextFrame(
  [in]  UINT                    TimeoutInMilliseconds,
  [out] DXGI_OUTDUPL_FRAME_INFO *pFrameInfo,
  [out] IDXGIResource           **ppDesktopResource
);

Parameters

[in] TimeoutInMilliseconds

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.

[out] pFrameInfo

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

[out] ppDesktopResource

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.

Remarks

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.

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