Fonction EngAlphaBlend (winddi.h)

Article
08/27/2023

La fonction EngAlphaBlend fournit des fonctionnalités de transfert de bloc de bits avec fusion alpha.

Syntaxe

ENGAPI BOOL EngAlphaBlend(
  SURFOBJ  *psoDest,
  SURFOBJ  *psoSrc,
  CLIPOBJ  *pco,
  XLATEOBJ *pxlo,
  RECTL    *prclDest,
  RECTL    *prclSrc,
  BLENDOBJ *pBlendObj
);

Paramètres

psoDest

Pointeur vers une structure SURFOBJ qui identifie la surface sur laquelle dessiner.

psoSrc

Pointeur vers une structure SURFOBJ qui identifie la surface source.

pco

Pointeur vers une structure CLIPOBJ . Les routines de service CLIPOBJ_Xxx sont fournies pour énumérer la région de clip sous la forme d’un ensemble de rectangles. Cette énumération limite la zone de la destination modifiée. Dans la mesure du possible, GDI simplifie le découpage impliqué. Toutefois, contrairement à EngBitBlt, EngAlphaBlend peut être appelé avec un rectangle unique afin d’éviter les erreurs d’arrondi lors du découpage de la sortie.

pxlo

Pointeur vers une structure XLATEOBJ qui spécifie comment les index de couleur doivent être traduits entre les surfaces source et de destination.

Si la surface source est gérée par palette, ses couleurs sont représentées par des index dans une table de recherche de valeurs de couleurs RVB. Dans ce cas, GDI peut interroger la structure XLATEOBJ pour obtenir un vecteur de traduction afin de traduire rapidement n’importe quel index source en index de couleur pour la destination.

La situation est plus compliquée lorsque, par exemple, la source est RVB, mais que la destination est gérée par palette. Dans ce cas, la correspondance la plus proche de chaque valeur RVB source doit être trouvée dans la palette de destination. GDI appelle la routine de service XLATEOBJ_iXlate pour effectuer cette opération de correspondance.

prclDest

Pointeur vers une structure RECTL qui définit la zone rectangulaire à modifier. Ce rectangle est spécifié dans le système de coordonnées de la surface de destination et est défini par deux points : en haut à gauche et en bas à droite. Les deux points qui définissent le rectangle sont toujours bien ordonnés.

Le rectangle est exclusif en bas à droite ; autrement dit, ses bords inférieur et droit ne font pas partie du mélange.

Le rectangle spécifié peut surplomber la surface de destination ; GDI effectue le découpage approprié lorsqu’il le fait.

EngAlphaBlend ne doit jamais être appelé avec un rectangle de destination vide.

prclSrc

Pointeur vers une structure RECTL qui définit la zone à copier. Ce rectangle est spécifié dans le système de coordonnées de la surface source et est défini par deux points : en haut à gauche et en bas à droite. Les deux points qui définissent le rectangle sont toujours bien ordonnés.

Le rectangle est exclusif en bas à droite ; autrement dit, ses bords inférieur et droit ne font pas partie du mélange.

Le rectangle source ne doit jamais dépasser les limites de la surface source et ne jamais dépasser la surface source.

EngAlphaBlend ne doit jamais être appelé avec un rectangle source vide.

Le mappage est défini par prclSrc et prclDest. Les points spécifiés dans prclDest et prclSrc se trouvent sur des coordonnées entières, qui correspondent aux centres de pixels. Un rectangle défini par deux points de ce type est considéré comme un rectangle géométrique avec deux sommets dont les coordonnées sont les points donnés, mais avec 0,5 soustrait de chaque coordonnée. (Les structures POINTL sont une notation abrégée permettant de spécifier ces sommets de coordonnées fractionnaires.)

pBlendObj

Pointeur vers une structure BLENDOBJ qui décrit l’opération de fusion à effectuer entre les surfaces source et de destination. Cette structure est un wrapper pour la structure BLENDFUNCTION, qui inclut les informations de format source et de destination nécessaires qui ne sont pas disponibles dans la structure XLATEOBJ . BLENDFUNCTION est déclaré dans la documentation Microsoft Windows SDK. Ses membres sont définis comme suit :

BlendOp définit l’opération de fusion à effectuer. Actuellement, cette valeur doit être AC_SRC_OVER, ce qui signifie que la bitmap source est placée sur la bitmap de destination en fonction des valeurs alpha des pixels sources. Il existe trois cas possibles que cette opération de fusion doit gérer. Celles-ci sont décrites dans la section Remarques de cette page de référence.

BlendFlags est réservé et est actuellement défini sur zéro.

SourceConstantAlpha définit le facteur de fusion constant à appliquer à l’ensemble de la surface source. Cette valeur se situe dans la plage de [0,255], où 0 est entièrement transparent et 255 est complètement opaque.

AlphaFormat définit si la surface est supposée avoir un canal alpha. Ce membre peut éventuellement être défini sur la valeur suivante :

AC_SRC_ALPHA

La surface source peut être supposée être au format « BGRA » alpha 32bpp prémultiplié ; autrement dit, le type de surface est BMF_32BPP et le type de palette est BI_RGB. Le composant alpha est un entier dans la plage de [0,255], où 0 est complètement transparent et 255 est complètement opaque.

Valeur retournée

EngAlphaBlend retourne TRUE en cas de réussite. Si une erreur se produit, elle retourne FALSE et signale un code d’erreur.

Remarques

Un transfert de bloc de bits avec fusion alpha est pris en charge entre les surfaces suivantes :

D’une surface gérée par l’appareil à une autre surface gérée par l’appareil.
D’une bitmap de format standard gérée par GDI à une autre bitmap de format standard gérée par GDI.
D’une surface gérée par l’appareil à une surface gérée par GDI, et vice versa.

Le pilote ne doit jamais appeler EngAlphaBlend avec des rectangles source et de destination qui se chevauchent sur la même surface.

Les trois cas possibles pour la fonction AC_SRC_OVER blend sont les suivants :

La bitmap source n’a pas d’alpha par pixel (AC_SRC_ALPHA n’est pas définie), de sorte que le mélange est appliqué aux canaux de couleur du pixel en fonction de la valeur alpha source constante spécifiée dans SourceConstantAlpha comme suit :

Dst.Red = Round(((Src.Red * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Red)) / 255);
Dst.Green = Round(((Src.Green * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Green)) / 255);
Dst.Blue = Round(((Src.Blue * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Blue)) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Round(((Src.Alpha * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Alpha)) / 255);

L’image bitmap source a des valeurs alpha par pixel (AC_SRC_ALPHA est définie) et SourceConstantAlpha n’est pas utilisée (elle est définie sur 255). Le mélange est calculé comme suit :

Dst.Red = Src.Red + 
    Round(((255 − Src.Alpha) * Dst.Red) / 255);
Dst.Green = Src.Green + 
    Round(((255 − Src.Alpha) * Dst.Green) / 255);
Dst.Blue = Src.Blue + 
    Round(((255 − Src.Alpha) * Dst.Blue) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Src.Alpha + 
    Round(((255 − Src.Alpha) * Dst.Alpha) / 255);

La bitmap source a des valeurs alpha par pixel (AC_SRC_ALPHA est définie), et SourceConstantAlpha est utilisé (elle n’est pas définie sur 255). Le mélange est calculé comme suit :

Temp.Red = Round((Src.Red * SourceConstantAlpha) / 255);
Temp.Green = Round((Src.Green * SourceConstantAlpha) / 255);
Temp.Blue = Round((Src.Blue * SourceConstantAlpha) / 255);
/* The next computation must be done even if the 
    destination bitmap does not have an alpha channel. */
Temp.Alpha = Round((Src.Alpha * SourceConstantAlpha) / 255);
 
/* Note that the following equations use the just-computed 
   Temp.Alpha value: */
Dst.Red = Temp.Red + 
    Round(((255 − Temp.Alpha) * Dst.Red) / 255);
Dst.Green = Temp.Green + 
    Round(((255 − Temp.Alpha) * Dst.Green) / 255);
Dst.Blue = Temp.Blue + 
    Round(((255 − Temp.Alpha) * Dst.Blue) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Temp.Alpha + 
    Round(((255 − Temp.Alpha) * Dst.Alpha) / 255);

Le pilote doit appeler EngAlphaBlend s’il a crocheté DrvAlphaBlend et qu’il est appelé pour faire quelque chose qu’il ne prend pas en charge.

Configuration requise

Condition requise	Valeur
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