StretchDIBits, fonction (wingdi.h)

Article
03/08/2023

La fonction StretchDIBits copie les données de couleur d’un rectangle de pixels dans une image DIB, JPEG ou PNG dans le rectangle de destination spécifié. Si le rectangle de destination est plus grand que le rectangle source, cette fonction étire les lignes et les colonnes des données de couleur pour les adapter au rectangle de destination. Si le rectangle de destination est plus petit que le rectangle source, cette fonction compresse les lignes et les colonnes à l’aide de l’opération raster spécifiée.

Syntaxe

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Paramètres

[in] hdc

Handle du contexte de l’appareil de destination.

[in] xDest

Coordonnée x, en unités logiques, du coin supérieur gauche du rectangle de destination.

[in] yDest

Coordonnée y, en unités logiques, du coin supérieur gauche du rectangle de destination.

[in] DestWidth

Largeur, en unités logiques, du rectangle de destination.

[in] DestHeight

Hauteur, en unités logiques, du rectangle de destination.

[in] xSrc

Coordonnée x, en pixels, du rectangle source dans l’image.

[in] ySrc

Coordonnée y, en pixels, du rectangle source dans l’image.

[in] SrcWidth

Largeur, en pixels, du rectangle source dans l’image.

[in] SrcHeight

Hauteur, en pixels, du rectangle source dans l’image.

[in] lpBits

Pointeur vers les bits d’image, qui sont stockés sous la forme d’un tableau d’octets. Pour plus d'informations, consultez la section Notes.

[in] lpbmi

Pointeur vers une structure BITMAPINFO qui contient des informations sur la DIB.

[in] iUsage

Spécifie si le membre bmiColors de la structure BITMAPINFO a été fourni et, le cas échéant, si bmiColors contient des valeurs ou des index (RVB) explicites. Le paramètre iUsage doit être l’une des valeurs suivantes.

Valeur	Signification
DIB_PAL_COLORS	Le tableau contient des index 16 bits dans la palette logique du contexte d’appareil source.
DIB_RGB_COLORS	La table de couleurs contient des valeurs RVB littérales.

Pour plus d'informations, consultez la section Notes.

[in] rop

Code d’opération raster qui spécifie comment les pixels sources, le pinceau actuel du contexte de l’appareil de destination et les pixels de destination doivent être combinés pour former la nouvelle image. Pour obtenir la liste de certains codes d’opération raster courants, consultez BitBlt.

Valeur retournée

Si la fonction réussit, la valeur de retour correspond au nombre de lignes d’analyse copiées. Notez que cette valeur peut être négative pour le contenu mis en miroir.

Si la fonction échoue ou si aucune ligne d’analyse n’est copiée, la valeur de retour est 0.

Si le pilote ne peut pas prendre en charge l’image de fichier JPEG ou PNG passée à StretchDIBits, la fonction échoue et retourne GDI_ERROR. En cas d’échec, l’application doit se replier sur sa propre prise en charge JPEG ou PNG pour décompresser l’image dans une bitmap, puis passer la bitmap à StretchDIBits.

Remarques

L’origine d’un DIB de bas en haut est le coin inférieur gauche ; l’origine d’un DIB du haut vers le bas est le coin supérieur gauche.

StretchDIBits crée une image miroir d’une bitmap si les signes des paramètres nSrcWidth et nDestWidth, ou si les paramètres nSrcHeight et nDestHeight diffèrent. Si nSrcWidth et nDestWidth ont des signes différents, la fonction crée une image miroir de la bitmap le long de l’axe X. Si nSrcHeight et nDestHeight ont des signes différents, la fonction crée une image miroir de la bitmap le long de l’axe y.

StretchDIBits crée une image de haut en bas si le signe du membre biHeight de la structure BITMAPINFOHEADER pour la DIB est négatif. Pour obtenir un exemple de code, consultez Dimensionnement d’une image JPEG ou PNG.

Cette fonction permet de transmettre une image JPEG ou PNG en tant qu’image source. La façon dont chaque paramètre est utilisé reste la même, sauf :

Si le membre biCompression de BITMAPINFOHEADER est BI_JPEG ou BI_PNG, lpBits pointe vers une mémoire tampon contenant une image JPEG ou PNG, respectivement. Le membre biSizeImage de la structure BITMAPINFOHEADER spécifie la taille de la mémoire tampon. Le paramètre iUsage doit être défini sur DIB_RGB_COLORS. Le paramètre dwRop doit être défini sur SRCCOPY.
Pour garantir une mise en attente correcte des métafichiers lors de l’impression, les applications doivent appeler l’échappement CHECKJPEGFORMAT ou CHECKPNGFORMAT pour vérifier que l’imprimante reconnaît l’image JPEG ou PNG, respectivement, avant d’appeler StretchDIBits.

ICM: La gestion des couleurs est effectuée si la gestion des couleurs a été activée avec un appel à SetICMMode avec le paramètre iEnableICM défini sur ICM_ON. Si la bitmap spécifiée par lpBitsInfo a un BITMAPV4HEADER qui spécifie les membres gamma et points de terminaison, ou un BITMAPV5HEADER qui spécifie les membres gamma et points de terminaison ou les membres profileData et profileSize, l’appel traite les pixels de la bitmap comme étant exprimés dans l’espace de couleurs décrit par ces membres, plutôt que dans l’espace de couleur source du contexte d’appareil.

Exemples

Pour obtenir un exemple, consultez Dimensionnement d’une image JPEG ou PNG.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wingdi.h (inclure Windows.h)
Bibliothèque	Gdi32.lib
DLL	Gdi32.dll