DXGKDDI_CREATEALLOCATION回呼函式 (d3dkmddi.h)

發行項
02/23/2024

DxgkDdiCreateAllocation 函式會建立系統或視訊記憶體的配置。

語法

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

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

參數

[in] hAdapter

與顯示配接器相關聯的內容區塊句柄。顯示迷你埠驅動程式先前已將此句柄提供給 DxgkDdiAddDevice 函式之 MiniportDeviceContext 輸出參數中的 Microsoft DirectX 圖形核心子系統。

[in/out] pCreateAllocation

包含建立配置資訊之DXGKARG_CREATEALLOCATION 結構的指標。

傳回值

DxgkDdiCreateAllocation 會傳回下列其中一個值：

傳回碼	描述
STATUS_SUCCESS	DxgkDdiCreateAllocation 已成功建立配置。
STATUS_INVALID_PARAMETER	傳遞至 DxgkDdiCreateAllocation 的參數包含導致無法完成的錯誤。
STATUS_NO_MEMORY	DxgkDdiCreateAllocation 無法配置完成所需的記憶體。
STATUS_GRAPHICS_DRIVER_MISMATCH	顯示迷你埠驅動程式與起始對 DxgkDdiCreateAllocation 呼叫的使用者模式顯示驅動程式不相容。

備註

在使用者模式顯示驅動程式呼叫 pfnAllocateCb 函式之後，DirectX 圖形核心子系統會呼叫 display miniport 驅動程式的 DxgkDdiCreateAllocation 函式來建立配置。顯示迷你埠驅動程序必須解譯DXGK_ALLOCATIONINFO結構之 pPrivateDriverData 成員中從使用者模式顯示驅動程式傳遞的每個配置) 的私人數據 (，而且必須決定透過視訊記憶體管理員建立每個配置所需的參數清單。如需顯示迷你埠驅動程式如何將這些參數提供給視訊記憶體管理員的詳細資訊，請參閱建立配置時指定區段。

顯示迷你埠驅動程序必須傳回配置句柄，通常是私人驅動程序數據結構的指標，其中包含配置的相關信息。顯示迷你埠驅動程式可以隨時呼叫 DxgkCbGetHandleData 函式，以擷取配置句柄的私人數據。因此，不需要顯示迷你埠驅動程式，才能維護私人配置句柄數據表。事實上，我們強烈建議不要私用句柄數據表，因為它們可能會過時或與 Display-mode-switch 案例中的 DirectX 圖形核心子系統同步，例如快速使用者切換、熱卸除等等。

使用者模式顯示驅動程式會將配置指派給資源或裝置。若要判斷配置是否屬於資源，顯示迷你埠驅動程式可以檢查是否在 DxgkDdiCreateAllocation 參數指向之 DXGKARG_CREATEALLOCATION 結構的 Flags 成員中設定資源位欄位旗標。如果配置屬於資源，則顯示迷你埠驅動程式可以 (，但不需要) 傳回資源句柄，這通常是描述資源的私人驅動程序數據結構的指標。如果 DirectX 圖形核心子系統呼叫 DxgkDdiCreateAllocation 來為現有資源建立額外的配置，DXGKARG_CREATEALLOCATION 的 hResource 成員會包含先前 DxgkDdiCreateAllocation 呼叫所傳回的句柄。如有必要，顯示迷你埠驅動程式可以在呼叫 DxgkDdiCreateAllocation 期間變更資源句柄。

如果使用者模式顯示驅動程式在命令緩衝區中放置資源句柄，則顯示迷你埠驅動程式可以呼叫 DxgkCbGetHandleData 來擷取私人數據。顯示迷你埠驅動程式也可以藉由呼叫 DxgkCbEnumHandleChildren 函式來列舉所有資源的子配置。

從 Windows 7 開始，如果顯示迷你埠驅動程式處理對 DxgkDdiCreateAllocation 函式的呼叫，以建立 GDI 硬體加速的配置，驅動程式應該設定配置的大小 (包括 CPU 可見設定) 、pCreateAllocation-pAllocationInfo-Size>> 的間距值。

在 DxgkDdiCreateAllocation 呼叫中建立的資源屬於適配卡，而不是裝置。顯示迷你埠驅動程序不應該參考私人配置和資源數據結構內的任何位置的裝置數據。由於表面共用，資源可能會在使用者模式顯示驅動程式從中建立資源的裝置損毀之後使用。

DxgkDdiCreateAllocation 應該設為可分頁。