DXGKDDI_SYSTEM_DISPLAY_ENABLE fonction de rappel (dispmprt.h)

Article
08/07/2023

Appelé par le système d’exploitation pour demander au pilote de miniport d’affichage de réinitialiser le périphérique d’affichage actuel à un état spécifié.

À compter de Windows 8, le système d’exploitation appelle cette fonction lors d’une opération de vérification de bogue suite à une erreur d’arrêt du système.

Syntaxe

DXGKDDI_SYSTEM_DISPLAY_ENABLE DxgkddiSystemDisplayEnable;

NTSTATUS DxgkddiSystemDisplayEnable(
  [in]  PVOID MiniportDeviceContext,
  [in]  D3DDDI_VIDEO_PRESENT_TARGET_ID TargetId,
  [in]  PDXGKARG_SYSTEM_DISPLAY_ENABLE_FLAGS Flags,
  [out] UINT *Width,
  [out] UINT *Height,
  [out] D3DDDIFORMAT *ColorFormat
)
{...}

Paramètres

[in] MiniportDeviceContext

Handle d’un bloc de contexte associé à une carte d’affichage. La fonction DxgkDdiAddDevice du pilote miniport d’affichage fournissait précédemment cette poignée au sous-système du noyau graphique Microsoft DirectX.

[in] TargetId

Valeur D3DDDI_VIDEO_PRESENT_TARGET_ID qui spécifie l’identificateur de la cible vidéo présente sur l’adaptateur d’affichage auquel le périphérique d’affichage est connecté. Cet identificateur peut concerner la cible qui était restée dans l’état actuel du réseau vidéo présent (VidPn) lors de l’appel précédent à DxgkDdiCommitVidPn.

Pour plus d’informations sur l’utilisation du paramètre TargetId , consultez la section suivante « Initialisation de la cible de présentation vidéo ».

[in] Flags

Pointeur vers une valeur qui contient un OR au niveau du bit d’indicateurs. Ce membre est réservé par le système d’exploitation.

[out] Width

Valeur UINT qui spécifie la largeur du mode d’affichage de l’appareil spécifié en unités de pixels.

[out] Height

Valeur UINT qui spécifie la hauteur du mode d’affichage de l’appareil spécifié en unités de pixels.

[out] ColorFormat

Pointeur vers une valeur D3DDDIFORMAT qui spécifie le format de couleur de l’appareil d’affichage.

Valeur retournée

DxgkDdiSystemDisplayEnable retourne STATUS_SUCCESS si elle réussit. Si la cible spécifiée par le paramètre TargetId n’est pas connectée à un périphérique d’affichage, la fonction retourne STATUS_NOT_SUPPORTED. Sinon, il retourne l’un des codes d’erreur définis dans Ntstatus.h.

Remarques

Étapes requises par le pilote miniport d’affichage

Le pilote miniport d’affichage doit suivre ces étapes lorsque sa fonction DxgkDdiSystemDisplayEnable est appelée :

Le pilote doit annuler toutes les opérations d’unité de traitement graphique (GPU) ou réinitialiser le GPU à l’état inactif.
Le système d’exploitation indique la cible actuelle de la vidéo via le paramètre TargetId . Le pilote doit conserver l’affichage associé à cette cible sous tension et visible. Si le pilote ne peut pas allumer l’affichage, l’appel à cette fonction doit échouer. Dans un tel cas de défaillance, le système d’exploitation peut appeler la fonction DxgkDdiResetDevice et provoquer une vérification de bogue système.
Le pilote doit case activée la connectivité de l’affichage associé à cette cible. Si l’affichage de la cible n’est pas connecté, le pilote doit terminer l’appel à cette fonction et retourner le code d’erreur STATUS_NOT_SUPPORTED.
Le pilote doit désactiver le signal à tous les autres affichages connectés à l’adaptateur d’affichage. Si cela n’est pas possible, le pilote doit tenter de placer une image vide sur tous les autres affichages. Si cela n’est pas possible, le pilote doit laisser la dernière image à l’écran inchangée.
Le pilote doit conserver le mode d’affichage actuel sur la cible indiquée et fournir ce mode au système d’exploitation dans le cadre de cet appel de fonction.
Si le pilote ne peut pas maintenir le mode d’affichage actuel, ou si la cible ne fait pas partie de la topologie active, le pilote doit tenter de définir une mémoire tampon d’image sur une autre cible capable d’une résolution d’affichage d’au moins 640 x 480 pixels dans un format de 24 bits par pixel. Si ce n’est pas possible, le pilote peut échouer cet appel de fonction, ce qui entraîne une vérification de bogue système et l’affichage d’un écran noir.
Il n’est pas obligatoire que le pilote utilise un mode mémoire tampon d’image linéaire. Toutefois, le pilote doit prendre en charge les opérations d’écriture dans cette mémoire tampon de trame à partir de sources au format D3DDDIFMT_A8R8G8B8 de l’énumération D3DDDIFORMAT .

Restrictions relatives à l’image source

Une fois que le pilote a donné au système d’exploitation le contrôle sur la fonctionnalité d’affichage, le système d’exploitation peut appeler la fonction DxgkDdiSystemDisplayWrite pour mettre à jour l’image d’écran et écrire un bloc d’images provenant de sources spécifiées dans l’écran qui a été réinitialisé par la fonction DxgkDdiSystemDisplayEnable .

DxgkDdiSystemDisplayWrite fournit au pilote l’adresse de départ de l’image source ainsi que la foulée, la largeur et la hauteur. Le format de couleur de l’image source est toujours D3DDDIFMT_X8R8G8B8. Le système d’exploitation garantit que l’image source est en mémoire non paginée.

Le pilote doit écrire cette image source sur l’écran actif en commençant aux positions spécifiées par les paramètres PositionX et PositionY de la fonction DxgkDdiSystemDisplayWrite .

Il est recommandé que le pilote utilise le processeur pour écrire l’image à partir de la source dans la mémoire tampon de trame, car une vérification de bogue système peut être provoquée par des instances de détection et de récupération de délai d’expiration (TDR) répétées qui entraînent l’état inconnu du GPU.

Utiliser de la mémoire non paginée

Les fonctions en mode noyau Windows peuvent ne pas être disponibles pendant l’appel de cette fonction.

DxgkDdiSystemDisplayEnable peut être appelé au niveau de n’importe quel IRQL. Il doit donc être en mémoire non modifiable. DxgkDdiSystemDisplayEnable ne doit pas appeler de code qui se trouve dans la mémoire paginable et ne doit pas manipuler les données qui se trouve dans la mémoire paginable.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Serveur minimal pris en charge	Windows Server 2012
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	dispmprt.h
IRQL	N’importe quel niveau (voir la section Remarques)