Fonction DrvAlphaBlend (winddi.h)

Article
03/06/2024

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

Syntaxe

BOOL DrvAlphaBlend(
  [in, out]      SURFOBJ  *psoDest,
  [in]           SURFOBJ  *psoSrc,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclDest,
  [in]           RECTL    *prclSrc,
  [in]           BLENDOBJ *pBlendObj
);

Paramètres

[in, out] psoDest

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

[in] psoSrc

Pointeur vers une structure SURFOBJ qui identifie la surface source.

[in] 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 à DrvBitBlt, DrvAlphaBlend peut être appelé avec un rectangle unique afin d’éviter les erreurs d’arrondi lors du découpage de la sortie.

[in, optional] 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 pxlo a la valeur NULL, aucune traduction n’est nécessaire.

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, le XLATEOBJ peut être interrogé pour un vecteur de traduction qui permet au pilote de périphérique 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. Le pilote peut appeler la routine de service XLATEOBJ_iXlate pour effectuer cette opération de correspondance.

[in] 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 pilote doit veiller à effectuer un découpage approprié lors de l’écriture des pixels, car le rectangle spécifié peut surplomber la surface de destination.

DrvAlphaBlend n’est jamais appelé avec un rectangle de destination vide.

[in] 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 dépassera jamais les limites de la surface source et ne dépassera donc jamais la surface source.

DrvAlphaBlend n’est jamais 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.)

[in] 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 non disponibles dans le XLATEOBJ. La structure BLENDFUNCTION est définie 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.

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

DrvAlphaBlend retourne TRUE en cas de réussite. Sinon, elle signale une erreur et retourne FALSE.

Remarques

Le pilote peut prendre en charge un transfert de bloc de bits avec fusion alpha 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 peut passer des appels à EngAlphaBlend.

Le pilote ne sera jamais appelé 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 :

L’image 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 couleurs 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);

La fonction Round(x) est arrondie à l’entier le plus proche, calculé comme suit :

Trunc(x + 0.5);

DrvAlphaBlend peut être implémenté éventuellement dans les pilotes graphiques. Il peut être fourni pour gérer certains types de mélanges alpha, tels que les mélanges où les surfaces source et de destination sont au même format et ne contiennent pas de canal alpha.

Une implémentation matérielle peut utiliser une virgule flottante ou un point fixe dans l’opération de fusion. Les tests de compatibilité vont tenir compte d’une erreur numérique dans les résultats ; Pour plus d’informations sur l’erreur maximale autorisée, consultez Effets spéciaux dans les pilotes d’affichage . Lorsque vous utilisez un point fixe, une approximation acceptable du terme x/255 est (x*257)/65536. Incorporant l’arrondi, l’expression :

((255 - Src.Alpha) * Dst.Red) / 255

peut ensuite être approximatif comme suit :

temp = ((255 - Src.Alpha) * Dst.Red) + 128;
result = (temp + (temp >> 8)) >> 8;

Le pilote raccorde DrvAlphaBlend en définissant l’indicateur HOOK_ALPHABLEND lorsqu’il appelle EngAssociateSurface. Si le pilote a crocheté DrvAlphaBlend et est appelé pour effectuer une opération qu’il ne prend pas en charge, le pilote doit demander à GDI de gérer l’opération en puntant les données dans un appel à EngAlphaBlend.