DXGI_DDI_BASE_FUNCTIONS-Struktur (dxgiddi.h)

Artikel
03/01/2024

Die DXGI_DDI_BASE_FUNCTIONS-Struktur enthält Funktionen, die der Benutzermodusanzeigetreiber implementieren kann, um Aufgaben auf niedriger Ebene auszuführen, z. B. das Darstellen gerenderter Frames in einer Ausgabe, das Steuern von Gamma und das Verwalten eines Vollbildübergangs.

Syntax

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

Member

pfnPresent

Zeiger auf die PresentDXGI-Funktion , die den Benutzermodusanzeigetreiber benachrichtigt, dass eine Anwendung das Rendering abgeschlossen hat, und fordert die Anzeige des Treibers auf die Zieloberfläche an.

Das hDevice-Element der DXGI_DDI_ARG_PRESENT-Struktur , auf die der pPresentData-Parameter verweist, ist das gleiche Handle, das die CreateDevice(D3D10) -Funktion des Treibers an die Runtime im hDrvDevice-Member der D3D10DDIARG_CREATEDEVICE-Struktur übergeben hat. Daher müssen Treiberschreiber den Typ dieses Handles sorgfältig definieren. Darüber hinaus können Treiber verschiedene Implementierungen der PresentDXGI-Funktion bereitstellen, basierend auf der die DDI-Implementierung den Aufruf von CreateDevice(D3D10) verarbeitet hat. Die Runtime kombiniert nie Treiberhandles über DDI-Implementierungen hinweg. In ähnlicher Weise sind die hSurfaceToPresent - und hDstResource-Member von DXGI_DDI_ARG_PRESENT auch treiberdefinierte Ressourcenhandles, die der Treiber in früheren Aufrufen der CreateResource(D3D10) -Funktion des Treibers an die Runtime zurückgegeben hat.

Das pDXGIContext-Element von DXGI_DDI_ARG_PRESENT ist ein undurchsichtiger Kommunikationsmechanismus. Die Runtime übergibt diesen DXGI-Kontext an den Treiber. Der Treiber sollte diesen DXGI-Kontext unverändert in das pDXGIContext-Element der DXGIDDICB_PRESENT-Struktur kopieren, wenn der Treiber die Funktion pfnPresentCbDXGI aufruft.

Der Treiber muss alle teilweise erstellten Renderdaten (Befehlspuffer) mithilfe der PfnRenderCb-Funktion übermitteln. Danach muss der Treiber die Ressourcenhandleparameter in Kernelhandles übersetzen und diese Kernelhandles in einem Aufruf von pfnPresentCbDXGI verwenden.

Hinweis

Wenn die PresentDXGI-Funktion des Treibers sRGB-formatierten Inhalt von einer Quelloberfläche auf eine Nicht-sRGB-Zieloberfläche kopiert, sollte der Treiber den sRGB-Inhalt unverändert kopieren (das heißt, der Treiber sollte keine sRGB-in-lineare Konvertierung durchführen).

pPresentData

[in] Ein Zeiger auf eine DXGI_DDI_ARG_PRESENT Struktur, die beschreibt, wie auf der Zieloberfläche angezeigt wird.

pfnGetGammaCaps

Die GetGammaCapsDXGI-Funktion ruft Gammafunktionen ab.

pGammaData

[in] Ein Zeiger auf eine DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS Struktur, die Gammafunktionen enthält.

pfnSetDisplayMode

Ein Zeiger auf die SetDisplayModeDXGI-Funktion des Treibers.

pfnSetResourcePriority

Die SetResourcePriorityDXGI-Funktion legt die eviction-from-memory-Priorität für eine Ressource fest.

Die Microsoft Direct3D-Runtime ruft SetResourcePriorityDXGI auf, um die Prioritätsebene für eine Ressource festzulegen. Der Benutzermodusanzeigetreiber sollte das Ressourcenhandle, das im hResource-Member der DXGI_DDI_ARG_SETRESOURCEPRIORITY-Struktur bereitgestellt wird, auf die von pPriorityData verwiesen wird, in ein Zuordnungshandle übersetzen. Nachdem der Treiber diese Übersetzung durchgeführt hat, sollte der Treiber das resultierende Handle in einem Aufruf der Funktion pfnSetPriorityCb übergeben.

pPriorityData

[in] Ein Zeiger auf eine DXGI_DDI_ARG_SETRESOURCEPRIORITY Struktur, die die Prioritätsebene beschreibt, auf die eine Ressource festgelegt werden soll.

pfnQueryResourceResidency

Diese Funktion bestimmt den Wohnsitz der angegebenen Ressourcenliste.

Die Microsoft Direct3D-Runtime ruft die QueryResourceResidencyDXGI-Funktion des Benutzermodustreibers für Anwendungen auf, um zu ermitteln, ob das Betriebssystem zur Ziehungszeit einen erheblichen Stillstand verursacht, wenn das System Ressourcen gpu-zugänglich machen muss. Die von QueryResourceResidencyDXGI zurückgegebenen Informationen sind eine Annäherung an die Residenz von Ressourcen, da die Ressourcen möglicherweise herabgestuft werden, bevor Anwendungen die Ressourcen verwenden.

QueryResourceResidencyDXGI muss die PfnQueryResidencyCb-Funktion aufrufen. pfnQueryResidencyCb gibt die Residency-status einer Ressource in den Elementen des Arrays zurück, das vom pResidencyStatus-Member der D3DDDICB_QUERYRESIDENCY-Struktur angegeben wird. Wenn pfnQueryResidencyCb für eine Abfrage D3DDDI_RESIDENCYSTATUS_NOTRESIDENT zurückgibt, muss QueryResourceResidencyDXGI S_NOT_RESIDENT zurückgeben. Wenn pfnQueryResidencyCb für eine Abfrage D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY und keine D3DDDI_RESIDENCYSTATUS_NOTRESIDENT für eine Abfrage zurückgibt, muss QueryResourceResidencyDXGI S_RESIDENT_IN_SHARED_MEMORY zurückgeben. QueryResourceResidencyDXGI muss nur S_OK zurückgeben, wenn alle Aufrufe von pfnQueryResidencyCb für alle Abfragen D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY zurückgeben.

Für jede Ressource, die von der Runtime über einen Aufruf von QueryResourceResidencyDXGI abgefragt wird, muss der Benutzermodusanzeigetreiber bestimmen, welche Zuordnungen, die zur Ressource gehören, über einen Aufruf von pfnQueryResidencyCb abgefragt werden sollen. Bei einer Ressource, die eine einzelne Zuordnung besitzt, ist die Ermittlung einfach. Der Treiber fragt diese Zuordnung ab. Wenn eine Ressource jedoch mehrere Zuordnungen besitzt, ist die Ermittlung schwieriger. Der Treiber muss bestimmen, welche Zuordnungen eine Anwendung wahrscheinlich zum Rendern verwendet, und der Treiber muss nur diese Zuordnungen abfragen. Wenn eine Ressource beispielsweise eine Zuordnung besitzt, die zum Rendern verwendet wird, und eine Scratch-Zuordnung, die einen Sperrvorgang verarbeitet, sollte der Treiber nur den Wohnsitz der ersten Zuordnung abfragen, da eine Anwendung höchstwahrscheinlich die zweite Zuordnung nicht zum Rendern verwendet.

Hinweis

Da die Runtime keine Residenzabfragen von Systemspeicherressourcen unterstützt, schlägt die Runtime immer Anforderungen von Anwendungen für die Residency-status von Systemspeicherressourcen fehl und ruft nie die QueryResourceResidencyDXGI-Funktion des Benutzermodusanzeigetreibers für diese Systemspeicherressourcen auf.

pResidencyData

[in] Ein Zeiger auf eine DXGI_DDI_ARG_QUERYRESOURCERESIDENCY-Struktur , die eine Liste der Ressourcen beschreibt, für die der Wohnsitz überprüft wird.

pfnRotateResourceIdentities

Rotiert eine Liste von Ressourcen.

Die RotateResourceIdentitiesDXGI-Funktion muss Identitäten des Arrays von Ressourcen austauschen, die im pResources-Member der DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES Struktur übergeben werden, auf die der pRotateData-Parameter verweist. Wenn sich das Ressourcenarray beispielsweise auf die Ressourcen X, Y und Z bezieht, muss RotateResourceIdentitiesDXGI diese Handles in erhöhter Arrayindexreihenfolge rotieren, um auf Y, Z und X zu verweisen. Insbesondere sollte der Benutzermodusanzeigetreiber die Kernelhandles der entsprechenden Ressourcen austauschen. Der Treiber sollte jedoch die entsprechenden Runtime-Handles (RT) nicht austauschen. Die Runtime ruft RotateResourceIdentitiesDXGI auf, um Puffer während der Präsentation zurück zu rotieren. Daher ist ein Aufruf von RotateResourceIdentitiesDXGI selten. Die Runtime kann das D3D10_DDI_BIND_PRESENT-Flag im BindFlags-Member der D3D10DDIARG_CREATERESOURCE-Struktur angeben, wenn die Runtime die CreateResource(D3D10) -Funktion des Treibers aufruft, um anzugeben, dass die Ressource an einem Drehvorgang teilnehmen kann.

Der Benutzermodusanzeigetreiber muss auch andere Aspekte des Identitätsaustauschs verarbeiten. In Direct3D Version 10 können Sichten beispielsweise auf Ressourcen verweisen. und in solchen Ansichten können Ressourcenadressen eingebettet sein. Daher muss der Treiber solche Ansichten erneut erstellen. Außerdem muss der Treiber möglicherweise die aktuell gebundenen Ansichten erneut anwenden.

Ab Windows 8 muss der Treiber die Rotation von Stereobackpuffern unterstützen.

pRotateData

[in] Ein Zeiger auf eine DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES Struktur, die eine Liste der zu rotierenden Ressourcen beschreibt.

pfnBlt

Kopiert den Inhalt einer Quelloberfläche auf eine Zieloberfläche und kann den Inhalt rotieren.

Die Direct3D-Runtime kann das Flags-Element der DXGI_DDI_ARG_BLT-Struktur festlegen, auf die der pBltData-Parameter verweist, sodass die BltDXGI-Funktion einen Bitblockübertragungsvorgang (Bitblockübertragung, Bitblt) ausführen muss, der Ressourcen mit mehreren Stichproben auflöst, eine Farbformatkonvertierung durchführt und eine Dehnung oder Verkleinerung auf einmal ausführt. Die Direct3D-Runtime legt den Flags-Member von DXGI_DDI_ARG_BLT jedoch nie auf 0 (d. h. keine Flags festgelegt) zusammen mit dem DXGI_DDI_MODE_ROTATION_IDENTITY Wert fest, der im Rotieren-Member von DXGI_DDI_ARG_BLT festgelegt ist (d. h., um keine Drehung anzugeben), um einen kopiervorgang des geraden Speichers auszuführen. Stattdessen ruft die Direct3D-Runtime die ResourceCopy - oder ResourceCopyRegion-Funktion des Treibers auf, um einen direkten Speicherkopievorgang auszuführen, es sei denn, beide Ressourcen sind mehrfach stichprobeniert.

Die Qualität der Dehnung oder Verkleinerung, die der Benutzermodusanzeigetreiber ausführt, muss genauso gut sein wie die Dehnung oder Verkleinerung, die ein bilinearer Filter ausführt.

Die Direct3D-Runtime ruft die BltDXGI-Funktion des Treibers selten auf. Das heißt, die Runtime sollte BltDXGI nicht mehr als ein- oder zweimal pro Frame aufrufen, da die Runtime BltDXGI in erster Linie zur Unterstützung einer Präsentation verwendet.

Wenn die Runtime BltDXGI für eine Präsentation aufruft, legt die Runtime das Bitfeldflag Present im Flags-Member von DXGI_DDI_ARG_BLT fest. Die Runtime legt das Bitfeldflag Present fest, um den Treiber darüber zu informieren, dass zusätzliche Anforderungen für die Bitblt bestehen und dass eine zusätzliche Synchronisierung erforderlich ist (beispielsweise muss die Runtime möglicherweise eine zusätzliche Synchronisierung in Computerkonfigurationen durchführen, die zwei Grafikkarten enthalten, die jeweils separate Teile der Anzeige verarbeiten). Wenn das Bitfeldflag Present festgelegt ist, sollte der Treiber einen Kopiervorgang aus den Backpuffern einer Anwendung auf die freigegebene Oberfläche des DWM ausführen. Da die Synchronisierung für diese Art von Kopiervorgang nicht genau ist, sollten zerreißende Artefakte die schlechteste Art von Artefakten sein, die ein Benutzer erlebt. Bei dieser Art von Kopiervorgang sollte der Treiber keinen Ansatz mit mehreren Durchgängen verwenden, indem er zuerst in die Zieloberfläche auflöst und dann die Ergebnisse an Ort und Stelle farbkonvertiert, da die möglichen Artefakte viel schlechter wären.

Wenn der Treiber das Zurückgeben von DXGI_DDI_ERR_UNSUPPORTED während der Erstellung einer primären Oberfläche unterstützt (d. a. zurückgeben DXGI_DDI_ERR_UNSUPPORTED von einem Aufruf der CreateResource(D3D10) -Funktion mit dem D3D10_DDI_BIND_PRESENT-Flag , das im BindFlags-Member von D3D10DDIARG_CREATERESOURCE festgelegt ist, zusammen mit dem pPrimaryDesc-Member von D3D10DDIARG_CREATERESOURCE auf ungleich NULL festgelegt) muss der Treiber auch die Drehung während eines Kopiervorgangs unterstützen. Wenn der Treiber nie DXGI_DDI_ERR_UNSUPPORTED von einem Aufruf seiner CreateResource(D3D10) -Funktion zurückgibt, übergibt die Runtime den Wert DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180 oder DXGI_DDI_MODE_ROTATION_ROTATE270 Wert nie an den Rotieren-Member von DXGI_DDI_ARG_BLT. Daher ist in dieser Situation die BltDXGI-Funktion des Treibers nicht erforderlich, um die Drehung zu unterstützen.

Die Runtime legt einen Wert im Rotieren-Member von DXGI_DDI_ARG_BLT fest, um die Anzahl der Grad anzugeben, die den Inhalt der Quelle gegen den Uhrzeigersinn gedreht werden sollen, bevor der Treiber den Inhalt an das Ziel kopiert. Die Drehung wird in Schritten von 90 Grad angegeben.

Hinweis

Wenn die BltDXGI-Funktion des Treibers sRGB-formatierten Inhalt von einer Quelloberfläche auf eine Nicht-sRGB-Zieloberfläche kopiert, sollte der Treiber den sRGB-Inhalt unverändert kopieren (das heißt, der Treiber sollte keine sRGB-in-lineare Konvertierung durchführen).

Quelleinschränkungen

Die BltDXGI-Funktion verwendet immer eine ganze Quellunterquelle (im Gegensatz zu einem teilrechteckigen Bereich), um den Bitblt-Vorgang auszuführen. Darüber hinaus ist die Quelle eine D3D10DDIRESOURCE_TEXTURE2D Darstellung (angegeben im ResourceDimension-Member von D3D10DDIARG_CREATERESOURCE , wenn die Quelle in einem Aufruf der CreateResource(D3D10) -Funktion des Benutzermodusanzeigetreibers erstellt wird). Wenn die Runtime das Bitfeld Auflösen im Flags-Member von DXGI_DDI_ARG_BLT festlegt, ist die Quelle eine Ressource mit mehreren Stichproben. Die Quellressource ist auf eine Ressource beschränkt, in der das D3D10_DDI_BIND_PRESENT-Flag im BindFlags-Member von D3D10DDIARG_CREATERESOURCE festgelegt wurde. Das Format der Quelle (angegeben im Format-Element von D3D10DDIARG_CREATERESOURCE) ist auf Anzeigemodusformate beschränkt, die durch die folgenden Werte aus der DXGI_FORMAT-Enumeration angegeben werden:

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (siehe Hinweis unten.)
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

Hinweis

Wenn der Treiber das Quellformat DXGI_FORMAT_B8G8R8A8_UNORM unterstützt, gelten die folgenden Einschränkungen:

Wenn der Treiber einen Bitblt-Vorgang von einem Gleitkommaformat zu einem ganzzahligen Format wie BGRA8888 ausführt, muss er gamma implizit in die Ergebnisse codieren.
Wenn der Treiber dagegen einen Bitblt-Vorgang von einem Ganzzahlformat in ein Gleitkommaformat ausführt, muss er die Gammacodierung implizit aus den Ergebnissen entfernen.

Zieleinschränkungen

Das Ziel ist auch eine D3D10DDIRESOURCE_TEXTURE2D Darstellung. Das Format des Ziels ist auch auf Anzeigemodusformate beschränkt. Die Zielressource ist auf eine Ressource beschränkt, die als Renderziel gebunden ist (D3D10_DDI_BIND_RENDER_TARGET im BindFlags-Element von D3D10DDIARG_CREATERESOURCE oder D3D11DDIARG_CREATERESOURCE festgelegt).

Erstellen eines Stereobackpuffers

Wenn der Treiber ab Windows 8 einen Stereobackpuffer erstellen muss, sollte er Member der D3D10DDIARG_CREATERESOURCE- bzw. D3D11DDIARG_CREATERESOURCE-Struktur festlegen, auf die der pCreateResource-Parameter der Funktionen CreateResource(D3D10) oder CreateResource(D3D11) wie folgt verweist:

Legen Sie den ArraySize-Member auf den Wert 2 fest.
Legen Sie den D3D10_DDI_BIND_PRESENT-Flagwert im BindFlags-Element fest.

Darüber hinaus muss die BltDXGI-Funktion zur Unterstützung der Stereodarstellung alle Werte für die Elemente DstSubresource und SrcSubresource der DXGI_DDI_ARG_BLT-Struktur zulassen, die sich im Bereich der Quell- und Zielressourcen befinden.