DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP fonction de rappel (dispmprt.h)

Article
01/07/2025

Un pilote miniport en mode noyau appelle Dxgkrnl's DxgkCbAcquirePostDisplayOwnership routine pour obtenir les informations d’affichage à partir de l’appareil d’affichage auto-test (POST) actuel ou du pilote WDDM en cours d’exécution.

Le pilote doit utiliser ces informations d’affichage pour optimiser la demande de modification du mode initial après le démarrage de l’appareil d’affichage.

Syntaxe

DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP DxgkcbAcquirePostDisplayOwnership;

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

Paramètres

[in] DeviceHandle

Handle qui représente un adaptateur d’affichage. Le kmD a précédemment obtenu ce handle dans le membre DeviceHandle de la structure DXGKRNL_INTERFACE qui a été passée à DxgkDdiStartDevice.

[out] DisplayInfo

Pointeur vers une structure DXGK_DISPLAY_INFORMATION allouée par le KMD. Si DxgkCbAcquirePostDisplayOwnership retourne STATUS_SUCCESS, cette structure contient des informations d’affichage pour l’appareil d’affichage actuel utilisé pour les opérations POST.

Valeur de retour

DxgkCbAcquirePostDisplayOwnership retourne STATUS_SUCCESS si elle réussit. Sinon, elle retourne l’un des codes d’erreur définis dans Ntstatus.h.

Remarques

L’appel de DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP garantit que le pilote initialise correctement les paramètres d’affichage en fonction de la configuration d’affichage actuelle ou la plus récente, en particulier après le démarrage du système, les événements de plug-in d’appareil ou la reprise à partir de la mise en veille prolongée.

Formats de couleurs autorisés

Le membre DisplayInfo->ColorFormat doit inclure une combinaison OR au niveau du bit des deux formats de D3DDDIFORMAT suivants :

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

Si le système d’exploitation renvoie le format D3DDDIFMT_R8G8B8, le KMD doit l’ignorer.

Initialisation de la cible de la vidéo présente

Il est possible que le membre DisplayInfo->TargetId n’est pas initialisé. Dans ce cas, l’identificateur de la cible présente vidéo est D3DDDI_ID_UNINITIALIZED. En règle générale, cette situation se produit après le démarrage d’un système.

De même, il est possible que le membre DisplayInfo->AcpiId n’est pas initialisé. Dans ce cas, l’identificateur ACPI acpiId a la valeur zéro.

Dans le cas d’une mise à niveau de pilote à pilote, le pilote précédent aura fourni l’identificateur cible et l’identificateur ACPI.

Instructions d’implémentation

À compter de WDDM 1.2, le KMD doit suivre ces instructions lorsqu’il appelle DxgkCbAcquirePostDisplayOwnership:

Le point d’entrée de la fonction DxgkCbAcquirePostDisplayOwnership fait partie de la structure DXGKRNL_INTERFACE. Cette structure est retournée au pilote via le paramètre DxgkInterface lorsque la fonction DxgkDdiStartDevice du pilote est appelée.
KMD peut éventuellement appeler DxgkCbAcquirePostDisplayOwnership. Toutefois, le système d’exploitation peut toujours appeler la fonctionDxgkKDdiStopDeviceAndReleasePostDisplayOwnership, même si le pilote n’a pas appelé DxgkCbAcquirePostDisplayOwnership, et le pilote doit gérer cet appel de manière appropriée. Si la fonction DxgkDdiStopDeviceAndReleasePostDisplayOwnership du pilote ne s’exécute pas correctement, le système d’exploitation appelle la fonction DxgkDdiStopDevice du pilote.
Le KMD peut appeler DxgkCbAcquirePostDisplayOwnership si l’appareil est démarré en réponse à un événement Plug-and-Play (PnP). Dans ce cas, le pilote doit appeler DxgkCbAcquirePostDisplayOwnership à partir du contexte de l’appel à la fonction DxgkDdiStartDevice.
Le KMD peut appeler DxgkCbAcquirePostDisplayOwnership si l’appareil reprend un état d’alimentation PowerDeviceD0 après un état de veille prolongée. Dans ce cas, le pilote doit appeler DxgkCbAcquirePostDisplayOwnership à partir du contexte de l’appel à la fonction DxgkDdiSetPowerState.
Le KMD doit uniquement appeler la fonction DxgkCbAcquirePostDisplayOwnership si elle exécute au moins Windows 8. Le kmD peut appeler RtlGetVersion pour déterminer la version du système d’exploitation.
DxgkCbAcquirePostDisplayOwnership peut retourner une structure DXGK_DISPLAY_INFORMATION avec le membre Width défini sur zéro. Cette valeur indique que l’appareil d’affichage actuel n’est pas capable d’opérations POST ou que le système d’exploitation n’a pas les informations d’affichage actuelles pour l’appareil POST actuel.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 8 (WDDM 1.2)
serveur minimum pris en charge	Windows Server 2012
plateforme cible	Bureau
d’en-tête	dispmprt.h (include Dispmprt.h)
IRQL	<= APC_LEVEL