Fonction DrvBitBlt (winddi.h)

Article
08/27/2023

La fonction DrvBitBlt fournit des fonctionnalités générales de transfert par bloc de bits entre des surfaces gérées par l’appareil, entre des bitmaps de format standard gérées par GDI ou entre une surface gérée par l’appareil et une bitmap de format standard gérée par GDI.

Syntaxe

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Paramètres

[in, out] psoTrg

Pointeur vers la structure SURFOBJ qui décrit la surface sur laquelle dessiner.

[in, optional] psoSrc

Pointeur vers une structure SURFOBJ qui décrit la source de l’opération de transfert de bloc de bits, si nécessaire par le paramètre rop4 .

[in, optional] psoMask

Pointeur vers une structure SURFOBJ qui décrit une surface à utiliser comme masque pour le paramètre rop4 . Le masque est une bitmap avec 1 bit par pixel. En règle générale, un masque est utilisé pour limiter la zone à modifier dans la surface de destination. Le masquage est sélectionné en définissant le paramètre rop4 sur la valeur 0xAACC. La surface de destination n’est pas affectée si le masque est 0x0000.

Le masque sera suffisamment grand pour couvrir le rectangle de destination.

Si ce paramètre a la valeur NULL et qu’un masque est requis par le paramètre rop4 , le masque implicite dans le pinceau est utilisé.

[in] pco

Pointeur vers une structure CLIPOBJ qui limite la zone à modifier. Les services GDI (CLIPOBJXxx) qui énumèrent la région de clip sous la forme d’un ensemble de rectangles sont fournis. Dans la mesure du possible, GDI simplifie l’écrêtage impliqué ; par exemple, cette fonction n’est jamais appelée avec un seul rectangle de découpage. GDI clipse le rectangle de destination avant d’appeler cette fonction, ce qui rend inutile un découpage supplémentaire.

[in, optional] pxlo

Pointeur vers une structure XLATEOBJ qui spécifie la façon dont 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 RVB. La structure XLATEOBJ peut être interrogée pour un vecteur de traduction qui permettra au pilote de périphérique de traduire 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 se trouver dans la palette de destination. Le pilote peut appeler le service XLATEOBJ_iXlate pour effectuer cette opération.

Si vous le souhaitez, le pilote de périphérique peut faire correspondre des couleurs lorsque la palette cible est la palette d’appareils par défaut.

[in] prclTrg

Pointeur vers une structure RECTL qui définit la zone à modifier. Cette structure utilise le système de coordonnées de la surface de destination. Les bords inférieur et droit de ce rectangle ne font pas partie du transfert de bloc de bits, ce qui signifie que le rectangle est exclusif en bas à droite.

DrvBitBlt n’est jamais appelé avec un rectangle de destination vide. Les deux points qui définissent le rectangle sont toujours bien ordonnés. Toutefois, sur les systèmes multimonitor, le rectangle peut définir une région plus grande que la surface de destination. Les pilotes doivent croiser ce rectangle avec leur surface.

[in, optional] pptlSrc

Pointeur vers une structure POINTL qui définit le coin supérieur gauche du rectangle source, s’il existe une source. Ce paramètre est ignoré s’il n’existe aucune source.

[in, optional] pptlMask

Pointeur vers une structure POINTL qui définit le pixel du masque qui correspond au coin supérieur gauche du rectangle source, s’il existe une source. Ce paramètre est ignoré si le paramètre psoMask a la valeur NULL.

[in, optional] pbo

Pointeur vers une structure BRUSHOBJ qui définit le modèle pour le transfert de bloc de bits. Le service de BRUSHOBJ_pvGetRbrush de GDI peut être utilisé pour récupérer la réalisation de l’appareil du pinceau. Ce paramètre est ignoré si le paramètre rop4 ne nécessite pas de modèle.

[in, optional] pptlBrush

Pointeur vers une structure POINTL qui définit l’origine du pinceau dans la surface de destination. Le pixel supérieur gauche du pinceau est aligné à ce point et le pinceau se répète en fonction de ses dimensions. Ce paramètre est ignoré si le paramètre rop4 ne nécessite pas de modèle.

[in] rop4

Spécifie une opération raster qui définit la façon dont les pixels de masque, de modèle, de source et de destination sont combinés pour écrire dans la surface de destination.

Il s’agit d’une opération de raster quaternaire, qui est une extension de l’opération Rop3 ternaire. Un Rop4 a 16 bits pertinents, qui sont similaires aux 8 bits de définition d’un Rop3. Le moyen le plus simple d’implémenter un Rop4 consiste à considérer ses 2 octets séparément : l’octet faible spécifie un Rop3 qui doit être calculé si le masque est un, et l’octet élevé spécifie un Rop3 qui peut être calculé et appliqué si le masque est 0.

Valeur retournée

DrvBitBlt retourne TRUE si l’opération de transfert de bloc de bits réussit. Sinon, la fonction retourne FALSE et un code d’erreur est consigné.

Remarques

Si le pilote crochete DrvBitBlt, GDI appelle cette fonction lorsqu’il doit effectuer une opération BitBlt où l’une des surfaces est une surface gérée par l’appareil. Si le pilote implémente des bitmaps opaques gérées par l’appareil, il doit crocheter DrvBitBlt ; dans le cas contraire, l’accrochage DrvBitBlt est facultatif. Si le pilote ne peut pas gérer l’appel spécifié, il peut effectuer le rappel au moteur DIB en appelant EngBitBlt.

Les services CLIPOBJXxx de GDI permettent de réduire le découpage à une série de rectangles de découpage. Un vecteur de traduction aide à la traduction d’index de couleur pour les palettes.

Note Ne déréférencez pas les pointeurs de paramètres, sauf si le ROP indique qu’ils sont nécessaires. Par exemple, ne jamais déréférencer inutilement pbo-->iSolidColor , car le fait de le faire pour un ROP tel que BLACKNESS peut entraîner une violation d’accès. (Cette règle s’applique également à toute fonction qui inclut un paramètre MIX.)

Si le pilote reçoit un appel à cette fonction dans lequel le paramètre rop4 est défini sur 0XCCAA, le pilote doit effectuer l’appel à EngBitBlt, exposant la ou les surfaces de l’appareil en fonction de l’appel.

Pour plus d’informations sur les opérations raster, consultez la documentation Microsoft Windows SDK.