DXGKDDI_RENDER回呼函式 (d3dkmddi.h)

發行項
02/23/2024

DxgkDdiRender 函式會從使用者模式顯示驅動程式傳遞的命令緩衝區產生直接記憶體存取 (DMA) 緩衝區。

語法

DXGKDDI_RENDER DxgkddiRender;

NTSTATUS DxgkddiRender(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRender
)
{...}

參數

[in] hContext

DMA 和命令緩衝區之裝置內容的句柄。 display miniport 驅動程式的 DxgkDdiCreateContext 函式先前在 dxgkDdiCreateContext 參數指向的 DXGKARG_CREATECONTEXT 結構 hContext 成員中傳回此句柄。

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

[in/out] pRender

包含 DMA 和命令緩衝區相關信息之DXGKARG_RENDER 結構的指標。

傳回值

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

傳回碼	Description
STATUS_SUCCESS	已翻譯整個命令緩衝區。
STATUS_NO_MEMORY	DxgkDdiRender 無法配置完成所需的記憶體。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	目前的 DMA 緩衝區已耗盡。
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiRender 偵測到非特殊許可權指令 (也就是說，存取記憶體超出目前中央處理單位 [CPU] 進程許可權的指令) 。
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiRender 偵測到圖形硬體不支援的指示。
STATUS_INVALID_PARAMETER	DxgkDdiRender 偵測到圖形硬體不支援的指令參數;不過，圖形硬體可以支援指示本身。不需要驅動程式才能傳回這個錯誤碼。相反地，當偵測到不支援的指令參數時，它可以傳回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_USER_BUFFER	DxgkDdiRender 偵測到數據或指令不足或滿溢。也就是說，驅動程式收到的指示或數據比預期還少。不需要驅動程式才能傳回這個錯誤碼。相反地，當偵測到數據或指令不足或超溢時，它可以傳回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_HANDLE	DxgkDdiRender 偵測到命令緩衝區中的句柄無效。
STATUS_GRAPHICS_DRIVER_MISMATCH	顯示迷你埠驅動程式與起始對 DxgkDdiRender 呼叫 (的使用者模式顯示驅動程式不相容，也就是提交命令緩衝區) 。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	顯示迷你埠驅動程式在 DMA 數據流中偵測到錯誤。如果驅動程式傳回此錯誤碼，圖形內容裝置會處於遺失狀態。

備註

DirectX 圖形核心子系統會呼叫 display miniport 驅動程式的 DxgkDdiRender 函式，從使用者模式顯示驅動程式傳遞的命令緩衝區產生 DMA 緩衝區。當顯示迷你埠驅動程式從命令緩衝區轉譯為 DMA 緩衝區時，驅動程式也應該驗證命令緩衝區，以確保命令緩衝區不包含任何可用來存取不屬於進程的記憶體的特殊許可權命令或命令。除了輸出 DMA 緩衝區之外，顯示迷你埠驅動程式也應該產生輸出修補程式位置的清單。視訊記憶體管理員會使用此列表適當地分割和修補 DMA 緩衝區。

命令緩衝區 pCommand 和輸入修補程式位置清單 pPatchLocationListIn 使用者模式顯示驅動程式產生的配置會從使用者模式位址空間配置，並傳遞至未變更的顯示迷你埠驅動程式。顯示迷你埠驅動程式必須在緩衝區和清單的任何存取上使用__try/__except程式代碼，而且必須先驗證緩衝區和清單的內容，再將內容複製到個別的核心緩衝區， (也就是說，將 pCommand 成員的內容複製到 pDmaBuffer 成員，並將 pPatchLocationListIn 成員的內容複製到 pPatchLocationListOut 成員之前，這些是 pRender 參數指向 ) DXGKARG_RENDER 結構的所有成員。

以下是顯示迷你埠驅動程序應該如何使用 __try 和 __except 邏輯來存取這些緩衝區的範例。 AllocationListIn 會指向使用者模式緩衝區。

__try
  {
    for (Index = 0; Index < AllocationListInSize; AllocationTable++, 
           AllocationListIn++, AllocationListOut++, Index++) 
    {
      D3DKMT_HANDLE AllocationHandle = AllocationListIn->hAllocation;
      . . .
    }
  }
__except(EXCEPTION_EXECUTE_HANDLER)
  {
    Status = STATUS_INVALID_PARAMETER;
    SAMPLE_LOG_ERROR(
  "Exception occurred accessing user-mode allocation list. Returning Status=0x%I64x",
      Status);
    goto cleanup;
  }

注意

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

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

使用者模式顯示驅動程式所提供的配置清單會在核心轉換期間驗證、複製並轉換成內核模式配置清單。 DirectX 圖形核心子系統會將每個 D3DDDI_ALLOCATIONLIST 元素轉換成 DXGK_ALLOCATIONLIST 元素，方法是將使用者模式顯示驅動程式所提供的D3DKMT_HANDLE型別句柄轉換成裝置特定的句柄，顯示迷你埠驅動程式的 DxgkDdiOpenAllocation 函式會傳回此句柄。每個配置的索引和配置 (的寫入狀態，也就是在轉換期間， WriteOperation 位字段旗標的設定) 會維持不變。

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

注意

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

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

當顯示迷你埠驅動程式將命令緩衝區轉譯為 DMA 緩衝區時，顯示迷你埠驅動程式和使用者模式顯示驅動程式應該針對下列情況執行下列動作：

如需詳細資訊，請參閱使用保證合約 DMA 緩衝區模型) ，在保證的合約 DMA 模式 (中，使用者模式顯示驅動程式必須保證足夠的資源才能進行翻譯命令。如果翻譯沒有足夠的資源存在，則顯示迷你埠驅動程序必須拒絕 DMA 緩衝區。
使用者模式顯示驅動程式應該一律分割可能會轉譯為大於單一 DMA 緩衝區大小的命令，因為顯示迷你埠驅動程式的 DxgkDdiRender 函式無法處理大於 DMA 緩衝區大小且無法分割的單一命令。

DxgkDdiRender 應設為可分頁。

從 Windows 7 開始新增 DxgkDdiRenderKm 函式的支援，適用於支援 GDI 硬體加速的顯示器適配卡。