PFND3DDDI_RENDERCB função de retorno de chamada (d3dumddi.h)

Artigo
02/06/2025

A função pfnRenderCb envia o buffer de comando atual para renderização para o driver de miniporto de exibição.

Sintaxe

PFND3DDDI_RENDERCB Pfnd3dddiRendercb;

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

Parâmetros

hDevice

Um identificador para o dispositivo de exibição (contexto gráfico).

unnamedParam2

pData [dentro, fora]

Um ponteiro para uma estrutura D3DDDICB_RENDER que descreve o buffer de comando atual a ser renderizado.

Valor de retorno

pfnRenderCb retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	O buffer de comando foi renderizado com êxito.
D3DDDIERR_PRIVILEGEDINSTRUCTION	O driver de miniporto de exibição detectou uma instrução privilegiada no buffer de comando; instruções privilegiadas não podem estar presentes em um buffer de comando.
D3DDDIERR_ILLEGALINSTRUCTION	O driver de miniporto de exibição detectou instruções que o hardware gráfico não pode dar suporte.
D3DDDIERR_INVALIDHANDLE	O driver de miniporto de exibição detectou um identificador inválido no buffer de comando.
D3DDDIERR_CANTRENDERLOCKEDALLOCATION	O gerenciador de memória de vídeo detectou referências a uma alocação bloqueada na lista de alocação. Observe que o gerenciador de memória de vídeo retorna esse erro somente se não puder reposicionar a alocação para um AGP ou segmento de memória do sistema.
D3DDDIERR_INVALIDUSERBUFFER	O driver de miniporto de exibição detectou uma subexecução ou sobrecarga de dados ou instruções. Ou seja, o driver recebeu menos ou mais instruções ou dados do que o esperado.
E_OUTOFMEMORY	pfnRenderCb não pôde ser concluído devido à memória insuficiente.
E_INVALIDARG	Os parâmetros foram validados e determinados como incorretos.

Essa função também pode retornar outros valores HRESULT.

Observações

Quando o driver de exibição do modo de usuário deve enviar o buffer de comando atual para renderização para o driver de miniporto de exibição (por exemplo, durante uma chamada para a função Flush ou Flush(D3D10) do driver de exibição no modo de usuário), o driver de exibição no modo de usuário deve chamar a função pfnRenderCb. O driver de exibição do modo de usuário deve definir o parâmetro hDevice para o valor fornecido pelo runtime do Microsoft Direct3D durante a chamada CreateDevice ou CreateDevice(D3D10). Na estrutura D3DDDICB_RENDER que é apontada pelo parâmetro pData , o driver de exibição no modo de usuário também deve definir:

O CommandLength membro para o número de bytes de comandos no buffer de comando que começam do deslocamento zero.
O CommandOffset membro para não zero se o driver de exibição do modo de usuário precisar especificar um deslocamento para o primeiro comando de hardware no buffer de comando.
O NumAllocations membro ao número de elementos na lista de alocação.
O NumPatchLocations membro ao número de elementos na lista de locais de patch.

Após uma chamada para pfnRenderCb, o driver de exibição no modo de usuário deve determinar o endereço base e o tamanho do buffer de comando que ele deve usar para o próximo envio dos valores retornados no pNewCommandBuffer e NewCommandBufferSize membros do D3DDDICB_RENDER. Da mesma forma, o driver deve determinar o endereço base e o número de elementos da próxima lista de alocação e da lista de locais de patch dos valores retornados no pNewAllocationList e membros newAllocationListSize e pNewPatchLocationList e membros newpatchLocationListSize, respectivamente.

Se o driver de exibição do modo de usuário detectar que a maioria das liberações do buffer de comando é porque o driver fica sem espaço no buffer de comandos, na lista de alocação ou na lista de locais de patch, o driver pode solicitar que eles sejam redimensionados. Para redimensionar o buffer de comando, o driver define o sinalizador ResizeCommandBuffer de campo de bits no Flags membro do D3DDDICB_RENDER e coloca o tamanho solicitado no membro NewCommandBufferSize do D3DDDICB_RENDER. Da mesma forma, para redimensionar a lista de alocação, o driver define o ResizeAllocationList sinalizador de campo de bits no Flags membro do D3DDDICB_RENDER e coloca o número solicitado de elementos no NewAllocationListSize membro do D3DDDICB_RENDER. Para redimensionar a lista de locais de patch, o driver define o ResizePatchLocationList sinalizador de campo de bit no Flags membro do D3DDDICB_RENDER e coloca o número solicitado de elementos no NewPatchLocationListSize membro do D3DDDICB_RENDER.

Observação Embora o driver possa solicitar que o buffer de comando e as listas de alocação e local do patch sejam redimensionados, o gerenciador de memória de vídeo pode não ser capaz de cumprir. Portanto, independentemente de a chamada para pfnRenderCb for bem-sucedida, o driver deve verificar os valores retornados no NewCommandBufferSize, NewAllocationListSizee NewPatchLocationListSize membros do D3DDDICB_RENDER.

Se o driver de exibição do modo de usuário definir o hContext membro da estrutura D3DDDICB_RENDER apontada pelo parâmetro pData para NULL, o runtime do Microsoft Direct3D enviará a operação de renderização para o contexto padrão do dispositivo. Se o driver de exibição do modo de usuário definir hContext para um identificador válido que a função pfnCreateContextCb retornada anteriormente e que representa um contexto de dispositivo, o runtime do Direct3D enviará a operação de renderização para esse contexto. Direct3D Versão 11 Observação: Para obter mais informações sobre como o driver chama pfnRenderCb, consulte Alterações do Direct3D 10.

Exemplos

O exemplo de código a seguir mostra como enviar o buffer de comando atual para renderização para o driver de miniporto de exibição. Este exemplo de código gera a lista de alocação depois que o buffer de comandos e a lista de patch são gerados. Isso não é ideal para o desempenho porque o buffer de comando é analisado mais do que o necessário. No entanto, essa implementação é mais fácil de mostrar. Em um driver de produção, gerar o buffer de comando ao mesmo tempo que as listas de alocação e patch é mais eficiente.

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
da Plataforma de Destino	Área de trabalho
cabeçalho	d3dumddi.h (inclua D3dumddi.h)