PFND3DDDI_CREATERESOURCE2 Rückruffunktion (d3dumddi.h)

Artikel
02/23/2024

Dient zum Erstellen einer Ressource. Wird von Windows Display Driver Model (WDDM) 1.2 und höher für Benutzermodus-Anzeigetreiber implementiert.

Syntax

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

Parameter

[in] hDevice

Ein Handle für das Anzeigegerät (Grafikkontext), das zum Erstellen der Ressource verwendet wird.

unnamedParam2

pResource2 [in, out]

Ein Zeiger auf eine D3DDDIARG_CREATERESOURCE2 Struktur, die die erstellte Ressource beschreibt.

Rückgabewert

Gibt S_OK oder ein entsprechendes Fehlerergebnis zurück. WdDM 1.3 und höher Direct3D Level 9-Treiber müssen diesen Fehlercode zurückgeben:

Rückgabecode	Beschreibung
E_INVALIDARG	Die D3DDDIARG_CREATERESOURCE2 . Flagsmember hat den Wert des CaptureBuffer-Flags festgelegt, und die Ressource überschreitet die vom Treiber unterstützten Werte.

Hinweise

Der Aufruf von CreateResource2 kann eine Liste von Oberflächen enthalten. Das SurfCount-Element der D3DDDIARG_CREATERESOURCE2-Struktur , die durch den pResource2-Parameter angegeben wird, gibt die Anzahl der zu erstellenden Oberflächen an – einschließlich MIP-Kartenebenen. Beispielsweise enthält eine MIP-Map-Ressource mit einer Textur von 256 x 256 x 9 eine Liste von neun Oberflächen, bei denen der SurfCount-Member und die Anzahl der MIP-Kartenebenen auf 9 festgelegt sind. Bei einer Cubekarte, die neun MIP-Kartenebenen enthält, sollte die Anzahl der MIP-Kartenebenen auf 9 und SurfCount auf 54 festgelegt sein. Für eine Swapchain mit drei Oberflächen sollte SurfCount auf 3 und die Anzahl der MIP-Kartenebenen auf 0 festgelegt sein. Beachten Sie, dass die Anzahl der MIP-Kartenebenen immer kleiner oder gleich dem Wert in SurfCount ist.

Als Reaktion auf den CreateResource2-Aufruf kann der Anzeigetreiber im Benutzermodus die PfnAllocateCb-Funktion aufrufen, um eine oder mehrere Speicherbelegungen zu erstellen. Der Anzeigetreiber für den Benutzermodus muss bestimmen, ob er mehrere Zuordnungen pro Oberfläche, eine Zuordnung für alle Oberflächen oder eine Zuordnung pro Oberfläche erstellen muss. Weitere Informationen zu Zuordnungen finden Sie unter Videospeicherverwaltung und GPU-Planung.

Hinweis Die CreateResource2-Funktion des Treibers ist nicht erforderlich, um pfnAllocateCb vor der Rückgabe aufzurufen. Stattdessen kann der Treiber die Erstellung der Zuordnung verzögern.

Hinweis Eine Ressource kann nur freigegeben werden, wenn alle Zuordnungen für die Ressource atomar in einem einzigen Aufruf von pfnAllocateCb vorgenommen werden.

Das hResource-Element in der D3DDDIARG_CREATERESOURCE2-Struktur ist ein Handle, das zum Identifizieren der Ressource verwendet wird. Der Anzeigetreiber für den Benutzermodus sollte den Wert von hResource speichern, der im CreateResource2-Aufruf übergeben wurde, und den Wert mit einem anderen Wert überschreiben, den die Microsoft Direct3D-Runtime verwenden kann, wenn der CreateResource2-Aufruf zurückgibt. Anders ausgedrückt: Bei Aufrufen der Runtime verwendet der Anzeigetreiber für den Benutzermodus den hResource-Wert , der an CreateResource2 übergeben wurde. in Aufrufen des Benutzermodusanzeigetreibers (z. B. bei Aufrufen der Funktionen SetTexture oder SetStreamSource ) verwendet die Laufzeit den hResource-Wert , der von CreateResource2 zurückgegeben wurde. Beachten Sie, dass jede Oberfläche nicht über einen expliziten Handle verfügt. Wenn auf die Oberfläche einzeln verwiesen werden muss (z. B. in einem Aufruf der Blt-Funktion ), wird sie durch ein Handle und einen Index referenziert. Der Index identifiziert die Oberfläche innerhalb der Ressource. Der Index ist identisch mit dem Index der Oberfläche im Array, das im pSurfList-Element von D3DDDIARG_CREATERESOURCE2 enthalten ist.

Ressourcen können von mehreren Geräten (hDevice) und Prozessen gemeinsam genutzt werden. Die Runtime gibt an, dass eine Ressource freigegeben wird, indem das SharedResource-Bitfeldflag im Flags-Element von D3DDDIARG_CREATERESOURCE2 festgelegt wird. Wenn dieses Bitfeldflag festgelegt ist, muss der Benutzermodusanzeigetreiber die folgenden Einschränkungen für freigegebene Ressourcen einhalten:

Der Anzeigetreiber für den Benutzermodus kann die Funktionen pfnAllocateCb und pfnDeallocateCb jeweils genau einmal aufrufen.
Der Anzeigetreiber für den Benutzermodus kann keine zusätzlichen Zuordnungen für die Ressource erstellen, nachdem die Ressource ursprünglich erstellt wurde, und kann die Ressourcenzuordnungen ebenfalls nur zu dem Zeitpunkt zerstören, zu dem die Ressource selbst zerstört wird.
Wenn die DestroyResource-Funktion des Benutzermodustreibers für eine freigegebene Ressource aufgerufen wird, die durch einen Aufruf der CreateResource2 - oder OpenResource-Funktion des Treibers erstellt oder geöffnet wurde, muss der Treiber den hResource-Member der D3DDDICB_DEALLOCATE-Struktur auf ungleich NULL und der NumAllocations-Member von D3DDDICB_DEALLOCATE in einem Aufruf der pfnDeallocateCb-Funktion auf Null festlegen, um die Ressource zu zerstören oder zu schließen. Das heißt, Zuordnungen, die einer freigegebenen Ressource zugeordnet sind, können nicht einzeln zerstört oder geschlossen werden. Die Ressource muss in einem Aufruf von pfnDeallocateCb atomar zerstört oder geschlossen werden.
Die Anzahl der Zuordnungen muss für den Ressourcentyp konsistent sein (das heißt, ein anderer Prozess, der denselben Ressourcentyp erstellt, sollte die gleiche Anzahl und Art von Zuordnungen generieren). Darüber hinaus ist das Umbenennen für diese Ressourcen nicht zulässig.

Die in der D3DDDI_RESOURCEFLAGS2-Struktur angegebenen Bitfeldflags werden im Flags-Member von D3DDDIARG_CREATERESOURCE2 übergeben.

Hinweis Eine Ressource kann ohne Angabe von Flags erstellt werden. Oberflächen, die einer solchen Ressource zugeordnet sind, können möglicherweise gesperrt werden und eine Quelle oder ein Ziel in einem Bitblockübertragungsvorgang (Bitblt) sein. Solche Oberflächen können jedoch nicht für andere Zwecke verwendet werden.

Hinweis Einfache Oberflächen unterscheiden sich von Texturen oder eigenständigen Renderzielen durch das Fehlen des Flags Textur oder Primäres Bitfeld. Das Vorhandensein des Flags primäres Bitfeld weist beispielsweise auf ein eigenständiges Renderziel hin, und das Fehlen dieses Flags weist auf ein Renderziel hin, das ein Hintergrundpuffer ist.

Hinweis Um sicherzustellen, dass Änderungen an der Laufzeit vorhandene Treiber nicht beeinträchtigen, dürfen die Treiber nicht die folgenden reservierten Member der D3DDDIARG_CREATERESOURCE2-Struktur in Aufrufen ihrer CreateResource2-Funktion verwenden, um das Verhalten der Treiber zu beeinflussen:

Die nicht definierten Bits des Flags-Elements sind reserviert.
Wenn das Flag primäres Bitfeld nicht in Flags festgelegt ist, sind die Elemente RefreshRate und Output reserviert.
Wenn das Bitfeldflag RenderTarget, DecodeRenderTarget oder VideoProcessRenderTarget in Flags nicht festgelegt ist, sind die Elemente MultisampleType und MultisampleQuality reserviert.
Wenn das VertexBuffer-Bitfeldflag nicht in Flags festgelegt ist, ist das Fvf-Element reserviert.
Wenn die Bitfeldflags Texture, CubeMap und Volume nicht in Flags festgelegt sind, ist das MipLevels-Element reserviert.

Weitere Informationen zum Erstellen und Zerstören von Ressourcen finden Sie unter Behandeln von Ressourcenerstellung und -zerstörung.

Für eine Systemarbeitsspeicherressource kann der Anzeige-Miniporttreiber eine Zuordnung um den Systemspeicher umschließen, wenn der Systemspeicher ordnungsgemäß für den direkten Zugriff durch die Grafikverarbeitungseinheit (GRAPHICS Processing Unit, GPU) ausgerichtet ist. Der Anzeige-Miniporttreiber umschließt eine Zuordnung um den Systemspeicher, indem das ExistingSysMem-Flag im Flags-Element der DXGK_ALLOCATIONINFO-Struktur festgelegt wird, wenn die Zuordnung mithilfe der DxgkDdiCreateAllocation-Funktion erstellt wird. Wenn der Anzeige-Miniporttreiber keine Zuordnung um den Systemspeicher umschließen kann oder das Wrapping fehlschlägt, sollte der Treiber die Erstellung der Ressource trotzdem erfolgreich ausführen und die CPU für den Zugriff auf die Ressource verwenden.

Wenn die Laufzeit die Erstellung eines Scheitelpunkt- oder Indexpuffers anfordert und der Benutzermodusanzeigetreiber den Puffer aus anderen Gründen als nicht genügend Arbeitsspeicher (z. B. fehlender Hardwareunterstützung) nicht erstellen kann, muss der Treiber mit D3DERR_NOTAVAILABLE fehlschlagen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8
Unterstützte Mindestversion (Server)	Windows Server 2012
Zielplattform	Desktop
Kopfzeile	d3dumddi.h (include D3dumddi.h)