Fonction SetDIBitsToDevice (wingdi.h)

Article
03/04/2024

La fonction SetDIBitsToDevice définit les pixels dans le rectangle spécifié sur l’appareil associé au contexte de l’appareil de destination à l’aide des données de couleur d’une image DIB, JPEG ou PNG.

Syntaxe

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Paramètres

[in] hdc

Handle dans le contexte de l’appareil.

[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] w

Largeur, en unités logiques, de l’image.

[in] h

Hauteur, en unités logiques, de l’image.

[in] xSrc

Coordonnée x, en unités logiques, du coin inférieur gauche de l’image.

[in] ySrc

Coordonnée y, en unités logiques, du coin inférieur gauche de l’image.

[in] StartScan

Ligne de balayage de départ dans l’image.

[in] cLines

Nombre de lignes d’analyse DIB contenues dans le tableau pointé vers le paramètre lpvBits .

[in] lpvBits

Pointeur vers les données de couleur stockées sous forme de tableau d’octets. Pour plus d'informations, consultez la section Notes qui suit.

[in] lpbmi

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

[in] ColorUse

Indique si le membre bmiColors de la structure BITMAPINFO contient des valeurs ou des index rouges, verts, bleus (RVB) explicites dans une palette. Pour plus d'informations, consultez la section Notes qui suit.

Le paramètre fuColorUse doit être l’une des valeurs suivantes.

Valeur	Signification
DIB_PAL_COLORS	La table de couleurs se compose d’un tableau d’index 16 bits dans la palette logique actuellement sélectionnée.
DIB_RGB_COLORS	La table de couleurs contient des valeurs RVB littérales.

Valeur retournée

Si la fonction réussit, la valeur de retour correspond au nombre de lignes d’analyse définies.

Si aucune ligne d’analyse est définie (par exemple, lorsque dwHeight a la valeur 0) ou si la fonction échoue, la fonction retourne zéro.

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

Remarques

Une vitesse de dessin bitmap optimale est obtenue lorsque les bits bitmap sont indexés dans la palette système.

Les applications peuvent récupérer les couleurs et les index de palette système en appelant la fonction GetSystemPaletteEntries . Une fois les couleurs et les index récupérés, l’application peut créer la DIB. Pour plus d’informations sur la palette système, consultez Couleurs.

Les lignes d’analyse doivent être alignées sur un DWORD , à l’exception des bitmaps compressées en RLE.

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

Pour réduire la quantité de mémoire nécessaire pour définir des bits d’une DIB volumineuse sur une surface d’appareil, une application peut regrouper la sortie en appelant à plusieurs reprises SetDIBitsToDevice, en plaçant une partie différente de l’image bitmap dans le tableau lpvBits à chaque fois. Les valeurs des paramètres uStartScan et cScanLines identifient la partie de l’image bitmap contenue dans le tableau lpvBits .

La fonction SetDIBitsToDevice retourne une erreur si elle est appelée par un processus qui s’exécute en arrière-plan pendant qu’une session MS-DOS en plein écran s’exécute au premier plan.

Si le membre biCompression de BITMAPINFOHEADER est BI_JPEG ou BI_PNG, lpvBits pointe vers une mémoire tampon contenant une image JPEG ou PNG. Le membre biSizeImage de spécifie la taille de la mémoire tampon. Le paramètre fuColorUse doit être défini sur DIB_RGB_COLORS.
Pour garantir un pool de métafichiers approprié 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 SetDIBitsToDevice.

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 lpbmi a une BITMAPV4HEADER qui spécifie les membres gamma et les points de terminaison, ou une BITMAPV5HEADER qui spécifie les membres gamma et points de terminaison ou les membres profileData et profileSize, l’appel traite les pixels de l’image 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 Test d’une imprimante pour la prise en charge 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