D3DKMTPresent-Funktion (d3dkmthk.h)

Artikel
02/23/2024

Die D3DKMTPresent-Funktion übermittelt einen aktuellen Befehl an das Microsoft DirectX-Grafikkernsystem (Dxgkrnl.sys).

Syntax

NTSTATUS D3DKMTPresent(
  [in] D3DKMT_PRESENT *unnamedParam1
);

Parameter

[in] unnamedParam1

pData: Ein Zeiger auf eine D3DKMT_PRESENT-Struktur , die Parameter für die Darstellung beschreibt.

Rückgabewert

D3DKMTPresent gibt einen NTSTATUS-Wert zurück, z. B. einen der folgenden Werte:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Das Geschenk wurde erfolgreich ausgeführt.
STATUS_DEVICE_REMOVED	Die Grafikkarte wurde beendet, oder der Anzeigekontext wurde zurückgesetzt.
STATUS_INVALID_PARAMETER	Die Parameter wurden überprüft und als falsch ermittelt.
STATUS_NO_MEMORY	D3DKMTPresent konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden.
STATUS_GRAPHICS_ALLOCATION_INVALID	Der primäre Oberflächenziehpunkt wurde aufgrund einer Änderung des Anzeigemodus ungültig. Wenn der installierbare OpenGL-Clienttreiber (ICD) diesen Fehlercode empfängt, sollte er das primäre Handle erneut öffnen oder neu erstellen, alle Verweise im Befehlspuffer durch das alte Handle durch das neue Handle ersetzen und den Puffer dann erneut übermitteln.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Fehler im Rendergerätekontext, den der hContext-Member von D3DKMT_PRESENT angibt.

Hinweis

Der STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE Fehlercode gibt nicht an, dass ein Timeouterkennungs- und Wiederherstellungsprozess (Timeout Detection and Recovery, TDR) initiiert wurde oder dass die GPU nicht mehr reagiert. Beispielsweise versetzt das DirectX-Grafikkernsubsystem ein Gerät in einen Fehlerzustand, wenn der Anzeige-Miniporttreiber angibt, dass ein DMA-Puffer, der von diesem Gerät übermittelt wurde, einen Fehler verursacht hat, oder wenn der Videospeicher-Manager nicht alle Zuordnungen ausgelagert hat, die für einen DMA-Puffer erforderlich sind, auch nach dem Aufteilen des DMA-Puffers. Nachdem sich ein Gerät in einem Fehlerzustand befindet, kann es keine weiteren Vorgänge mehr ausführen und muss zerstört und neu erstellt werden. Der ICD kann die Funktion D3DKMTGetDeviceState aufrufen, um eine genauere Ursache für den Fehler zu ermitteln.

Hinweise

Die D3DKMTPresent-Funktion gibt möglicherweise STATUS_INVALID_PARAMETER zurück, abhängig von der Kombination von Parameterwerten (d. a. Werte in Membern der D3DKMT_PRESENT-Struktur , auf die pData verweist). In der folgenden Liste werden die häufigsten Kombinationen von Parameterwerten beschrieben, die dazu führen können, dass D3DKMTPresent STATUS_INVALID PARAMETER zurückgibt:

Der hDestination-Member ist ungleich NULL , und mindestens eine der folgenden Bedingungen ist true:
- Das pSrcSubRects-Element ist NULL.
- Das SubRectCnt-Element ist 0.
- Das Blt-Bitfeldflag des Flags-Elements ist nicht festgelegt.
- Das SrcRectValid-Bitfeldflag von Flags ist nicht festgelegt.
- Das ColorFill-Bitfeldflag von Flags ist festgelegt.
- Das Flip-, FlipDoNotFlip-, FlipDoNotWait- oder FlipRestart-Bitfeldflag von Flags ist festgelegt.
- Das SrcColorKey - oder DstColorKey-Bitfeldflag von Flags ist festgelegt.
- Das hSource-Element ist gleich hDestination.
- Quelle und Ziel sind keine primäre Oberfläche.
Das Flip-Bitfeldflag von Flags ist festgelegt, und mindestens eine der folgenden Bedingungen ist true:
- Das ColorFill-Bitfeldflag von Flags ist festgelegt.
- Das Blt-Bitfeldflag von Flags ist festgelegt.
- Das SrcColorKey - oder DstColorKey-Bitfeldflag von Flags ist festgelegt.
- Das SrcRectValid - oder DstRectValid-Bitfeldflag von Flags ist festgelegt.
- Das Flag "Bitfeld rotieren " von Flags ist festgelegt.
- Das RestrictVidPnSource-Bitfeldflag von Flags ist festgelegt.
- Die Quelle ist keine primäre Oberfläche.
- Der Anzeigeminiporttreiber unterstützt nicht das Flipintervall, das vom FlipInterval-Member angegeben wird.
- Die Funktion D3DKMTSetDisplayMode wurde zuvor nicht aufgerufen.
Das ColorFill-Bitfeldflag von Flags ist festgelegt, und eine der folgenden Bedingungen ist true:
- pSrcSubRects ist NULL.
- SubRectCnt ist 0.
- Das Blt-Bitfeldflag von Flags ist festgelegt.
- Das Flip-, FlipDoNotFlip-, FlipDoNotWait- oder FlipRestart-Bitfeldflag von Flags ist festgelegt.
- Das SrcColorKey - oder DstColorKey-Bitfeldflag von Flags ist festgelegt.
- Das SrcRectValid-Bitfeldflag von Flags ist festgelegt.
Das Blt-Bitfeldflag von Flags ist festgelegt, und eine der folgenden Bedingungen ist true:
- pSrcSubRects ist NULL.
- SubRectCnt ist 0.
- Das ColorFill-Bitfeldflag von Flags ist festgelegt.
- Das Flip-, FlipDoNotFlip-, FlipDoNotWait- oder FlipRestart-Bitfeldflag von Flags ist festgelegt.

Benutzermodus-Grafiktreiber, die D3DKMTPresent für blit style present aufrufen, wobei das Blt-Bitfeldflag von Flags festgelegt ist, müssen besonders darauf achten, dass alle zuvor an den kontext(n) angezeigten Kontext(n) übermittelten Arbeiten vollständig entleerbar sind. Andernfalls kann das Anwendungs-Deadlock selbst oder in einigen Fällen zu einem Deadlock des aktuellen Benutzerdesktops führen. Ein Kontext ist vollständig entleerbar, wenn er nur Wartevorgänge auf dem GPU-Synchronisierungsobjekt enthält, bei denen das entsprechende Signal bereits in die Warteschlange der GPU-Scheduler-Datenbank eingereiht wurde und das Signal selbst nicht hinter einer anderen unzurückbaren Wartezeit steht. Anders ausgedrückt: Wenn der Benutzerbereich aller Prozesse im System unmittelbar nach dem Aufruf von D3DKMTPresent angehalten wird, würde die Wartezeit erfüllt sein, sobald die abhängige Renderingkette, die bereits in die Warteschlange des GPU-Schedulers eingereiht wurde, das Rendering beendet würde. Ein Treiber darf niemals blit in einem Kontext aufrufen, der von einer GPU-Wartezeit abhängig ist, die derzeit nicht erfüllt ist und von einem späteren Vorgang aus diesem oder einem anderen Prozess erwartet wird.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie ein OpenGL ICD D3DKMTPresent verwenden kann, um Daten zu präsentieren.

HRESULT Present(D3DKMT_HANDLE hDevice, 
                HWND hWnd, 
                RECT* pSrcRect,
                 RECT* pDstRect)
{
    D3DKMT_PRESENT PresentData = {0};

    PresentData.hDevice = hDevice;
    PresentData.Flags.Blt = 
    PresentData.Flags.DstRectValid = 
    PresentData.Flags.SrcRectValid = TRUE;
    PresentData.hWindow = hWnd;
    PresentData.DstRect = *pDstRect;
    PresentData.SrcRect = *pSrcRect;
    PresentData.SubRectCnt = 1;  
    PresentData.pSrcSubRects = pSrcRect; 

    if (NT_SUCCESS((*pfnKTPresent)(&PresentData))) {
        return S_OK;
    }
    return E_FAIL;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
Header	d3dkmthk.h (include D3dkmthk.h)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll

Weitere Informationen

D3DKMTGetDeviceState

D3DKMTSetDisplayMode

D3DKMT_PRESENT