IDXGIOutputDuplication::AcquireNextFrame-Methode (dxgi1_2.h)

Gibt an, dass die Anwendung bereit ist, das nächste Desktopimage zu verarbeiten.

Syntax

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

Parameter

[in] TimeoutInMilliseconds

Das Timeoutintervall in Millisekunden. Dieses Intervall gibt die Zeit an, die diese Methode auf einen neuen Frame wartet, bevor sie an den Aufrufer zurückgegeben wird. Diese Methode gibt zurück, wenn das Intervall abgelaufen ist und kein neues Desktopimage verfügbar ist.

Weitere Informationen zum Timeoutintervall finden Sie unter Hinweise.

[out] pFrameInfo

Ein Zeiger auf einen Speicherort, der die DXGI_OUTDUPL_FRAME_INFO-Struktur empfängt, die Timing- und Präsentationsstatistiken für einen Frame beschreibt.

[out] ppDesktopResource

Ein Zeiger auf eine Variable, die die IDXGIResource-Schnittstelle der Oberfläche empfängt, die die Desktop-Bitmap enthält.

Rückgabewert

AcquireNextFrame gibt Folgendes zurück:

• S_OK, wenn das nächste Desktopimage erfolgreich empfangen wurde.
• DXGI_ERROR_ACCESS_LOST, wenn die Desktopduplizierungsschnittstelle ungültig ist. Die Desktopduplizierungsschnittstelle wird in der Regel ungültig, wenn ein anderer Bildtyp auf dem Desktop angezeigt wird. Beispiele für diese Situation sind:
  • Desktopswitch
  • Modusänderung
  • Wechseln von DWM ein, DWM aus oder einer anderen Vollbildanwendung
  In diesem Fall muss die Anwendung die IDXGIOutputDuplication-Schnittstelle freigeben und eine neue IDXGIOutputDuplication für den neuen Inhalt erstellen.
• DXGI_ERROR_WAIT_TIMEOUT, ob das Timeoutintervall abgelaufen ist, bevor der nächste Desktopframe verfügbar war.
• DXGI_ERROR_INVALID_CALL, wenn die Anwendung AcquireNextFrame aufgerufen hat, ohne den vorherigen Frame freizugeben.
• E_INVALIDARG, wenn einer der Parameter für AcquireNextFrame falsch ist; beispiel: pFrameInfo ist NULL.
• Möglicherweise weitere Fehlercodes, die im Thema DXGI_ERROR beschrieben werden.

Hinweise

Wenn AcquireNextFrame erfolgreich zurückgegeben wird, kann die aufrufende Anwendung auf das Desktopimage zugreifen, das AcquireNextFrame in der Variablen unter ppDesktopResource zurückgibt. Wenn der Aufrufer im TimeoutInMilliseconds-Parameter ein Timeoutintervall von null angibt, überprüft AcquireNextFrame , ob ein neues Desktopimage verfügbar ist, gibt sofort zurück und gibt dessen Ergebnis mit dem Rückgabewert an. Wenn der Aufrufer ein INFINITE-Timeoutintervall im TimeoutInMilliseconds-Parameter angibt, vergeht das Timeoutintervall nie.

Hinweis Sie können die Wartezeit, die Sie im Parameter TimeoutInMilliseconds angegeben haben, nicht abbrechen. Wenn Sie daher in regelmäßigen Abständen nach anderen Bedingungen suchen müssen (z. B. ein Beendigungssignal), sollten Sie ein nicht unendliches Timeoutintervall angeben. Nach Ablauf des Timeoutintervalls können Sie nach diesen anderen Bedingungen suchen und dann AcquireNextFrame erneut aufrufen, um auf den nächsten Frame zu warten.

 

AcquireNextFrame ruft einen neuen Desktopframe ab, wenn das Betriebssystem entweder das Desktop-Bitmapbild aktualisiert oder die Form oder Position eines Hardwarezeigers ändert. Für den neuen Frame, den AcquireNextFrame abruft, wird möglicherweise nur das Desktopbild aktualisiert, nur die Zeigerform oder -position aktualisiert oder beides.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	dxgi1_2.h
Bibliothek	Dxgi.lib

Weitere Informationen

IDXGIOutputDuplication