Fonction DrvStretchBlt (winddi.h)

Article
03/04/2024

La fonction DrvStretchBlt offre des fonctionnalités de transfert par bloc de bits entre n’importe quelle combinaison de surfaces gérées par l’appareil et gérées par GDI.

Syntaxe

BOOL DrvStretchBlt(
  [in, out]      SURFOBJ         *psoDest,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMask,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in]           POINTL          *pptlHTOrg,
  [in]           RECTL           *prclDest,
  [in]           RECTL           *prclSrc,
  [in, optional] POINTL          *pptlMask,
  [in]           ULONG           iMode
);

Paramètres

[in, out] psoDest

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

[in, out] psoSrc

Pointeur vers la structure SURFOBJ qui définit la source pour l’opération de transfert de bloc de bits.

[in, optional] psoMask

Pointeur facultatif vers une structure SURFOBJ qui définit une surface qui fournit un masque pour la source. Le masque est défini par une carte logique, qui est une bitmap avec 1 bit par pixel.

Le masque limite la zone de la source copiée. Si ce paramètre est spécifié, il a un rop4 implicite de 0xCCAA, ce qui signifie que la source doit être copiée partout où le masque est un, mais que la destination doit être laissée seule partout où le masque est zéro.

Lorsque ce paramètre a la valeur NULL, il existe un rop4 implicite de 0xCCCC, ce qui signifie que la source doit être copiée partout dans le rectangle source.

Le masque sera toujours assez grand pour contenir la source appropriée ; le carrelage n’est pas nécessaire.

[in] pco

Pointeur vers une structure CLIPOBJ qui limite la zone à modifier dans la destination. Les services GDI sont fournis pour énumérer la région de clip sous la forme d’un ensemble de rectangles.

Dans la mesure du possible, GDI simplifie le découpage impliqué. Toutefois, contrairement à DrvBitBlt, DrvStretchBlt peut être appelé avec un rectangle de découpage unique. Cela empêche les erreurs d’arrondi lors de la coupe de la sortie.

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

La structure XLATEOBJ peut également être interrogée pour trouver la couleur RVB de n’importe quel index source. Un transfert de bloc de bits étirement de haute qualité doit interpoler les couleurs dans certains cas.

[in, optional] pca

Pointeur vers une structure COLORADJUSTMENT qui définit les valeurs d’ajustement des couleurs à appliquer à l’image bitmap source avant d’étendre les bits. (Consultez la documentation Microsoft Windows SDK.)

[in] pptlHTOrg

Pointeur vers une structure POINTL qui spécifie l’origine du pinceau en demi-teinte. Les pilotes de périphérique qui utilisent des pinceaux en demi-teinte doivent aligner le pixel supérieur gauche du motif du pinceau sur ce point sur la surface de l’appareil.

[in] prclDest

Pointeur vers une structure RECTL qui définit la zone à modifier dans le système de coordonnées de la surface de destination. Ce rectangle est défini par deux points qui ne sont pas nécessairement bien ordonnés, ce qui signifie que les coordonnées du deuxième point ne sont pas nécessairement plus grandes que celles du premier point. Le rectangle qu’ils décrivent n’inclut pas les bords inférieur et droit. Cette fonction n’est jamais appelée avec un rectangle de destination vide.

DrvStretchBlt doit échanger les deux valeurs x et/ou les deux valeurs y lorsque le rectangle de destination n’est pas bien ordonné.

[in] prclSrc

Pointeur vers une structure RECTL qui définit la zone qui sera copiée dans le système de coordonnées de la surface source. Le rectangle est défini par deux points et est mappé au rectangle défini par prclDest. Les points du rectangle source sont bien ordonnés. Cette fonction ne reçoit jamais de 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 à des 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 doivent être considérées comme une notation abrégée pour spécifier ces sommets de coordonnées fractionnaires.)

Les bords d’un rectangle n’entrecroisent jamais un pixel, mais tournent autour d’un ensemble de pixels. Les pixels à l’intérieur du rectangle sont ceux attendus pour un rectangle « exclusif en bas à droite ». DrvStretchBlt mappe exactement le rectangle source géométrique sur le rectangle géométrique de destination.

[in, optional] pptlMask

Pointeur vers une structure POINTL qui spécifie quel pixel dans le masque donné correspond au pixel supérieur gauche dans le rectangle source. Ignorez ce paramètre si aucun masque n’est spécifié.

[in] iMode

Spécifie la façon dont les pixels sources sont combinés pour obtenir des pixels de sortie. Le mode HALFTONE est plus lent que les autres modes, mais produit des images de qualité supérieure.

Valeur	Signification
BLACKONWHITE	Lors d’un transfert de bloc de bits qui diminue, les pixels doivent être combinés à une opération BOOLEAN AND. Lors d’un transfert de bloc de bits étiré, les pixels doivent être répliqués.
COLORONCOLOR	Lors d’un transfert de bloc de bits qui diminue, suffisamment de pixels doivent être ignorés pour que les pixels n’ont pas besoin d’être combinés. Lors d’un transfert de bloc de bits étiré, les pixels doivent être répliqués.
DEMI-TEINTES	Le pilote peut utiliser des groupes de pixels dans la surface de sortie pour estimer au mieux la couleur ou le niveau de gris de l’entrée.
WHITEONBLACK	Lors d’un transfert de bloc de bits de réduction, les pixels doivent être combinés à une opération OR booléenne. Lors d’un transfert de bloc de bits étiré, les pixels doivent être répliqués.

Valeur retournée

La valeur de retour est TRUE si la fonction réussit. Sinon, il est FALSE et un code d’erreur est journalisé.

Remarques

DrvStretchBlt permet au pilote de périphérique d’écrire dans des bitmaps GDI, en particulier lorsque le pilote peut effectuer le demi-toning. Cette fonction permet d’appliquer le même algorithme de halftoning aux bitmaps GDI et aux surfaces d’appareil.

Cette fonction peut être fournie pour gérer uniquement certaines formes d’étirement, telles que les multiples entiers. Si le pilote a crocheté l’appel et est invité à effectuer une opération qu’il ne prend pas en charge, il doit transférer les données à EngStretchBlt pour que GDI gère.

Si le pilote souhaite que GDI gère la demi-toning et souhaite s’assurer de la valeur iMode appropriée, le pilote peut crocheter DrvStretchBlt, définir iMode sur HALFTONE et rappeler à GDI avec EngStretchBlt avec la valeur iMode définie.

DrvStretchBlt est facultatif pour les pilotes d’affichage.