DrvEnableSurface, fonction (winddi.h)

Article
03/09/2024

La fonction DrvEnableSurface configure une surface à dessiner et l’associe à un appareil physique donné.

Syntaxe

HSURF DrvEnableSurface(
  DHPDEV dhpdev
);

Paramètres

dhpdev

Gérez le PDEV de l’appareil physique. Il s’agit de la valeur de retour de DrvEnablePDEV. Le PDEV décrit l’appareil physique pour lequel une surface doit être créée.

Valeur retournée

La valeur de retour est un handle qui identifie la surface nouvellement créée. Sinon, il est égal à zéro et un code d’erreur est journalisé.

Remarques

Il existe deux méthodes pour préparer une surface à utiliser.

Dans cette méthode, qui est recommandée, le pilote crée la surface par un appel à EngCreateDeviceSurface. Une fois que GDI a créé la surface et retourné une poignée au pilote, le pilote appelle EngModifySurface, qui définit les indicateurs de crochet appropriés et, éventuellement, informe GDI de l’emplacement de la surface.
La deuxième méthode est celle utilisée par les pilotes Windows NT 4.0. Dans cette méthode, le pilote appelle EngCreateBitmap. Après cet appel, le pilote appelle EngAssociateSurface pour associer la surface au périphérique d’affichage physique. Cette fonction GDI permet au pilote de spécifier les routines de sortie graphiques prises en charge pour les bitmaps de format standard. Un appel à cette fonction ne peut être effectué que lorsqu’il n’existe aucune surface pour l’appareil physique donné. Si un pilote Windows 2000 ou ultérieur est rétro-porté pour s’exécuter sur Windows NT 4.0, cette méthode doit être utilisée. Si un tel pilote s’exécute également sur Windows 2000 ou version ultérieure, un chemin de code distinct dans le pilote doit utiliser la première méthode.
Pour les périphériques d’imprimante, la situation habituelle est que GDI collecte les graphiques directement sur une bitmap GDI. Le pilote doit appeler EngCreateBitmap, ce qui permet à GDI d’allouer de la mémoire pour la bitmap.

Tout handle bitmap GDI existant est un handle de surface valide.

Pour les DLL graphiques d’imprimante qui utilisent des surfaces gérées par GDI, la fonction DrvEnableSurface doit appeler EngCreateBitmap, en spécifiant une taille de surface suffisamment grande pour contenir une page physique entière. En cas d’échec, des appels répétés à EngCreateBitmap doivent être tentés, avec des tailles de surface décroissantes, jusqu’à ce qu’un appel aboutisse. La taille valide doit être spécifiée comme entrée dans EngMarkBandingSurface, ce qui informe GDI que le bandeau de surface sera nécessaire.

Une fois que DrvEnableSurface a retourné un handle à une surface primaire, n’appelez pas EngModifySurface ou EngAssociateSurface sur cette poignée. Cela peut entraîner un bogue case activée dans certaines circonstances. Pour plus d’informations, consultez l’article 330248 de la Base de connaissances Microsoft.

DrvEnableSurface est requis pour les pilotes graphiques.