DXGKDDI_PRESENT Rückruffunktion (d3dkmddi.h)

Artikel
05/26/2023

Die DxgkDdiPresent-Funktion kopiert Inhalte aus Quellzuordnungen auf eine primäre Oberfläche (und manchmal auch auf Systemspeicherzuordnungen außerhalb des Bildschirms).

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 hat dieses Handle 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-Grafikkernsubsystem das Handle durch den Kontext durch ein Handle für das Gerät. Die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers hat zuvor den Gerätehandle im hDevice-Element 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 die Vervollständigung erforderlich war.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Der aktuelle DMA-Puffer (Direct Memory Access) ist erschöpft.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Der Display-Miniporttreiber hat eine Bitblockübertragung (Bitblt) für die Farbkonvertierung erkannt, die das Gerät nicht ausführen konnte. Die Microsoft Direct3D-Runtime verhindert, dass die Anwendung fortgesetzt wird, und die Anwendung erhält einen Fehler beim Kopieren von Inhalten.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent hat nicht privilegierte Anweisungen erkannt (d. h. Anweisungen, die über die Berechtigungen des aktuellen CPU-Prozesses der zentralen Verarbeitungseinheit hinausgehen).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent hat Anweisungen erkannt, die Grafikhardware nicht unterstützen kann.
STATUS_INVALID_HANDLE	DxgkDdiPresent hat ein ungültiges Handle im Befehlspuffer erkannt.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Der Anzeigeminiporttreiber hat einen Fehler im DMA-Stream erkannt. Das Grafikkontextgerät befindet sich in einem verlorenen Zustand, wenn der Treiber diesen Fehlercode zurückgibt.

Hinweise

Das DirectX-Grafikkernsubsystem 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 Systemspeicherzuordnung außerhalb des Bildschirms kopieren.) Da eine primäre Oberfläche lose definiert ist, kann DxgkDdiPresent für die folgenden Szenarien implementiert werden:

Abhängig von der Position des Fensters muss die DxgkDdiPresent-Funktion für verschiedene Vorwahlen ausgeführt werden, die sich auf demselben Adapter oder auf verschiedenen Adaptern befinden können.
Der Primäre befindet sich auf einem Remotemonitor und wird über einen Terminaldiensteclient oder Microsoft NetMeeting zugegriffen.
Kürzlich ist ein Moduswechsel aufgetreten, und das primäre Format unterscheidet sich vom Quellformat, sodass eine Farbkonvertierung erforderlich ist. Darüber hinaus kann der DxgkDdiPresent-Vorgang aufgrund von Fensterausschnitten und -reihenfolgen abgeschnitten werden.

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

Der Anzeigeminiporttreiber muss die Besonderheiten der vorherigen Szenarien nicht kennen, solange der Treiber die folgenden Abstraktionen unterstützt:

Bei einem Kopiervorgang von einer Videospeicherquelle in ein primäres Video- oder Systemspeicherziel, eine Kopie von einer Off-Screen-Systemspeicherquelle zum primären Ziel, eine Kopie von und in die primäre Quelle oder eine Kopie von der primären Quelle in ein Off-Screen-Systemspeicherziel wird die Quelle vom hDeviceSpecificAllocation-Member des pAllocationList[DXGK_PRESENT_SOURCE_INDEX] Arrayelements der DXGKARG_PRESENT-Struktur angegeben, die pPresent der DxgkDdiPresent-Parameter zeigt auf. Das Ziel, bei dem es sich entweder um das aktuelle primäre Element des Geräts oder um eine Systemspeicherzuordnung außerhalb des Bildschirms handelt, wird vom hDeviceSpecificAllocation-Element des pAllocationList[DXGK_PRESENT_DESTINATION_INDEX]-Arrayelements von DXGKARG_PRESENT angegeben. Wenn das Ziel der Quelle (d. a. Zielquelle == ) entspricht, ist der Kopiervorgang eine Bitblockübertragung von Bildschirm zu Bildschirm (Bitblt). Daher legt das Grafiksubsystem die Quelle und das Ziel auf die folgenden Werte fest:
- destination != NULL (d. a. ziel == nonNULL)
- source != NULL (d. a. quelle == nonNULL)
In einem Videospeicher, der von der aktuellen Zuordnung in eine andere Zuordnung umdreht, 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 Ein No-Op-Flip kann aus derselben Quellzuordnung wie die aktuell gescannte Zuordnung durchgeführt werden. Ein No-Op-Flip wird verwendet, um eine Wartezeit in der Warteschlange auf ein vertikales Leerzeichen im Renderingstream einzufügen. Der Display-Miniporttreiber sollte einen Hardware-Flip-Befehl einfügen, als würde er in eine andere Zuordnung umgedreht.
Bei einem Farbfüllvorgang für die primäre Oberfläche ist keine Quellzuordnung erforderlich, und das Ziel ist ein primäres Zuordnungshandle, das vom hDeviceSpecificAllocation-Member des pAllocationList[DXGK_PRESENT_DESTINATION_INDEX]-Arrayelements von DXGKARG_PRESENT angegeben wird. Das Color-Element von DXGKARG_PRESENT befindet sich in der Regel im D3DDDIFMT_A8R8G8B8 Format des D3DDDIFORMAT Enumerationstyps. Wenn das primäre Format jedoch palettisiert RGB ist, enthält Color den Palettenindex. Daher legt das Grafiksubsystem die Quelle und das Ziel auf die folgenden Werte fest:
- destination != NULL (d. a. ziel == nonNULL)
- Source == NULL

Damit alle DxgkDdiPresent-Szenarien ordnungsgemäß funktionieren, sollte die DxgkDdiCreateDevice-Funktion des Anzeigeminiporttreibers festlegen, dass der DmaBufferSize-Member der DXGK_DEVICEINFO-Struktur groß genug ist, um die Hardwarebefehle zu halten, die erforderlich sind, um mindestens ein RECT-Rechteck für das Anzeige- oder Off-Bildschirmziel anzuzeigen. Die DxgkDdiPresent-Funktion des Treibers kann jedoch STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER zurückgeben, wenn die Anzahl von Unterrectangles im DxgkDdiPresent-Szenario den aktuellen DMA-Puffer erschöpft und der Treiber einen weiteren DMA-Puffer benötigt, um fortzufahren.

Das Grafiksubsystem ruft dann einen neuen DMA-Puffer ab und ruft die DxgkDdiPresent-Funktion des Treibers erneut mit der gleichen Liste von RECT-Strukturen auf wie der vorherige DxgkDdiPresent-Aufruf . Der Treiber muss das MultipassOffset-Element der DXGKARG_PRESENT-Struktur verwenden, auf die von pPresent verwiesen wird, um den Fortschritt aufzuzeichnen, der beim Abschließen der RECT-Liste im vorherigen Aufruf von DxgkDdiPresent gemacht wurde, damit der Treiber an der Stelle fortfahren kann, an der er mit dem neuen DMA-Puffer beendet wurde. Wenn die DxgkDdiPresent-Funktion des Treibers die Liste der RECT-Strukturen abschließt, gibt sie STATUS_SUCCESS zurück.

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 bekannten physischen Adressen für die Quelle und das Ziel) in der Zuordnungsliste bereit.

Wenn der Videospeicher-Manager diese Informationen bereitstellt, muss der Treiber den DMA-Puffer generieren, indem er bestimmt, dass diese physischen Adressen die endgültigen Adressen sind, die das DirectX-Grafikkernsubsystem bereitstellt. Das Grafiksubsystem ruft die DxgkDdiPatch-Funktion im DMA-Puffer möglicherweise nicht auf, um sie 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 nichtzero ist.

Hinweis Obwohl die DxgkDdiPresent-Funktion des Treibers den DMA-Puffer vor patchet, muss der Treiber dennoch 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-Grafikkernsubsystem die DxgkDdiPatch-Funktion auf, um den DMA-Puffer erneut zu patchen.

Wenn der Treiber die Rotation unterstützt (d. h. die Unterstützung für drehbare Modi im RotationSupport-Member der D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION-Struktur in einem Aufruf der DxgkDdiEnumVidPnCofuncModality-Funktion meldet), muss der Treiber in der Lage sein, gedrehte Bitblockübertragungen (Bitblt) von der Quelle zum Ziel durchzuführen. Wenn das Bitfeldflag Rotieren in der DXGK_PRESENTFLAGS-Struktur für das Flags-Element von DXGKARG_PRESENT angegeben wird, sollte der Treiber die Drehung so anwenden, als ob er von einer nicht gedrehten Oberfläche auf die endgültige Ausrichtung der aktuellen Quelle geht.

Die primäre Zuordnung einer Quelle wird in der DxgkDdiCommitVidPn-Funktion angegeben. Wenn mehrere Pfade von der angegebenen Quelle stammen (Klonmodus), muss der Anzeigeminiporttreiber sicherstellen, dass die Ausgaben im Pfadrotationsmodus für die verschiedenen Ziele ordnungsgemäß gedreht werden. Alle parameter, die für DxgkDdiPresent bereitgestellt werden, sind rotationagnostisch. Die Quell- und Zielrechtecke können beide der gesamte Bildschirm sein, wie es von Clients wahrgenommen wird (z. B. 768 x 1024).

Hinweis Diese Situation gilt nicht für Direct3D-Vollbildanwendungen im gedrehten Modus.

Wenn der Anzeige-Miniporttreiber zuvor in einem Aufruf seiner DxgkDdiQueryAdapterInfo-Funktion angegeben hat, dass er eine memory mapped I/O (MMIO)-basiertes Flip-Element unterstützt (durch Festlegen des FlipOnVSyncMmIo-Bitfeldflags im FlipCaps-Member der DXGK_DRIVERCAPS-Struktur auf TRUE), wird die DxgkDdiPresent-Funktion des Treibers anschließend aufgerufen, wobei der pDmaBuffer-Member von DXGKARG_PRESENT auf NULL festgelegt ist. da ein MMIO-basiertes Flip keinen DMA-Puffer erfordert, um auf der GPU ausgeführt werden zu können. Stattdessen muss die DxgkDdiPresent-Funktion des Treibers die Quelloberfläche überprüfen und die Fliphardware nach Bedarf programmieren. Das DirectX-Grafikkernsubsystem ruft die DxgkDdiSetVidPnSourceAddress-Funktion des Treibers auf, um diese Art von Flip auszuführen.

DxgkDdiPresent sollte seitenfähig gemacht werden.