DXGKDDI_RENDERKM回呼函式 (d3dkmddi.h)

發行項
02/23/2024

針對支援 GDI 硬體加速的顯示適配卡， DxgkDdiRenderKm 函式會從核心模式標準顯示驅動程式 (CDD) 傳遞的命令緩衝區產生直接記憶體存取 (DMA) 緩衝區。

語法

DXGKDDI_RENDERKM DxgkddiRenderkm;

NTSTATUS DxgkddiRenderkm(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}

參數

[in] hContext

DMA 和命令緩衝區裝置內容的句柄。顯示迷你埠驅動程式的 DxgkDdiCreateContext 函式先前在 dxgkDdiCreateContext 參數指向的 hContextDXGKARG_CREATECONTEXT 結構 hContext 成員中傳回此句柄。

如果驅動程式不支持內容建立，Microsoft DirectX 圖形核心子系統會將內容的句柄取代為裝置的句柄。顯示迷你連接埠驅動程式的 DxgkDdiCreateDevice 函式先前傳回DXGKARG_CREATEDEVICE結構之 pCreateDevice 參數指向之 hDevice 成員中的裝置句柄。

[in/out] pRenderKmArgs

DXGKARG_RENDER 結構的指標，其中包含 DMA 緩衝區和格式化命令緩衝區的相關信息。

如果顯示迷你埠驅動程序支援 GDI 硬體加速，pRenderKmArgs-pCommand> 會指向DXGK_RENDERKM_COMMAND命令緩衝區。

驅動程式必須將輸入命令緩衝區轉譯成 DMA 緩衝區命令，並建置修補程式位置清單。

傳回值

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

傳回碼	描述
STATUS_SUCCESS	已翻譯整個命令緩衝區。
STATUS_NO_MEMORY	DxgkDdiRenderKm 無法配置完成所需的記憶體。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	目前的 DMA 緩衝區已耗盡。
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm 偵測到圖形硬體不支援的指令參數;不過，圖形硬體可以支援指示本身。不需要驅動程式才能傳回這個錯誤碼。相反地，它可以在偵測到不支援的指令參數時傳回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm 偵測到數據或指令不足或超溢。也就是說，驅動程式收到的指令或數據比預期還少。不需要驅動程式才能傳回這個錯誤碼。相反地，它可以在偵測到數據或指令不足或溢出時傳回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_HANDLE	DxgkDdiRenderKm 偵測到命令緩衝區中的無效句柄。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	顯示迷你埠驅動程式在 DMA 數據流中偵測到錯誤。如果驅動程式傳回此錯誤碼，圖形內容裝置會處於遺失狀態。

備註

DirectX 圖形核心子系統會呼叫 display miniport 驅動程式的 DxgkDdiRenderKm 函式，從核心模式 Canonical Display Driver 所傳遞的命令緩衝區產生 DMA 緩衝區， (操作系統提供的 CDD) 。除了輸出 DMA 緩衝區之外，顯示迷你埠驅動程式也應該產生輸出修補程式位置的清單。視訊記憶體管理員會使用此列表來適當地分割和修補 DMA 緩衝區。

存取核心緩衝區不需要保護程序 try/except 代碼。

如果 CDD 可以更理想的方式重新建立資訊，則不需要顯示迷你埠驅動程式。例如，如果 pRender-pPatchLocationListIn> 成員是空的，因為使用者模式顯示驅動程式未提供輸入修補程式位置清單，則顯示迷你埠驅動程式可以改為根據命令緩衝區的內容產生 pRender-pPatchLocationListOut> 成員的內容。

除了裝置特定的句柄之外，DirectX 圖形核心子系統還會為每個配置提供最後一個已知 GPU 區段位址的顯示迷你埠驅動程式。如果配置索引 N 目前已分頁出，DirectX 圖形核心子系統會將 DXGKARG_RENDER pAllocationList 成員之 n 第 N個元素的 SegmentId 成員設定為零。如果配置清單第 N個元素的 SegmentId 成員未設定為零，則顯示迷你埠驅動程式必須先使用提供的區段位址資訊修補產生的 DMA 緩衝區，然後 DirectX 圖形核心子系統才會呼叫 DxgkDdiPatch 函式來重新修補 DMA 緩衝區。驅動程式必須在要求時執行此初始修補，因為 DirectX 圖形核心子系統可能不會在驅動程式應該已正確修補的 DMA 緩衝區上呼叫 DxgkDdiPatch 函式。

即使驅動程式的 DxgkDdiRenderKm 函式執行如先前所述的初始 DMA 緩衝區修補，驅動程式仍必須將配置的所有參考插入 pPatchLocationListOutDXGKARG_RENDER 成員所指定的輸出修補程式位置清單中。此清單必須包含所有參考，因為配置位址可能會在 DMA 緩衝區提交至 GPU 之前變更;因此，DirectX 圖形核心子系統會呼叫 DxgkDdiPatch 函式來重新修補 DMA 緩衝區。

若要解除配置系結，顯示迷你埠驅動程式可以在配置清單中指定參考 NULL 句柄的專案，然後使用參考該 NULL 配置的修補程式位置元素。一般而言，驅動程式應該使用配置清單的第一個專案， (元素0) 作為 NULL 元素。

在保證的合約 DMA 模式中，當顯示迷你埠驅動程式將命令緩衝區轉譯為 DMA 緩衝區時，CDD 必須保證足夠的資源以供翻譯命令使用。如果翻譯沒有足夠的資源存在，則顯示迷你埠驅動程序必須拒絕 DMA 緩衝區。如需詳細資訊，請參閱使用保證的合約 DMA 緩衝區模型。

DxgkDdiRenderKm 應該可分頁。