DXGKDDI_CREATEALLOCATION Rückruffunktion (d3dkmddi.h)

Artikel
02/06/2025

Die Kernelmodusanzeigetreiber (KMD) DxgkDdiCreateAllocation--Funktion erstellt Zuordnungen des System- oder Videospeichers.

Syntax

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

NTSTATUS DxgkddiCreateallocation(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_CREATEALLOCATION pCreateAllocation
)
{...}

Parameter

[in] hAdapter

Ein Handle zu einem Kontextblock, der einem Anzeigeadapter zugeordnet ist. Der KMD hat dieses Handle zuvor für Dxgkrnl- im MiniportDeviceContext Ausgabeparameter der DxgkDdiAddDevice--Funktion bereitgestellt.

[in/out] pCreateAllocation

Ein Zeiger auf eine DXGKARG_CREATEALLOCATION-Struktur, die Informationen zum Erstellen von Zuordnungen enthält.

Rückgabewert

DxgkDdiCreateAllocation gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	DxgkDdiCreateAllocation die Zuordnung erfolgreich erstellt.
STATUS_INVALID_PARAMETER	Die übergebenen Parameter enthalten Fehler, die verhindern, dass DxgkDdiCreateAllocation- abgeschlossen werden.
STATUS_NO_MEMORY	DxgkDdiCreateAllocation konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
STATUS_GRAPHICS_DRIVER_MISMATCH	Die KMD ist nicht mit dem Benutzermodusanzeigetreiber (USER-Mode Display Driver, UMD) kompatibel, der den Aufruf von DxgkDdiCreateAllocationinitiiert hat.

Bemerkungen

Nachdem die UMD pfnAllocateCbaufgerufen hat, ruft Dxgkrnl die DxgkDdiCreateAllocation-Funktion von KMD auf, um die Zuordnungen zu erstellen. Der KMD muss die privaten Daten (im pPrivateDriverData Member der DXGK_ALLOCATIONINFO-Struktur für jede Zuordnung) interpretieren, die von der UMD übergeben wird, und die Liste der Parameter bestimmen, die zum Erstellen der einzelnen Zuordnungen über den Videospeicher-Manager erforderlich sind. Weitere Informationen dazu, wie der KMD diese Parameter dem Videospeicher-Manager bereitstellt, finden Sie unter Angeben von Segmenten beim Erstellen von Zuordnungen.

Der KMD muss einen Zuordnungshandle zurückgeben, bei dem es sich in der Regel um einen Zeiger auf eine private Treiberdatenstruktur handelt, die Informationen zur Zuordnung enthält. Die UMD kann die DxgkCbGetHandleData Funktion jederzeit aufrufen, um die privaten Daten für einen Zuordnungshandle abzurufen. Daher ist der KMD nicht erforderlich, um eine private Zuordnungshandle-Tabelle beizubehalten. Tatsächlich wird dringend davon abgeraten, private Handle-Tabellen zu verwenden, da sie veraltet oder nicht mehr mit dem DirectX-Grafik-Kernel-Subsystem in Anzeigemodus-Switch-Szenarien wie schnellem Benutzerschalter, hot unplug usw. synchronisiert werden könnten.

Der Anzeigetreiber für den Benutzermodus weist entweder einer Ressource oder einem Gerät eine Zuordnung zu. Um festzustellen, ob die Zuordnung zu einer Ressource gehört, kann der Anzeigeminiporttreiber überprüfen, ob das -Bitfeld-Flag Bitfeld im Flags Element der DXGKARG_CREATEALLOCATION Struktur festgelegt ist, auf die der pCreateAllocation Parameter von DxgkDdiCreateAllocation verweist. Wenn die Zuordnung zu einer Ressource gehört, kann der Anzeige-Miniporttreiber (aber nicht erforderlich) einen Ressourcenhandle zurückgeben, was in der Regel ein Zeiger auf eine private Treiberdatenstruktur ist, die die Ressource beschreibt. Wenn das DirectX-Grafiksubsystem DxgkDdiCreateAllocation- aufruft, um eine zusätzliche Zuordnung für eine vorhandene Ressource zu erstellen, enthält das hResource Member von DXGKARG_CREATEALLOCATION das Handle, das vom vorherigen DxgkDdiCreateAllocation Aufruf für diese Ressource zurückgegeben wurde. Bei Bedarf kann der Anzeigeminiporttreiber den Ressourcenhandle während eines Aufrufs von DxgkDdiCreateAllocationändern.

Wenn der Benutzermodus-Anzeigetreiber ein Ressourcenhandle in einem Befehlspuffer platziert, kann der Miniporttreiber die privaten Daten abrufen, indem DxgkCbGetHandleDataaufgerufen wird. Der Miniporttreiber für die Anzeige kann auch alle untergeordneten Zuordnungen der Ressource aufzählen, indem die DxgkCbEnumHandleChildren-Funktion aufgerufen wird.

Ab Windows 7, wenn ein Display-Miniporttreiber einen Aufruf des DxgkDdiCreateAllocation--Funktion verarbeitet, um Zuordnungen für die GDI-Hardwarebeschleunigung zu erstellen, sollte der Treiber die Größe der Zuordnung (einschließlich des Pitchwerts für cpu sichtbare Zuordnungen) festlegen, pCreateAllocation->pAllocationInfo->Größe.

Die Ressourcen, die im DxgkDdiCreateAllocation Aufruf erstellt werden, gehören zum Adapter und nicht zum Gerät. Der Anzeige-Miniporttreiber sollte nicht überall in den privaten Zuordnungs- und Ressourcendatenstrukturen auf die Gerätedaten verweisen. Aufgrund der Oberflächenfreigabe kann eine Ressource nach der Zerstörung des Geräts verwendet werden, von dem der Benutzermodusanzeigetreiber die Ressource erstellt hat.

DxgkDdiCreateAllocation sollte seitenfähig gemacht werden.

Zuordnen von Verlaufspuffern

Ab Windows 8.1 kann die KMD den DXGK_ALLOCATIONINFOFLAGSfestlegen, wenn DxgkDdiCreateAllocation- aufgerufen wird.HistoryBuffer Mitglied an, um anzugeben, dass der Benutzermodustreiber die Erstellung und Zerstörung von Verlaufspuffern verwalten kann.