PFND3DDDI_CREATERESOURCE2 Rückruffunktion (d3dumddi.h)

Artikel
02/06/2025

Erstellt eine Ressource. Implementiert durch Windows Display Driver Model (WDDM) 1.2 und höher Benutzermodus-Anzeigetreiber.

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-Treiber der Direct3D-Ebene 9 müssen diesen Fehlercode zurückgeben:

Rückgabecode	Beschreibung
E_INVALIDARG	Die D3DDDIARG_CREATERESOURCE2 . Flagsmember hat den CaptureBuffer-Flagwert festgelegt, und die Ressource überschreitet, was der Treiber unterstützen kann.

Bemerkungen

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 einschließlich MIP-Kartenebenen an. Beispielsweise enthält eine 256x256x9 Textur-MIP-Map-Ressource eine Liste von neun Oberflächen, auf denen das SurfCount Member und die Anzahl der MIP-Kartenebenen auf 9 festgelegt sind. Eine Cubezuordnung mit neun MIP-Kartenebenen sollte die Anzahl der MIP-Kartenebenen auf 9 und SurfCount- auf 54 festgelegt haben. 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 für den Benutzermodus die pfnAllocateCb--Funktion aufrufen, um eine oder mehrere Speicherzuordnungen 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- aufzurufen, bevor sie zurückgegeben wird; Stattdessen kann der Treiber die Zuordnungserstellung zurückstellen.

Hinweis Eine Ressource kann nur freigegeben werden, wenn alle Zuordnungen für die Ressource in einem einzigen Aufruf an pfnAllocateCbatomar erfolgen.

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 hResource- speichern, die im CreateResource2-Aufruf übergeben wurde, und den Wert mit einem anderen Wert überschreiben, den die Microsoft Direct3D-Laufzeit verwenden kann, wenn der CreateResource2-aufruf Aufrufs zurückgibt. Anders ausgedrückt: Bei Aufrufen der Laufzeit verwendet der Anzeigetreiber für den Benutzermodus den hResource Wert, der an CreateResource2übergeben wurde; in Aufrufen des Anzeigetreibers für den Benutzermodus (z. B. bei Aufrufen des SetTexture- oder SetStreamSource--Funktionen), verwendet die Laufzeit den hResource Wert, der von CreateResource2zurückgegeben wurde. Beachten Sie, dass für jede Oberfläche kein expliziter Ziehpunkt vorhanden ist; wenn die Oberfläche einzeln bezeichnet werden muss (z. B. in einem Aufruf der Blt-Funktion), wird sie durch ein Handle und einen Index bezeichnet. Der Index identifiziert die Oberfläche innerhalb der Ressource. Der Index ist identisch mit dem Index der Oberfläche in dem Array, das im pSurfList Mitglied von D3DDDIARG_CREATERESOURCE2enthalten ist.

Ressourcen können von mehreren Geräten (hDevice) und Prozessen gemeinsam genutzt werden. Die Laufzeit gibt an, dass eine Ressource gemeinsam verwendet wird, indem sie das SharedResource- Bitfeld-Flag im Flags Member von D3DDDIARG_CREATERESOURCE2festlegen. Wenn dieses Bitfeld-Flag festgelegt ist, muss der Anzeigetreiber für den Benutzermodus die folgenden Einschränkungen für freigegebene Ressourcen einhalten:

Der Anzeigetreiber für den Benutzermodus kann die pfnAllocateCb- aufrufen und pfnDeallocateCb funktionen genau einmal.
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 Benutzers im Benutzermodus für eine freigegebene Ressource aufgerufen wird, die über einen Aufruf der CreateResource2-- oder OpenResource- Funktion des Treibers erstellt oder geöffnet wurde, der Treiber muss das hResource Member der D3DDDICB_DEALLOCATE Struktur auf Nicht-NULL und das NumAllocations-Element von D3DDDICB_DEALLOCATE in einem Aufruf der pfnDeallocateCb--Funktion auf Null festlegen. 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 pfnDeallocateCbatomisch zerstört oder geschlossen werden.
Die Anzahl der Zuordnungen muss für den Ressourcentyp konsistent sein (d. a. ein anderer Prozess, der denselben Ressourcentyp erstellt, sollte dieselbe Anzahl und art von Zuordnungen generieren). Darüber hinaus ist die Umbenennung für diese Ressourcen nicht zulässig.

Die Bitfeld-Flags, die in der D3DDDI_RESOURCEFLAGS2-Struktur angegeben sind, werden im Flags Member von D3DDDIARG_CREATERESOURCE2übergeben.

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

Note Plain surfaces unterscheiden sich von Texturen oder eigenständigen Renderzielen, da die Texture oder Primary Bitfeldkennzeichnung nicht vorhanden ist. Beispielsweise gibt das Vorhandensein des Primären Bitfeldflagge ein eigenständiges Renderziel an, und das Fehlen dieses Flags gibt ein Renderziel an, das ein Hintergrundpuffer ist.

Hinweis Um sicherzustellen, dass Änderungen an der Laufzeit vorhandene Treiber nicht unterbrechen, 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 der Flags Member sind reserviert.
Wenn das Primäre Bitfeld-Flag nicht in Flagsfestgelegt ist, sind die RefreshRate und Output Member reserviert.
Wenn das RenderTarget, DecodeRenderTarget-oder VideoProcessRenderTarget Bitfeld-Flag nicht in Flagsfestgelegt ist, werden die MultisampleType- und MultisampleQuality Member reserviert.
Wenn das VertexBuffer- Bitfeld-Flag nicht in Flagsfestgelegt ist, ist das Fvf Mitglied reserviert.
Wenn die Texture, CubeMap-und Volume- Bitfeld-Flags nicht in Flagsfestgelegt sind, ist das MipLevels Member reserviert.

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

Bei einer Systemspeicherressource kann der Display-Miniporttreiber eine Zuordnung um den Systemspeicher umschließen, wenn der Systemspeicher ordnungsgemäß für den direkten Zugriff durch die Grafikverarbeitungseinheit (GPU) ausgerichtet ist. Der Display-Miniporttreiber umschließt eine Zuordnung des Systemspeichers, indem das flag ExistingSysMem im Flags Member der DXGK_ALLOCATIONINFO Struktur festgelegt wird, indem die DxgkDdiCreateAllocation-Funktion verwendet wird. Wenn der Anzeige-Miniporttreiber keine Zuordnung um den Systemspeicher umschließen kann oder der Umbruch fehlschlägt, sollte der Treiber dennoch erfolgreich die Erstellung der Ressource ausführen und die CPU für den Zugriff auf die Ressource verwenden.

Wenn die Laufzeitanforderungen zum Erstellen eines Vertex- oder Indexpuffers und wenn der Anzeigetreiber für den Benutzermodus den Puffer aus anderen Gründen als aus dem Arbeitsspeicher (z. B. fehlender Hardwareunterstützung) nicht erstellen kann, muss der Treiber mit D3DERR_NOTAVAILABLEfehlschlagen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 8
mindestens unterstützte Server-	Windows Server 2012
Zielplattform-	Desktop
Header-	d3dumddi.h (include D3dumddi.h)