Fonction EngAssociateSurface (winddi.h)

Article
08/27/2023

La fonction EngAssociateSurface marque une surface donnée comme appartenant à un appareil spécifié.

Syntaxe

ENGAPI BOOL EngAssociateSurface(
  HSURF hsurf,
  HDEV  hdev,
  FLONG flHooks
);

Paramètres

hsurf

Gérez la surface ou la bitmap à associer à hdev. Ce handle a été retourné par EngCreateBitmap ou EngCreateDeviceBitmap.

hdev

Gérez l’appareil auquel la surface doit être associée. Il s’agit du handle créé par GDI qui a été passé à la fonction DrvCompletePDEV du pilote.

flHooks

Spécifie les fonctions que le pilote peut crocheter à partir de GDI. Le pilote doit implémenter la fonction correspondante pour chaque bit qu’il définit dans les flHooks. Ce membre est un or au niveau du bit de l’une des valeurs suivantes :

Indicateur	Fonction à accrocher
HOOK_ALPHABLEND	DrvAlphaBlend
HOOK_BITBLT	DrvBitBlt
HOOK_COPYBITS	DrvCopyBits
HOOK_FILLPATH	DrvFillPath
HOOK_GRADIENTFILL	DrvGradientFill
HOOK_LINETO	DrvLineTo
HOOK_MOVEPANNING	Obsolète
HOOK_PAINT	Obsolète
HOOK_PLGBLT	DrvPlgBlt
HOOK_STRETCHBLT	DrvStretchBlt
HOOK_STRETCHBLTROP	DrvStretchBltROP
HOOK_STROKEANDFILLPATH	DrvStrokeAndFillPath
HOOK_STROKEPATH	DrvStrokePath
HOOK_SYNCHRONIZE	DrvSynchronize ou DrvSynchronizeSurface (ou les deux)
HOOK_SYNCHRONIZEACCESS	Obsolète
HOOK_TEXTOUT	DrvTextOut
HOOK_TRANSPARENTBLT	DrvTransparentBlt

Valeur retournée

La valeur de retour est TRUE si la fonction réussit. Sinon, le pilote doit envoyer les informations à la fonction GDI qu’il implémente et retourner la valeur de retour de GDI.

Remarques

EngAssociateSurface peut être utilisé par les pilotes d’imprimante pour implémenter des « règles » ou des polices d’appareil, ou par des pilotes d’affichage pour utiliser du matériel blt spécial.

Si la surface identifiée par hsurf est une image bitmap au format standard, le pilote peut spécifier les fonctions de sortie de la surface qu’il va gérer en définissant des bits dans flHooks. La définition de bits dans flHooks entraîne l’envoi de fonctions de sortie particulières au pilote à la place. C’est ce qu’on appelle crochetage. Si le pilote ne crochete pas d’appel, GDI gère automatiquement l’opération lorsqu’un bitmap de format standard est dessiné.

Lorsque la surface est associée, elle suppose la palette et les étapes de style par défaut du PDEV. Une surface doit être associée avant d’être retournée par DrvEnableSurface.

Par défaut, lorsqu’un pilote prend en charge les bitmaps d’appareil en implémentant DrvCreateDeviceBitmap/DrvDeleteDeviceBitmap, GDI ne synchronise pas automatiquement les appels de dessin à la bitmap de l’appareil et à la surface primaire. Par exemple, GDI peut appeler la fonction DrvBitBlt du pilote pour dessiner dans une image bitmap d’appareil, tandis qu’un autre thread dessine vers la surface primaire en exécutant l’implémentation du pilote de DrvTextOut. Le pilote peut même être appelé à dessiner vers plusieurs bitmaps d’appareil en même temps.

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

Configuration requise


Client minimal pris en charge	Disponible dans Windows 2000 et versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Universal
En-tête	winddi.h (inclure Winddi.h)
Bibliothèque	Win32k.lib
DLL	Win32k.sys