D3DKMTPresent-Funktion (d3dkmthk.h)

Artikel
02/06/2025

Die D3DKMTPresent-Funktion sendet einen vorhandenen Befehl an das Microsoft DirectX-Grafikkernsubsystem (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	Die Präsentation wurde erfolgreich ausgeführt.
STATUS_DEVICE_REMOVED	Der Grafikadapter wurde beendet, oder der Anzeigekontext wurde zurückgesetzt.
STATUS_INVALID_PARAMETER	Parameter wurden überprüft und ermittelt, dass sie falsch sind.
STATUS_NO_MEMORY	D3DKMTPresent konnte aufgrund 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 erneut erstellen, alle Verweise im Befehlspuffer durch das alte Handle durch das neue Handle ersetzen und dann den Puffer erneut übermitteln.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Fehler im Rendergerätekontext, den der hContext Element von D3DKMT_PRESENT angibt.

Anmerkung

Der STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE Fehlercode weist nicht auf die Initiierung eines TDR-Prozesses (Timeout Detection and Recovery) hin, oder die GPU reagiert nicht mehr. Beispielsweise versetzt das DirectX-Grafik-Kernel-Subsystem 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 Für einen DMA-Puffer erforderlichen Zuordnungen selbst nach dem Aufteilen des DMA-Puffers aufblättern konnte. Nachdem sich ein Gerät in einem Fehlerzustand befindet, kann es keine weiteren Vorgänge ausführen und muss zerstört und neu erstellt werden. Die ICD kann die D3DKMTGetDeviceState Funktion aufrufen, um einen genaueren Grund für den Fehler zu ermitteln.

Bemerkungen

Die funktion D3DKMTPresent kann abhängig von der Kombination von Parameterwerten (d. h. Werte in Membern der D3DKMT_PRESENT Struktur, auf die pData- verweist) STATUS_INVALID_PARAMETER zurückgeben. In der folgenden Liste werden die am häufigsten verwendeten Kombinationen von Parameterwerten beschrieben, die dazu führen können, dass D3DKMTPresent- STATUS_INVALID PARAMETER zurückgeben:

Das hDestination- Mitglied ist nichtNULL-, und mindestens eine der folgenden Bedingungen gilt:
- Das pSrcSubRects Member ist NULL-.
- Der SubRectCnt Member ist 0.
- Das Blt- Bitfeld-Flag des Flags Members ist nicht festgelegt.
- Das SrcRectValid- Bitfeld-Flag von Flags ist nicht festgelegt.
- Das Bitfeld-Flag Flags festgelegt ist.
- Die Flip, FlipDoNotFlip, FlipDoNotWaitoder FlipRestart Bitfeld-Flag von Flags festgelegt ist.
- Die SrcColorKey- oder DstColorKey- Bitfeldkennzeichnung Flags festgelegt ist.
- Das hSource-element ist gleich hDestination.
- Die Quelle und das Ziel sind keine primäre Oberfläche.
Das Flip- Bitfeldflagge von Flags festgelegt ist und mindestens eine der folgenden Bedingungen zutrifft:
- Das Bitfeld-Flag Flags festgelegt ist.
- Das Blt- Bitfeld-Flag von Flags festgelegt ist.
- Die SrcColorKey- oder DstColorKey- Bitfeldkennzeichnung Flags festgelegt ist.
- Die SrcRectValid oder DstRectValid Bitfeldflagge von Flags festgelegt ist.
- Das Bitfeldflagge Flags festgelegt ist.
- Das RestrictVidPnSource- Bitfeld-Flag von Flags festgelegt ist.
- Die Quelle ist keine primäre Oberfläche.
- Der Anzeigeminiporttreiber unterstützt nicht das Flip-Intervall, das vom FlipInterval Member angegeben wird.
- Die funktion D3DKMTSetDisplayMode wurde zuvor nicht aufgerufen.
Das ColorFill- Bitfeld-Flag von Flags festgelegt ist und eine der folgenden Bedingungen zutrifft:
- pSrcSubRects ist NULL.
- SubRectCnt- ist 0.
- Das Blt- Bitfeld-Flag von Flags festgelegt ist.
- Die Flip, FlipDoNotFlip, FlipDoNotWaitoder FlipRestart Bitfeld-Flag von Flags festgelegt ist.
- Die SrcColorKey- oder DstColorKey- Bitfeldkennzeichnung Flags festgelegt ist.
- Die SrcRectValid Bitfeld-Flag von Flags festgelegt ist.
Das Blt- Bitfeld-Flag von Flags festgelegt ist und eine der folgenden Bedingungen zutrifft:
- pSrcSubRects ist NULL.
- SubRectCnt- ist 0.
- Das Bitfeld-Flag Flags festgelegt ist.
- Die Flip, FlipDoNotFlip, FlipDoNotWaitoder FlipRestart Bitfeld-Flag von Flags festgelegt ist.

Grafiktreiber für den Benutzermodus, die D3DKMTPresent- für blit-Formatvorlage aufrufen, müssen mit der Blt- Bitfeldkennzeichnung von Flags festgelegt werden, besondere Sorgfalt erfordern, um sicherzustellen, dass alle zuvor übermittelten Arbeiten an den kontext(n) vollständig entwässerbar sind. Andernfalls kann die Anwendung das Deadlocking selbst oder in einigen Fällen das Deadlocking des aktuellen Benutzerdesktops bewirken. Ein Kontext ist vollständig entwässerbar, wenn er nur Wartezeiten für das GPU-Synchronisierungsobjekt enthält, in dem das entsprechende Signal bereits in die GPU-Planerdatenbank in die Warteschlange eingereiht wurde und wo sich das Signal selbst nicht hinter einem anderen unrainierbaren Warten befindet. Anders ausgedrückt: Wenn der Benutzerbereich aller Prozesse im System unmittelbar nach dem Aufruf von D3DKMTPresent-angehalten wurde, würde die Wartezeit erfüllt werden, nachdem die abhängige Renderingkette, die bereits in die Warteschlange des GPU-Schedulers eingereiht wurde, das Rendering abgeschlossen hat. Ein Treiber darf niemals blit aufrufen, der in einem Kontext vorhanden ist, der von einer GPU-Wartezeit abhängig ist, die derzeit nicht erfüllt ist und von einem späteren Vorgang, der aus diesem oder einem anderen Prozess stammt, erfüllt wird.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie ein OpenGL ICD D3DKMTPresent- zum Darstellen von Daten verwenden kann.

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
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Header-	d3dkmthk.h (einschließlich D3dkmthk.h)
Library	Gdi32.lib
DLL-	Gdi32.dll

Siehe auch

D3DKMTGetDeviceState

D3DKMTSetDisplayMode

D3DKMT_PRESENT

Freigeben über