D3DKMTPresent 函式 (d3dkmthk.h)

發行項
02/23/2024

D3DKMTPresent 函式會將目前命令提交至 Microsoft DirectX 圖形核心子系統， (Dxgkrnl.sys) 。

語法

NTSTATUS D3DKMTPresent(
  [in] D3DKMT_PRESENT *unnamedParam1
);

參數

[in] unnamedParam1

pData：描述要呈現之參數 之D3DKMT_PRESENT 結構的指標。

傳回值

D3DKMTPresent 會傳回 NTSTATUS 值，例如下列其中一個值：

傳回碼	描述
STATUS_SUCCESS	已成功執行目前。
STATUS_DEVICE_REMOVED	圖形配接器已停止或顯示內容已重設。
STATUS_INVALID_PARAMETER	已驗證參數，並判斷為不正確。
STATUS_NO_MEMORY	D3DKMTPresent 因為記憶體不足而無法完成。
STATUS_GRAPHICS_ALLOCATION_INVALID	主要表面控點因為顯示模式變更而失效。如果 OpenGL 可安裝用戶端驅動程式 (ICD) 收到此錯誤碼，它應該重新開啟或重新建立主要句柄、以新的句柄取代命令緩衝區中的所有參考，然後重新提交緩衝區。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	轉譯裝置內容發生錯誤，D3DKMT_PRESENT指定的 hContext 成員。

注意

STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE錯誤碼不會指出啟動逾時偵測和復原 (TDR) 進程，或 GPU 停止回應。例如，如果顯示迷你埠驅動程式指出從此裝置提交的 DMA 緩衝區造成錯誤，或視訊記憶體管理員無法分頁處理 DMA 緩衝區的所有配置，即使分割 DMA 緩衝區之後，DirectX 圖形核心子系統仍會將裝置放入錯誤狀態。當裝置處於錯誤狀態之後，就無法再執行任何作業，而且必須終結並重新建立。 ICD 可以呼叫 D3DKMTGetDeviceState 函式來判斷錯誤更精確的原因。

備註

D3DKMTPresent 函式可能會傳回STATUS_INVALID_PARAMETER，視參數值 (的組合而定，也就是 pData 指向 ) D3DKMT_PRESENT 結構成員中的值。下列清單描述可能導致 D3DKMTPresent 傳回STATUS_INVALID PARAMETER 最常見的參數值組合：

hDestination 成員為非 NULL，且下列至少一個條件成立：
- pSrcSubRects 成員為 NULL。
- SubRectCnt 成員為 0。
- 未設定 Flags 成員的 Blt 位欄位旗標。
- 未設定 Flags 的 SrcRectValid 位字段旗標。
- 已設定 Flags 的 ColorFill 位欄位旗標。
- 已設定 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段旗標。
- 已設定 Flags 的 SrcColorKey 或 DstColorKey 位欄位旗標。
- hSource 成員等於 hDestination。
- 來源和目的地不是主要表面。
已設定 Flags 的翻轉位欄位旗標，且下列至少一個條件成立：
- 已設定 Flags 的 ColorFill 位欄位旗標。
- 已設定 Flags 的 Blt 位字段旗標。
- 已設定 Flags 的 SrcColorKey 或 DstColorKey 位欄位旗標。
- 已設定 Flags 的 SrcRectValid 或 DstRectValid 位欄位旗標。
- 已設定 Flags 的旋轉位欄位旗標。
- 已設定 Flags 的 RestrictVidPnSource 位字段旗標。
- 來源不是主要表面。
- 顯示迷你埠驅動程式不支援 FlipInterval 成員指定的翻轉間隔。
- 先前未呼叫 D3DKMTSetDisplayMode 函式。
已設定 Flags 的 ColorFill 位字段旗標，且下列其中一個條件成立：
- pSrcSubRects 為 NULL。
- SubRectCnt 為 0。
- 已設定 Flags 的 Blt 位字段旗標。
- 已設定 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段旗標。
- 已設定 Flags 的 SrcColorKey 或 DstColorKey 位欄位旗標。
- 已設定 Flags 的 SrcRectValid 位字段旗標。
已設定 Flags 的 Blt 位字段旗標，且下列其中一個條件成立：
- pSrcSubRects 為 NULL。
- SubRectCnt 為 0。
- 已設定 Flags 的 ColorFill 位欄位旗標。
- 已設定 Flags 的 Flip、FlipDoNotFlip、FlipDoNotWait 或 FlipRestart 位字段旗標。

呼叫 D3DKMTPresent 來呈現 blit 樣式的使用者模式圖形驅動程式，且已設定 Flags 的 Blt 位字段旗標，必須特別小心，以確保所有先前提交的工作都會呈現至內容， (呈現的來源) 完全可清空。若無法這麼做，可能會導致應用程式自行死結，或在某些情況下，使目前的使用者桌面死結。如果內容只包含 GPU 同步處理物件的等候，其中對應的訊號已排入 GPU 排程器資料庫，且該訊號本身不在另一個無法讀取的等候後方，則內容會完全清空。換句話說，如果系統中所有進程的用戶空間在呼叫 D3DKMTPresent 之後立即暫停，當相依轉譯鏈結已排入 GPU 排程器的佇列完成轉譯之後，就會滿足等候。驅動程序絕對不能在相依於 GPU 等候的內容上呼叫 blit，該等候目前未滿足，而且預期會由來自此或其他進程的一些後續作業滿足。

範例

下列程式代碼範例示範 OpenGL ICD 如何使用 D3DKMTPresent 來呈現數據。

HRESULT Present(D3DKMT_HANDLE hDevice, 
                HWND hWnd, 
                RECT* pSrcRect,
                 RECT* pDstRect)
{
    D3DKMT_PRESENT PresentData = {0};

    PresentData.hDevice = hDevice;
    PresentData.Flags.Blt = 
    PresentData.Flags.DstRectValid = 
    PresentData.Flags.SrcRectValid = TRUE;
    PresentData.hWindow = hWnd;
    PresentData.DstRect = *pDstRect;
    PresentData.SrcRect = *pSrcRect;
    PresentData.SubRectCnt = 1;  
    PresentData.pSrcSubRects = pSrcRect; 

    if (NT_SUCCESS((*pfnKTPresent)(&PresentData))) {
        return S_OK;
    }
    return E_FAIL;
}