PFND3DDDI_RENDERCB回呼函式 (d3dumddi.h)

發行項
02/25/2024

pfnRenderCb 函式會提交目前的命令緩衝區，以便轉譯至顯示迷你埠驅動程式。

語法

PFND3DDDI_RENDERCB Pfnd3dddiRendercb;

HRESULT Pfnd3dddiRendercb(
  HANDLE hDevice,
  D3DDDICB_RENDER *unnamedParam2
)
{...}

參數

hDevice

顯示裝置的句柄 (圖形內容) 。

unnamedParam2

pData [in， out]

描述要呈現之目前命令緩衝區之D3DDDICB_RENDER 結構的指標。

傳回值

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

傳回碼	描述
S_OK	已成功轉譯命令緩衝區。
D3DDDIERR_PRIVILEGEDINSTRUCTION	顯示迷你埠驅動程式在命令緩衝區中偵測到特殊許可權指令;特殊許可權指令不能出現在命令緩衝區中。
D3DDDIERR_ILLEGALINSTRUCTION	顯示迷你埠驅動程式偵測到圖形硬體不支援的指示。
D3DDDIERR_INVALIDHANDLE	顯示迷你埠驅動程式偵測到命令緩衝區中的無效句柄。
D3DDDIERR_CANTRENDERLOCKEDALLOCATION	視訊記憶體管理員偵測到配置清單中的鎖定配置參考。請注意，只有當視訊記憶體管理員無法將配置重新定位至 AGP 或系統記憶體區段時，才會傳回此錯誤。
D3DDDIERR_INVALIDUSERBUFFER	顯示迷你埠驅動程序偵測到數據或指令不足或溢出。也就是說，驅動程式收到的指令或數據比預期還少。
E_OUTOFMEMORY	pfnRenderCb 因為記憶體不足而無法完成。
E_INVALIDARG	已驗證參數，並判斷為不正確。

此函式也可能傳回其他 HRESULT 值。

備註

當使用者模式顯示驅動程式必須提交目前的命令緩衝區以轉譯至顯示迷你埠驅動程式 (例如，在呼叫使用者模式顯示驅動程式的 Flush 或 Flush (D3D10) 函式) 時，使用者模式顯示驅動程式必須呼叫 pfnRenderCb 函式。使用者模式顯示驅動程式應該將 hDevice 參數設定為 CreateDevice 或 CreateDevice (D3D10) 呼叫期間提供的 Microsoft Direct3DD 運行時間值。在 pData 參數所指向的D3DDDICB_RENDER結構中，使用者模式顯示驅動程式也應該設定：

CommandLength 成員到從位移零開始之命令緩衝區中的命令位元元組數目。
如果使用者模式顯示驅動程式必須指定命令緩衝區中第一個硬體命令的位移， CommandOffset 成員為非零。
配置清單中的元素數目的 NumAllocations 成員。
NumPatchLocations 成員到修補程式位置清單中的元素數目。

呼叫 pfnRenderCb 之後，使用者模式顯示驅動程式必須從 pNewCommandBuffer 和 NewCommandBufferSizeD3DDDICB_RENDER 傳回的值，判斷它應該用於下一個提交的命令緩衝區基位址和大小。同樣地，驅動程式必須分別從 pNewAllocationList 和 NewAllocationListSize 成員和 pNewPatchLocationListSize 成員和 NewPatchLocationListSize 成員中傳回的值，判斷下一個配置清單和修補程式位置清單的基地址和專案數目。

如果使用者模式顯示驅動程式偵測到大部分的命令緩衝區排清是因為驅動程式在命令緩衝區、配置清單或修補程式位置清單中用盡空間，則驅動程式可以要求他們重設大小。若要調整命令緩衝區的大小，驅動程式會在 D3DDDICB_RENDER 的 Flags 成員中設定 ResizeCommandBuffer 位字段旗標，並將要求的大小放在 D3DDDICB_RENDER 的 NewCommandBufferSize 成員中。同樣地，若要調整配置清單的大小，驅動程式會在 D3DDDICB_RENDER 的 Flags 成員中設定 ResizeAllocationList 位字段旗標，並將要求的元素數目放在 D3DDDICB_RENDER 的 NewAllocationListSize 成員中。若要調整修補程式位置清單的大小，驅動程式會在 D3DDDICB_RENDER 的 Flags 成員中設定 ResizePatchLocationList 位字段旗標，並將要求的元素數目放在 D3DDDICB_RENDER 的 NewPatchLocationListSize 成員中。

注意即使驅動程式可以要求命令緩衝區和配置和修補程式位置清單重設大小，視訊記憶體管理員可能無法符合。因此，不論 pfnRenderCb 的呼叫是否成功，驅動程式都應該確認 在 NewCommandBufferSize、 NewAllocationListSize 和 NewPatchLocationListSize D3DDDICB_RENDER 成員中傳回的值。

如果使用者模式顯示驅動程式將 pData 參數指向之D3DDDICB_RENDER結構的 hContext 成員設定為 NULL，Microsoft Direct3D 運行時間會將轉譯作業傳送至裝置的預設內容。如果使用者模式顯示驅動程式將 hContext 設定為 pfnCreateContextCb 函式先前傳回且代表裝置內容的有效句柄，Direct3D 運行時間會將轉譯作業傳送至該內容。 Direct3D 版本 11 附注： 如需驅動程式如何呼叫 pfnRenderCb 的詳細資訊，請參閱 Direct3D 10 的變更。

範例

下列程式代碼範例示範如何提交目前的命令緩衝區，以轉譯至顯示迷你埠驅動程式。此程式代碼範例會在產生命令緩衝區和修補程式清單之後產生配置清單。這不適用於效能，因為命令緩衝區已剖析超過必要。不過，這個實作更容易顯示。在生產驅動程式中，與配置和修補程式清單同時產生命令緩衝區更有效率。

VOID CD3DContext::SubmitDXVABuffer(DWORD Size) {
    D3DDDICB_RENDER     renderCBData = {0};
    DWORD               dwAllocationListUsed;
    HRESULT             hr;

    if (GenerateAllocationListFromCmdBuf(R200UpdateQSParamsForDXVASubmit(m_pR200Ctx, Size), m_sContexts[MULTI_ENGINE_NODE_VIDEO].pHwCmdBufAllocList, m_dwHwCmdBufAllocListSize, &dwAllocationListUsed) == FALSE)
    {
        DBG_BREAK;
        return;
    }

    // 3-D and video packets must be in sync. If the last packet that was sent went to 
    // the 3-D engine, that packet must finish before the new packet runs on the hardware.

    renderCBData.CommandOffset  = 0;
    renderCBData.CommandLength  = Size + sizeof(UMD_CMDBUF_INFO);
    renderCBData.NumAllocations = dwAllocationListUsed;
    renderCBData.hContext = m_sContexts[MULTI_ENGINE_NODE_VIDEO].hContext;

    // Copy command-buffer data from the internal buffer to the buffer that was created by dxgkrnl
    memcpy(m_sContexts[MULTI_ENGINE_NODE_VIDEO].pHwCmdBuf, m_pHwCmdBuf + GetCmdBufPreambleSize(m_pR200Ctx), renderCBData.CommandLength);
 
    m_d3dCallbacks.pfnRenderCb(m_hD3D, &renderCBData);

        // Makes video the last engine that work was submitted to
        m_LastEngineSubmit = MULTI_ENGINE_NODE_VIDEO;
    }

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 作業系統中使用。
目標平台	桌面
標頭	d3dumddi.h (include D3dumddi.h)