PFND3DDDI_RENDERCB funzione di callback (d3dumddi.h)

Articolo
02/06/2025

La funzione pfnRenderCb invia il buffer dei comandi corrente per il rendering al driver miniport di visualizzazione.

Sintassi

PFND3DDDI_RENDERCB Pfnd3dddiRendercb;

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

Parametri

hDevice

Handle per il dispositivo di visualizzazione (contesto grafico).

unnamedParam2

pData [in, out]

Puntatore a una struttura D3DDDICB_RENDER che descrive il buffer dei comandi corrente da eseguire per il rendering.

Valore restituito

pfnRenderCb restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	Il rendering del buffer dei comandi è stato eseguito correttamente.
D3DDDIERR_PRIVILEGEDINSTRUCTION	Il driver miniport di visualizzazione ha rilevato un'istruzione con privilegi nel buffer dei comandi; Le istruzioni con privilegi non possono essere presenti in un buffer dei comandi.
D3DDDIERR_ILLEGALINSTRUCTION	Il driver miniport di visualizzazione ha rilevato istruzioni che l'hardware grafico non può supportare.
D3DDDIERR_INVALIDHANDLE	Il driver miniport di visualizzazione ha rilevato un handle non valido nel buffer dei comandi.
D3DDDIERR_CANTRENDERLOCKEDALLOCATION	Gestione memoria video ha rilevato riferimenti a un'allocazione bloccata nell'elenco di allocazioni. Si noti che la gestione memoria video restituisce questo errore solo se non è stato possibile riposizionare l'allocazione in un segmento di memoria di sistema o AGP.
D3DDDIERR_INVALIDUSERBUFFER	Il driver miniport di visualizzazione ha rilevato un sovraccarico o un sovraccarico di dati o istruzioni. Ovvero, il driver ha ricevuto meno o più istruzioni o dati del previsto.
E_OUTOFMEMORY	PfnRenderCb non è riuscito a completare a causa di memoria insufficiente.
E_INVALIDARG	I parametri sono stati convalidati e sono stati determinati in modo che non siano corretti.

Questa funzione potrebbe restituire anche altri valori HRESULT.

Osservazioni

Quando il driver di visualizzazione in modalità utente deve inviare il buffer dei comandi corrente per il rendering al driver miniport di visualizzazione (ad esempio, durante una chiamata alla funzione del driver di visualizzazione in modalità utente Scarica o Flush(D3D10), il driver di visualizzazione in modalità utente deve chiamare la funzione pfnRenderCb. Il driver di visualizzazione in modalità utente deve impostare il parametro hDevice sul valore fornito dal runtime di Microsoft Direct3D durante la chiamata CreateDevice o CreateDevice(D3D10). Nella struttura D3DDDICB_RENDER a cui fa riferimento il parametro pData è necessario impostare anche il driver di visualizzazione in modalità utente:

Il CommandLength membro al numero di byte di comandi nel buffer dei comandi che iniziano dall'offset zero.
Il CommandOffset membro a diverso da zero se il driver di visualizzazione in modalità utente deve specificare un offset al primo comando hardware nel buffer dei comandi.
Il NumAllocations membro al numero di elementi nell'elenco di allocazione.
Il NumPatchLocations membro al numero di elementi nell'elenco di percorsi patch.

Dopo una chiamata a pfnRenderCb, il driver di visualizzazione in modalità utente deve determinare l'indirizzo di base e le dimensioni del buffer di comando che deve usare per il successivo invio dai valori restituiti nel pNewCommandBuffer e NewCommandBufferSize membri di D3DDDICB_RENDER. Analogamente, il driver deve determinare l'indirizzo di base e il numero di elementi dell'elenco di allocazione successivo e dell'elenco di posizioni patch dai valori restituiti rispettivamente nei pNewAllocationList e Membri newAllocationListSize e pNewPatchLocationList e membri NewPatchLocationListSize.

Se il driver di visualizzazione in modalità utente rileva che la maggior parte degli scaricamenti del buffer dei comandi è dovuta al fatto che il driver esaurisce lo spazio nel buffer dei comandi, nell'elenco di allocazioni o nell'elenco di percorsi patch, il driver può richiedere il ridimensionamento. Per ridimensionare il buffer dei comandi, il driver imposta l'ResizeCommandBuffer flag di campo di bit nel membro flag di D3DDDICB_RENDER e inserisce le dimensioni richieste nel membro NewCommandBufferSize di D3DDDICB_RENDER. Analogamente, per ridimensionare l'elenco di allocazioni, il driver imposta l'ResizeAllocationList flag di campo di bit nel membro flag di D3DDDICB_RENDER e inserisce il numero richiesto di elementi nel membro NewAllocationListSize di D3DDDICB_RENDER. Per ridimensionare l'elenco di percorsi patch, il driver imposta il flag ResizePatchLocationList bit-field nel membro flag di D3DDDICB_RENDER e inserisce il numero richiesto di elementi nel membro NewPatchLocationListSize del D3DDDICB_RENDER.

Nota Anche se il driver può richiedere che il buffer dei comandi e gli elenchi di allocazione e posizione patch vengano ridimensionati, la gestione della memoria video potrebbe non essere in grado di conformarsi. Pertanto, indipendentemente dal fatto che la chiamata a pfnRenderCb abbia esito positivo, il driver deve verificare i valori restituiti nel NewCommandBufferSize, NewAllocationListSizee NewPatchLocationListSize membri di D3DDDICB_RENDER.

Se il driver di visualizzazione in modalità utente imposta il membro hContext della struttura D3DDDICB_RENDER a cui punta il parametro pData su NULL, il runtime Di Microsoft Direct3D invia l'operazione di rendering al contesto predefinito del dispositivo. Se il driver di visualizzazione in modalità utente imposta hContext su un handle valido che la funzione pfnCreateContextCb restituita in precedenza e che rappresenta un contesto di dispositivo, il runtime Direct3D invia l'operazione di rendering a tale contesto. Direct3D versione 11 Nota: Per altre informazioni su come il driver chiama pfnRenderCb, vedere modifiche da Direct3D 10.

Esempi

Nell'esempio di codice seguente viene illustrato come inviare il buffer dei comandi corrente per il rendering al driver miniport di visualizzazione. Questo esempio di codice genera l'elenco di allocazioni dopo la generazione del buffer dei comandi e dell'elenco di patch. Ciò non è ottimale per le prestazioni perché il buffer dei comandi viene analizzato più del necessario. Tuttavia, questa implementazione è più semplice da mostrare. In un driver di produzione, la generazione del buffer dei comandi contemporaneamente all'allocazione e agli elenchi di patch è più efficiente.

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;
    }

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
piattaforma di destinazione	Desktop
intestazione	d3dumddi.h (include D3dumddi.h)