DXGKDDI_PRESENT Rückruffunktion (d3dkmddi.h)

Artikel
02/06/2025

Die DxgkDdiPresent--Funktion kopiert Inhalte aus Quellzuordnungen auf eine primäre Oberfläche (und manchmal auch auf Speicherzuweisungen aus dem Offscreen-System).

Syntax

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Parameter

[in] hContext

Ein Handle für den Gerätekontext für die Kopierinformationen. Die DxgkDdiCreateContext-Funktion des Anzeigeminiporttreibers zuvor im hContext-Element der DXGKARG_CREATECONTEXT Struktur zurückgegeben, auf die der pCreateContext Parameter von DxgkDdiCreateContext verweist.

Wenn der Treiber die Kontexterstellung nicht unterstützt, ersetzt das Microsoft DirectX-Grafik-Kernel-Subsystem das Handle in den Kontext durch ein Handle für das Gerät. Die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers hat zuvor den Gerätehandle im hDevice Member der DXGKARG_CREATEDEVICE Struktur zurückgegeben, auf die der pCreateDevice--Parameter von DxgkDdiCreateDevice verweist.

[in/out] pPresent

Ein Zeiger auf eine DXGKARG_PRESENT Struktur, die Informationen zum Kopiervorgang enthält.

Rückgabewert

DxgkDdiPresent gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	DxgkDdiPresent hat den Inhalt erfolgreich kopiert.
STATUS_NO_MEMORY oder STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Der aktuelle DMA-Puffer (Direct Memory Access) ist erschöpft.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Der Anzeige-Miniporttreiber hat eine Bitblockübertragung (Bitblt) für die Farbkonvertierung erkannt, die das Gerät nicht ausführen konnte. Die Microsoft Direct3D-Laufzeit verhindert, dass die Anwendung fortgesetzt wird, und die Anwendung empfängt einen Fehler beim Kopieren von Inhalten.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent hat nicht privilegierte Anweisungen erkannt (d. a. Anweisungen, die über die Berechtigungen des aktuellen zentralen Verarbeitungsgeräts [CPU]-Prozesses hinausgehen).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent hat Anweisungen erkannt, die grafikhardware nicht unterstützen kann.
STATUS_INVALID_HANDLE	DxgkDdiPresent hat einen ungültigen Handle im Befehlspuffer erkannt.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Der Anzeigeminiporttreiber hat einen Fehler im DMA-Datenstrom erkannt. Das Grafikkontextgerät wird in einen verlorenen Zustand versetzt, wenn der Treiber diesen Fehlercode zurückgibt.

Bemerkungen

Das DirectX-Grafik-Kernelsubsystem ruft die DxgkDdiPresent--Funktion des Anzeigeminiporttreibers auf, um Inhalte aus Quellzuordnungen in der Regel auf die primäre Oberfläche zu kopieren. (Diese Funktion kann auch Inhalte in eine Speicherzuweisung aus dem Offscreen-System kopieren.) Da eine primäre Oberfläche lose definiert ist, können DxgkDdiPresent- für die folgenden Szenarien implementiert werden:

Abhängig von der Position des Fensters muss die DxgkDdiPresent--Funktion über verschiedene Primarstellen hinweg ausgeführt werden, die sich auf demselben Adapter oder auf verschiedenen Adaptern befinden können.
Die Primäre befindet sich auf einem Remotemonitor und wird über einen Terminaldienste-Client oder Microsoft NetMeeting aufgerufen.
Ein Moduswechsel ist kürzlich aufgetreten, und das primäre Format unterscheidet sich vom Quellformat, sodass eine Farbkonvertierung erforderlich ist. Darüber hinaus kann der DxgkDdiPresent--Vorgang aufgrund des Fensterausschnitts und der Sortierung abgeschnitten werden.

Da sich die vorstehenden Szenarien asynchron ändern können, kann der Anzeigetreiber für den Benutzermodus keine Hardwareanweisungen für die DxgkDdiPresent--Funktion des Anzeige-Miniporttreibers im Voraus kompilieren. Der Miniporttreiber für die Anzeige muss Hardwarebefehle für den tatsächlichen DxgkDdiPresent--Vorgang erstellen, und er muss in einem DMA-Ausgabepuffer platziert werden. Nachdem die DxgkDdiPresent- Funktion des Anzeigeminiporttreibers aufgerufen wurde, um den DMA-Puffer zu generieren, garantiert das Betriebssystem, dass eine Szenarioänderung nicht eintritt, bevor dieser Puffer gerendert wird.

Der Miniporttreiber für die Anzeige ist nicht erforderlich, um die Besonderheiten der vorherigen Szenarien zu beachten, solange der Treiber die folgenden Abstraktionen unterstützt:

Bei einem Kopiervorgang von einer Videospeicherquelle in ein primäres Video- oder Systemspeicherziel wird eine Kopie von einer Offscreen-Systemspeicherquelle auf das primäre Ziel, eine Kopie von und zur primären Quelle oder eine Kopie von der primären Quelle auf ein Offscreen-Systemspeicherziel angegeben, die Quelle wird durch das hDeviceSpecificAllocation Mitglied des pAllocationList-[DXGK_PRESENT_SOURCE_INDEX] Arrayelements des DXGKARG_PRESENT Struktur, auf die der parameter pPresent von DxgkDdiPresent verweist. Das Ziel, das entweder die aktuelle Primäre des Geräts oder eine Speicherzuweisung auf dem Offscreen-System ist, wird durch das hDeviceSpecificAllocation Member des pAllocationList-[DXGK_PRESENT_DESTINATION_INDEX] Arrayelements von DXGKARG_PRESENT angegeben. Wenn das Ziel der Quelle entspricht (d. h. Ziel == Quelle), ist der Kopiervorgang eine Bitblockübertragung (Bitblt) auf dem Bildschirm. Daher legt das Grafiksubsystem die Quelle und das Ziel auf die folgenden Werte fest:
- destination != NULL- (d. b. Ziel == nichtNULL)
- source != NULL (d. a. quelle == nonNULL)
Wenn ein Videospeicher von der aktuellen Zuordnung zu einer anderen Zuordnung wechselt, kann die Quelle vom Betriebssystem angegeben und im hDeviceSpecificAllocation Member des pAllocationList-[DXGK_PRESENT_SOURCE_INDEX] Arrayelements von DXGKARG_PRESENT festgelegt werden. Das Grafiksubsystem legt die Quelle und das Ziel auf die folgenden Werte fest:
- destination == NULL
- source != NULL (d. a. quelle == nonNULL)
Hinweis Eine no-op Flip kann aus derselben Quellzuordnung wie die aktuell gescannte Zuordnung ausgeführt werden. Ein no-op Flip wird verwendet, um eine in die Warteschlange eingereihte Wartezeit auf ein vertikales Leerzeichen im Renderingdatenstrom einzufügen. Der Miniporttreiber für die Anzeige sollte einen Hardware-Flip-Befehl einfügen, als ob er in eine andere Zuordnung umgedreht wurde.
Bei einem Farbfüllvorgang an die primäre Oberfläche ist keine Quellzuordnung erforderlich, und das Ziel ist ein primärer Zuordnungshandle, der durch das hDeviceSpecificAllocation-element des pAllocationList-[DXGK_PRESENT_DESTINATION_INDEX] Arrayelements von DXGKARG_PRESENT angegeben wird. Das Color Member von DXGKARG_PRESENT befindet sich in der Regel im D3DDDIFMT_A8R8G8B8 Format aus dem D3DDDIFORMAT Enumerationstyp. Wenn das primäre Format jedoch RGB palettisiert ist, enthält Color den Palettenindex. Daher legt das Grafiksubsystem die Quelle und das Ziel auf die folgenden Werte fest:
- destination != NULL- (d. b. Ziel == nichtNULL)
- Quelle == NULL

Für alle DxgkDdiPresent- Szenarien, die ordnungsgemäß ausgeführt werden sollen, Die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers sollte die DmaBufferSize Member der DXGK_DEVICEINFO-Struktur so groß sein, dass die Hardwarebefehle, die benötigt werden, um mindestens ein RECT- Rechteck auf das Anzeige- oder Off-Screen-Ziel darzustellen. Die DxgkDdiPresent-Funktion des Treibers kann jedoch STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER zurückgeben, wenn die Anzahl der Untererkennungen im DxgkDdiPresent Szenario den aktuellen DMA-Puffer verringert, und der Treiber erfordert einen weiteren DMA-Puffer, um fortzufahren.

Das Grafiksubsystem ruft dann einen neuen DMA-Puffer ab und ruft die DxgkDdiPresent- Funktion des Treibers erneut mit der gleichen Liste der RECT-Strukturen auf, wie der vorherige DxgkDdiPresent Aufruf. Der Treiber muss das MultipassOffset Member der DXGKARG_PRESENT Struktur verwenden, auf das von pPresent-verwiesen wird, um den Fortschritt aufzuzeichnen, der beim Abschließen der RECT-Liste im vorherigen Aufruf von DxgkDdiPresent durchgeführt wurde, damit der Treiber mit dem neuen DMA-Puffer fortfahren kann. Wenn die DxgkDdiPresent Funktion des Treibers die Liste der RECT-Strukturen abgeschlossen hat, wird STATUS_SUCCESS zurückgegeben.

Zusätzlich zum Generieren eines DMA-Puffers muss der Anzeigeminiporttreiber eine Patchspeicherortliste generieren, die die verschiedenen Offsets innerhalb des DMA-Puffers angibt, die später gepatcht werden müssen, wenn physische Adressen für Zuordnungen bekannt sind. Manchmal stellt der Videospeicher-Manager dem Treiber vorab gepatchte Informationen (d. h. die letzten physischen Adressen für die Quelle und das Ziel) in der Zuordnungsliste zur Verfügung.

Wenn der Videospeicher-Manager diese Informationen bereitstellt, muss der Treiber den DMA-Puffer generieren, indem ermittelt wird, dass diese physischen Adressen die endgültigen Adressen sind, die vom DirectX-Grafik-Kernel-Subsystem bereitgestellt werden. Das Grafiksubsystem ruft möglicherweise nicht die DxgkDdiPatch--Funktion im DMA-Puffer auf, um es später erneut zu patchen. Daher muss der Treiber die Pre-Patch-Informationen verwenden, um den DMA-Puffer ordnungsgemäß zu generieren. Vorab gepatchte Informationen werden für Element N bereitgestellt, wenn das SegmentId-Element des Nth-Elements des pAllocationList- Arrays von DXGKARG_PRESENT ungleich Null ist.

Hinweis Obwohl der Treiber DxgkDdiPresent Funktion den DMA-Puffer vorpatcht, muss der Treiber weiterhin alle Verweise auf Zuordnungen in die Ausgabepatch-Location-Liste einfügen, die das pPatchLocationListOut Mitglied von DXGKARG_PRESENT angibt. Der Treiber muss diese Verweise einfügen, da sich die Adressen der Zuordnungen ändern können, bevor der DMA-Puffer an die GPU übermittelt wird. Daher ruft das DirectX-Grafik-Kernelsubsystem die DxgkDdiPatch--Funktion auf, um den DMA-Puffer neu zu beheben.

Wenn der Treiber die Drehung unterstützt (d. h. meldet die Unterstützung für gedrehte Modi im RotationSupport Member der D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION Struktur in einem Aufruf der DxgkDdiEnumVidPnCofuncModality-Funktion), muss der Treiber in der Lage sein, gedrehte Bitblockübertragungen (Bitblt) von Quelle zu Ziel auszuführen. Wenn das Bitfeldflagge Bitfeld-Kennzeichnung in der DXGK_PRESENTFLAGS Struktur für das Flags-Element Element von DXGKARG_PRESENTangegeben wird, sollte der Treiber die Drehung so anwenden, als ob er von einer nicht gedrehten Oberfläche zur endgültigen Ausrichtung der aktuellen Quelle wechselt.

Die primäre Zuordnung einer Quelle wird in der DxgkDdiCommitVidPn--Funktion angegeben. Wenn mehrere Pfade aus der angegebenen Quelle (Klonmodus) stammen, muss der Anzeigeminiporttreiber sicherstellen, dass die Ausgaben entsprechend dem Pfaddrehungsmodus für die verschiedenen Ziele korrekt gedreht werden. Alle Parameter, die an DxgkDdiPresent bereitgestellt werden, sind drehagnostisch. Die Quell- und Zielrechtecke können beide der gesamte Bildschirm sein, da Clients sie wahrnehmen (z. B. 768 x 1024).

Hinweis In dieser Situation werden direct3D-Anwendungen im gedrehten Modus nicht im Vollbildmodus behandelt.

Wenn der zuvor angegebene Anzeigeminiporttreiber in einem Aufruf der DxgkDdiQueryAdapterInfo-Funktion angezeigt wird, dass es eine speicherzuordnunge E/A (MMIO)-basierte Flip unterstützt (durch Festlegen des FlipOnVSyncMmIo Bitfeld-Flag im FlipCaps Member der DXGK_DRIVERCAPS Struktur auf TRUE), wird die DxgkDdiPresent--Funktion des Treibers anschließend mit dem pDmaBuffer Member der DXGKARG_PRESENT auf NULL-, da für einen MMIO-basierten Flip kein DMA-Puffer für die GPU erforderlich ist. Stattdessen muss die DxgkDdiPresent--Funktion des Treibers die Quelloberfläche überprüfen und die Hardware nach Bedarf programmieren. Das DirectX-Grafik-Kernelsubsystem ruft die DxgkDdiSetVidPnSourceAddress-Funktion auf, um diese Art von Flip auszuführen.

DxgkDdiPresent- sollte seitenfähig gemacht werden.