PFND3DDDI_CREATERESOURCE Rückruffunktion (d3dumddi.h)

Artikel
08/07/2023

Die CreateResource-Funktion erstellt eine Ressource.

Syntax

PFND3DDDI_CREATERESOURCE Pfnd3dddiCreateresource;

HRESULT Pfnd3dddiCreateresource(
  HANDLE hDevice,
  D3DDDIARG_CREATERESOURCE *unnamedParam2
)
{...}

Parameter

hDevice

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

unnamedParam2

pResource [in, out]

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

Rückgabewert

CreateResource gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	Die Ressource wurde erfolgreich erstellt.
E_OUTOFMEMORY	CreateResource konnte nicht den erforderlichen Arbeitsspeicher zuordnen, um sie abzuschließen.
D3DERR_NOTAVAILABLE	CreateResource konnte die Ressource aus anderen Gründen nicht erstellen, als dass sie keinen Arbeitsspeicher zuweisen konnte. CreateResource kann diesen Fehler nur beim Erstellen von Vertex- oder Indexpuffern zurückgeben.

Hinweise

Der Aufruf von CreateResource kann eine Liste von Oberflächen enthalten. Das SurfCount-Element der D3DDDIARG_CREATERESOURCE-Struktur , die durch den pResource-Parameter angegeben wird, gibt die Anzahl der zu erstellenden Oberflächen an, einschließlich der MIP-Map-Ebenen. 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 CreateResource-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 CreateResource-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_CREATERESOURCE-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 CreateResource-Aufruf übergeben wurde, und den Wert mit einem anderen Wert überschreiben, den die Microsoft Direct3D-Runtime verwenden kann, wenn der CreateResource-Aufruf zurückgibt. Anders ausgedrückt: Bei Aufrufen der Runtime verwendet der Benutzermodusanzeigetreiber den hResource-Wert , der an CreateResource übergeben wurde. in Aufrufen des Anzeigetreibers für den Benutzermodus (z. B. bei Aufrufen der Funktionen SetTexture oder SetStreamSource ) verwendet die Laufzeit den hResource-Wert , der von CreateResource 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_CREATERESOURCE 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_CREATERESOURCE 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 CreateResource - 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_RESOURCEFLAGS-Struktur angegebenen Bitfeldflags werden im Flags-Element von D3DDDIARG_CREATERESOURCE ü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 keine vorhandenen Treiber unterbrechen, dürfen die Treiber nicht die folgenden reservierten Member der D3DDDIARG_CREATERESOURCE-Struktur in Aufrufen ihrer CreateResource-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.

Der neue CreateResource-DDI unterscheidet sich von DdCreateSurface DDI für das Microsoft Windows 2000-Anzeigetreibermodell auf folgende Weise:

Im neuen CreateResource-DDI werden Oberflächen nie explizit angefügt. Alle Anlagen werden von der atomic create impliziert.
In der neuen CreateResource DDI ist die partielle Erstellung von Cubezuordnungen nicht zulässig.

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 Anzeigetreiber im Benutzermodus den Puffer nicht aus anderen Gründen als nicht genügend Arbeitsspeicher erstellen kann (z. B. fehlende Hardwareunterstützung), muss der Treiber mit D3DERR_NOTAVAILABLE fehlschlagen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Desktop
Kopfzeile	d3dumddi.h (include D3dumddi.h)