DXGKDDI_PRESENT função de retorno de chamada (d3dkmddi.h)

Artigo
02/27/2024

A função DxgkDdiPresent copia o conteúdo das alocações de origem para uma superfície primária (e às vezes para alocações de memória do sistema fora da tela).

Sintaxe

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Parâmetros

[in] hContext

Um identificador para o contexto do dispositivo para as informações de cópia. A função DxgkDdiCreateContext do driver de miniporta de exibição retornou anteriormente esse identificador no membro hContext da estrutura DXGKARG_CREATECONTEXT para a qual o parâmetro pCreateContext de DxgkDdiCreateContext aponta.

Se o driver não der suporte à criação de contexto, o subsistema de kernel de elementos gráficos do Microsoft DirectX substituirá o identificador para o contexto por um identificador para o dispositivo. A função DxgkDdiCreateDevice do driver de miniporta de vídeo retornou anteriormente o identificador do dispositivo no membro hDevice da estrutura DXGKARG_CREATEDEVICE para a qual o parâmetro pCreateDevice de DxgkDdiCreateDevice aponta.

[in/out] pPresent

Um ponteiro para uma estrutura DXGKARG_PRESENT que contém informações sobre a operação de cópia.

Retornar valor

DxgkDdiPresent retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	DxgkDdiPresent copiou o conteúdo com êxito.
STATUS_NO_MEMORY ou STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent não pôde alocar a memória necessária para que ela fosse concluída.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	O buffer de DMA (acesso direto à memória) atual está esgotado.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	O driver de miniporta de exibição detectou uma transferência de bit block (bitblt) para conversão de cores que o dispositivo não pôde executar. O runtime do Microsoft Direct3D impede que o aplicativo continue e o aplicativo recebe uma falha ao copiar conteúdo.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent detectou instruções não privilegiadas (ou seja, instruções que acessam a memória além do privilégio do processo atual da unidade de processamento central [CPU]).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent detectou instruções para as quais o hardware gráfico não pode dar suporte.
STATUS_INVALID_HANDLE	DxgkDdiPresent detectou um identificador inválido no buffer de comando.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	O driver de miniporta de exibição detectou um erro no fluxo de DMA. O dispositivo de contexto gráfico será colocado em um estado perdido se o driver retornar esse código de erro.

Comentários

O subsistema de kernel de elementos gráficos DirectX chama a função DxgkDdiPresent do driver de miniporta de exibição para copiar conteúdo de alocações de origem normalmente para a superfície primária. (Essa função também pode copiar conteúdo para uma alocação de memória do sistema fora da tela.) Como uma superfície primária é definida livremente, DxgkDdiPresent pode ser implementado para os seguintes cenários:

Dependendo da posição da janela, a função DxgkDdiPresent deve ser executada em diferentes primárias que podem estar no mesmo adaptador ou em adaptadores diferentes.
O primário está em um monitor remoto e é acessado por meio de um cliente de serviços de terminal ou Microsoft NetMeeting.
Uma opção de modo ocorreu recentemente e o formato primário é diferente do formato de origem, portanto, uma conversão de cor é necessária. Além disso, a operação DxgkDdiPresent pode ser recortada devido ao recorte e à ordenação da janela.

Como os cenários anteriores podem ser alterados de forma assíncrona, o driver de exibição do modo de usuário não pode compilar instruções de hardware para a função DxgkDdiPresent do driver de miniporta de exibição com antecedência. O driver de miniporta de exibição deve criar comandos de hardware para a operação DxgkDdiPresent real e eles devem ser colocados em um buffer de DMA de saída. Depois que a função DxgkDdiPresent do driver de miniporta de exibição for chamada para gerar o buffer DMA, o sistema operacional garantirá que uma alteração de cenário não ocorrerá antes que esse buffer seja renderizado.

O driver de miniporto de exibição não precisa estar ciente das especificidades dos cenários anteriores, desde que o driver dê suporte às seguintes abstrações:

Em uma operação de cópia de uma fonte de memória de vídeo para um vídeo primário ou destino de memória do sistema, uma cópia de uma fonte de memória do sistema fora da tela para o destino primário, uma cópia de e para o primário ou uma cópia da origem primária para um destino de memória do sistema fora da tela, a origem é especificada pelo membro hDeviceSpecificAllocation do elemento de matriz pAllocationList[DXGK_PRESENT_SOURCE_INDEX] da estrutura DXGKARG_PRESENT que o pPresent parâmetro de DxgkDdiPresent aponta para. O destino, que é o primário atual do dispositivo ou uma alocação de memória do sistema fora da tela, é especificado pelo membro hDeviceSpecificAllocation do elemento de matriz pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. Se o destino for igual à origem (ou seja, destino == origem), a operação de cópia será uma transferência de bloco de bits de tela para tela (bitblt). Portanto, o subsistema gráfico define a origem e o destino com os seguintes valores:
- destination != NULL (ou seja, destination == nonNULL)
- source != NULL (ou seja, source == nonNULL)
Em uma inversão de memória de vídeo da alocação atual para outra alocação, a origem pode ser especificada pelo sistema operacional e definida no membro hDeviceSpecificAllocation do elemento de matriz pAllocationList[DXGK_PRESENT_SOURCE_INDEX] de DXGKARG_PRESENT. O subsistema gráfico define a origem e o destino com os seguintes valores:
- destination == NULL
- source != NULL (ou seja, source == nonNULL)
Nota Uma inversão sem operações pode ser executada da mesma alocação de origem que a alocação verificada no momento. Uma inversão sem operações é usada para inserir uma espera enfileirada por um espaço em branco vertical no fluxo de renderização. O driver de miniporta de exibição deve inserir um comando de inversão de hardware como se estivesse invertendo para outra alocação.
Em uma operação de preenchimento de cores para a superfície primária, nenhuma alocação de origem é necessária e o destino é um identificador de alocação primário especificado pelo membro hDeviceSpecificAllocation do elemento de matriz pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. O membro Color do DXGKARG_PRESENT normalmente está no formato D3DDDIFMT_A8R8G8B8 do tipo de enumeração D3DDDIFORMAT . No entanto, quando o formato primário é palettizado RGB, Color contém o índice de paleta. Portanto, o subsistema gráfico define a origem e o destino com os seguintes valores:
- destination != NULL (ou seja, destination == nonNULL)
- source == NULL

Para que todos os cenários DxgkDdiPresent operem corretamente, a função DxgkDdiCreateDevice do driver de miniporta de exibição deve definir o membro DmaBufferSize da estrutura DXGK_DEVICEINFO como grande o suficiente para manter os comandos de hardware necessários para apresentar pelo menos um retângulo RECT para o destino de exibição ou fora da tela. No entanto, a função DxgkDdiPresent do driver poderá retornar STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER se o número de subrectangles no cenário DxgkDdiPresent esgotar o buffer DMA atual e o driver exigir que outro buffer de DMA continue.

Em seguida, o subsistema gráfico adquire um novo buffer DMA e chama a função DxgkDdiPresent do driver novamente com a mesma lista de estruturas RECT que a chamada DxgkDdiPresent anterior. O driver deve usar o membro MultipassOffset da estrutura DXGKARG_PRESENT apontada por pPresent para registrar a quantidade de progresso feita na conclusão da lista RECT na chamada anterior para DxgkDdiPresent para que o driver possa continuar de onde parou com o novo buffer de DMA. Quando a função DxgkDdiPresent do driver conclui a lista de estruturas RECT, ela retorna STATUS_SUCCESS.

Além de gerar um buffer DMA, o driver de miniporto de exibição deve gerar uma lista de locais de patch que indique os vários deslocamentos dentro do buffer de DMA que devem ser corrigidos posteriormente quando endereços físicos para alocações são conhecidos. Às vezes, o gerenciador de memória de vídeo fornece ao driver informações pré-corrigidas (ou seja, os últimos endereços físicos conhecidos para a origem e o destino) na lista de alocação.

Quando o gerenciador de memória de vídeo fornece essas informações, o driver deve gerar o buffer de DMA determinando que esses endereços físicos são os endereços finais que o subsistema de kernel de elementos gráficos DirectX fornecerá. O subsistema gráfico pode não chamar a função DxgkDdiPatch no buffer de DMA para corrigi-la novamente mais tarde. Portanto, o driver deve usar as informações de pré-patch para gerar o buffer de DMA corretamente. Informações pré-corrigidas são fornecidas para o elemento N quando o membro SegmentId do Nth elemento da matriz pAllocationList de DXGKARG_PRESENT é diferente de zero.

Nota Embora a função DxgkDdiPresent do driver pré-corrija o buffer DMA, o driver ainda deve inserir todas as referências às alocações na lista de locais de patch de saída que o membro pPatchLocationListOut do DXGKARG_PRESENT especifica. O driver deve inserir essas referências porque os endereços das alocações podem ser alterados antes que o buffer de DMA seja enviado para a GPU; Portanto, o subsistema de kernel de elementos gráficos DirectX chamará a função DxgkDdiPatch para recompensar o buffer de DMA.

Se o driver der suporte à rotação (ou seja, relatar suporte para modos girados no membro RotationSupport da estrutura D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION em uma chamada para sua função DxgkDdiEnumVidPnCofuncModality ), o driver deverá ser capaz de executar transferências de bit-block giradas (bitblt) da origem para o destino. Quando o sinalizador Girar campo de bits é especificado na estrutura DXGK_PRESENTFLAGS para o membro Flags do DXGKARG_PRESENT, o driver deve aplicar a rotação como se estivesse indo de uma superfície não girada para a orientação final da origem atual.

A alocação primária de uma origem é especificada na função DxgkDdiCommitVidPn . Se vários caminhos forem originados da origem fornecida (modo clone), o driver de miniporto de exibição deverá garantir que as saídas sejam giradas corretamente, considerando o modo de rotação de caminho para os diferentes destinos. Todos os parâmetros fornecidos para DxgkDdiPresent são independentes de rotação. Os retângulos de origem e destino podem ser a tela inteira, pois os clientes a percebem (por exemplo, 768 x 1024).

Nota Essa situação não aborda aplicativos Direct3D de tela inteira no modo girado.

Se o driver de miniporta de exibição tiver sido indicado anteriormente, em uma chamada para sua função DxgkDdiQueryAdapterInfo , que dá suporte a uma inversão baseada em E/S mapeada na memória (MMIO) (definindo o sinalizador de campo de bits FlipOnVSyncMmIo no membro FlipCaps da estrutura DXGK_DRIVERCAPS como TRUE), a função DxgkDdiPresent do driver é chamada posteriormente com o membro pDmaBuffer de DXGKARG_PRESENT definido como NULL porque uma inversão baseada em MMIO não requer um buffer de DMA para ser executado na GPU. Em vez disso, a função DxgkDdiPresent do driver deve validar a superfície de origem e o hardware de inversão do programa, conforme necessário. O subsistema de kernel de elementos gráficos DirectX chama a função DxgkDdiSetVidPnSourceAddress do driver para executar esse tipo de inversão.

DxgkDdiPresent deve ser tornado paginável.