DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP função de retorno de chamada (dispmprt.h)

Artigo
01/07/2025

Um KMD (driver de miniporto de exibição) no modo kernel chama DxgkrnlDxgkCbAcquirePostDisplayOwnership rotina para obter as informações de exibição do dispositivo de exibição post (auto-teste) do power-on atual ou do driver WDDM anteriormente em execução.

O driver deve usar essas informações de exibição para otimizar a solicitação de alteração de modo inicial depois que o dispositivo de exibição tiver sido iniciado.

Sintaxe

DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP DxgkcbAcquirePostDisplayOwnership;

NTSTATUS DxgkcbAcquirePostDisplayOwnership(
  [in]  HANDLE DeviceHandle,
  [out] PDXGK_DISPLAY_INFORMATION DisplayInfo
)
{...}

Parâmetros

[in] DeviceHandle

Um identificador que representa um adaptador de exibição. O KMD obteve anteriormente esse identificador no DeviceHandle membro da estrutura DXGKRNL_INTERFACE que foi passada para DxgkDdiStartDevice.

[out] DisplayInfo

Ponteiro para uma estrutura DXGK_DISPLAY_INFORMATION alocada pelo KMD. Se DxgkCbAcquirePostDisplayOwnership retornar STATUS_SUCCESS, essa estrutura conterá informações de exibição para o dispositivo de exibição atual usado para operações POST.

Valor de retorno

DxgkCbAcquirePostDisplayOwnership retornará STATUS_SUCCESS se tiver êxito. Caso contrário, ele retornará um dos códigos de erro definidos em Ntstatus.h.

Observações

Chamar DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP garante que o driver inicialize corretamente as configurações de exibição com base na configuração de exibição atual ou mais recente, especialmente após a inicialização do sistema, eventos de plug-in do dispositivo ou retomada da hibernação.

Formatos de cor permitidos

O membro DisplayInfo-ColorFormat deve incluir uma combinação bit a bit OR dos dois seguintes formatos de D3DDDIFORMAT:

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

Se o sistema operacional relatar o formato D3DDDIFMT_R8G8B8, o KMD deverá ignorá-lo.

Inicialização de destino de apresentação de vídeo

É possível que o membro DisplayInfo-TargetId não seja inicializado. Nesse caso, o identificador do destino presente do vídeo é D3DDDI_ID_UNINITIALIZED. Normalmente, essa situação ocorre após uma inicialização do sistema.

Da mesma forma, é possível que o membro DisplayInfo-AcpiId não seja inicializado. Nesse caso, o identificador acpi AcpiId tem um valor igual a zero.

No caso de uma atualização de driver para driver, o driver anterior terá fornecido o identificador de destino e o identificador de ACPI.

Diretrizes de implementação

A partir do WDDM 1.2, o KMD deve seguir estas diretrizes quando chama DxgkCbAcquirePostDisplayOwnership:

O ponto de entrada da função DxgkCbAcquirePostDisplayOwnership faz parte da estrutura DXGKRNL_INTERFACE. Essa estrutura é retornada ao driver por meio do parâmetro DxgkInterface quando a função de DxgkDdiStartDevice do do driver é chamada.
O KMD pode, opcionalmente, chamar DxgkCbAcquirePostDisplayOwnership. No entanto, o sistema operacional ainda pode chamar a funçãoDxgkDdiStopDeviceAndReleasePostDisplayOwnership do KMD, mesmo que o driver não tenha chamado anteriormente DxgkCbAcquirePostDisplayOwnership, e o driver deve lidar com essa chamada adequadamente. Se a função DxgkDdiStopDeviceAndReleasePostDisplayOwnership do driver não for concluída com êxito, o sistema operacional chamará a função de DxgkDdiStopDevice do driver.
O KMD pode chamar DxgkCbAcquirePostDisplayOwnership se o dispositivo for iniciado em resposta a um evento plug and play (PnP). Nesse caso, o driver deve chamar DxgkCbAcquirePostDisplayOwnership de dentro do contexto da chamada para a função DxgkDdiStartDevice .
O KMD poderá chamar DxgkCbAcquirePostDisplayOwnership se o dispositivo retomar um PowerDeviceD0 estado de energia após um estado de hibernação. Nesse caso, o driver deve chamar DxgkCbAcquirePostDisplayOwnership de dentro do contexto da chamada para a função DxgkDdiSetPowerState .
O KMD só deve chamar a função DxgkCbAcquirePostDisplayOwnership se estiver executando pelo menos o Windows 8. O KMD pode chamar rtlGetVersion para determinar a versão do sistema operacional.
DxgkCbAcquirePostDisplayOwnership pode retornar uma estrutura de DXGK_DISPLAY_INFORMATION com o membro Width definido como zero. Esse valor indica que o dispositivo de exibição atual não é capaz de operações POST ou o sistema operacional não tem as informações de exibição atuais para o dispositivo POST atual.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 8 (WDDM 1.2)
servidor com suporte mínimo	Windows Server 2012
da Plataforma de Destino	Área de trabalho
cabeçalho	dispmprt.h (inclua Dispmprt.h)
IRQL	<= APC_LEVEL