GetDIBits, fonction (wingdi.h)

Article
08/27/2023

La fonction GetDIBits récupère les bits de l’image bitmap compatible spécifiée et les copie dans une mémoire tampon en tant que DIB au format spécifié.

Syntaxe

int GetDIBits(
  [in]      HDC          hdc,
  [in]      HBITMAP      hbm,
  [in]      UINT         start,
  [in]      UINT         cLines,
  [out]     LPVOID       lpvBits,
  [in, out] LPBITMAPINFO lpbmi,
  [in]      UINT         usage
);

Paramètres

[in] hdc

Handle dans le contexte de l’appareil.

[in] hbm

Handle de la bitmap. Il doit s’agir d’une bitmap compatible (DDB).

[in] start

Première ligne d’analyse à récupérer.

[in] cLines

Nombre de lignes d’analyse à récupérer.

[out] lpvBits

Pointeur vers une mémoire tampon pour recevoir les données bitmap. Si ce paramètre a la valeur NULL, la fonction transmet les dimensions et le format de l’image bitmap à la structure BITMAPINFO pointée par le paramètre lpbmi .

[in, out] lpbmi

Pointeur vers une structure BITMAPINFO qui spécifie le format souhaité pour les données DIB.

[in] usage

Format du membre bmiColors de la structure BITMAPINFO . Il doit s’agir de l’une des valeurs suivantes.

Valeur	Signification
DIB_PAL_COLORS	La table de couleurs doit se composer d’un tableau d’index 16 bits dans la palette logique actuelle.
DIB_RGB_COLORS	La table de couleurs doit se composer de valeurs littérales rouge, verte et bleue (RVB).

Valeur retournée

Si le paramètre lpvBits n’a pas la valeur NULL et que la fonction réussit, la valeur de retour correspond au nombre de lignes d’analyse copiées à partir de la bitmap.

Si le paramètre lpvBits a la valeur NULL et que GetDIBits remplit correctement la structure BITMAPINFO , la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro.

Cette fonction peut retourner la valeur suivante.

Code de retour	Description
ERROR_INVALID_PARAMETER	Un ou plusieurs des paramètres d’entrée n’est pas valide.

Remarques

Si le format demandé pour la DIB correspond à son format interne, les valeurs RVB de la bitmap sont copiées. Si le format demandé ne correspond pas au format interne, une table de couleurs est synthétisée. Le tableau suivant décrit la table de couleurs synthétisée pour chaque format.

Valeur	Signification
1_BPP	La table de couleurs se compose d’une entrée noire et d’une entrée blanche.
4_BPP	La table de couleurs se compose d’un mélange de couleurs identiques à la palette VGA standard.
8_BPP	La table de couleurs se compose d’un mélange général de 256 couleurs définies par GDI. (Les 20 couleurs de la palette logique par défaut sont incluses dans ces 256 couleurs.)
24_BPP	Aucune table de couleurs n’est retournée.

Si le paramètre lpvBits est un pointeur valide, les six premiers membres de la structure BITMAPINFOHEADER doivent être initialisés pour spécifier la taille et le format de la DIB. Les lignes d’analyse doivent être alignées sur un DWORD , à l’exception des bitmaps compressées RLE.

Une DIB ascendante est spécifiée en définissant la hauteur sur un nombre positif, tandis qu’une DIB descendante est spécifiée en définissant la hauteur sur un nombre négatif. La table de couleurs bitmap sera ajoutée à la structure BITMAPINFO .

Si lpvBits a la valeur NULL, GetDIBits examine le premier membre de la première structure pointée vers lpbi. Ce membre doit spécifier la taille, en octets, d’une structure BITMAPCOREHEADER ou BITMAPINFOHEADER . La fonction utilise la taille spécifiée pour déterminer comment les membres restants doivent être initialisés.

Si lpvBits a la valeur NULL et que le nombre de bits membre de BITMAPINFO est initialisé à zéro, GetDIBits remplit une structure BITMAPINFOHEADER ou BITMAPCOREHEADER sans la table de couleurs. Cette technique peut être utilisée pour interroger des attributs bitmap.

La bitmap identifiée par le paramètre hbmp ne doit pas être sélectionnée dans un contexte d’appareil lorsque l’application appelle cette fonction.

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

Exemples

Pour obtenir un exemple, consultez Capture d’une image.

Configuration requise


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