CreateDIBSection, fonction (wingdi.h)

Article
03/08/2023

La fonction CreateDIBSection crée une DIB dans laquelle les applications peuvent écrire directement. La fonction vous donne un pointeur vers l’emplacement des valeurs de bits bitmap. Vous pouvez fournir un handle à un objet de mappage de fichiers que la fonction utilisera pour créer l’image bitmap, ou vous pouvez laisser le système allouer la mémoire pour la bitmap.

Syntaxe

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

Paramètres

[in] hdc

Handle d'un contexte de périphérique. Si la valeur d’iUsage est DIB_PAL_COLORS, la fonction utilise la palette logique de ce contexte d’appareil pour initialiser les couleurs DIB.

[in] pbmi

Pointeur vers une structure BITMAPINFO qui spécifie différents attributs de la DIB, y compris les dimensions et les couleurs bitmap.

[in] usage

Type de données contenues dans le membre du tableau bmiColors de la structure BITMAPINFO pointée vers pbmi (index de palette logique ou valeurs RVB littérales). Les valeurs suivantes sont définies.

Valeur	Signification
DIB_PAL_COLORS	Le membre bmiColors est un tableau d’index 16 bits dans la palette logique du contexte d’appareil spécifié par hdc.
DIB_RGB_COLORS	La structure BITMAPINFO contient un tableau de valeurs RVB littérales.

[out] ppvBits

Pointeur vers une variable qui reçoit un pointeur vers l’emplacement des valeurs de bits DIB.

[in] hSection

Handle vers un objet de mappage de fichiers que la fonction utilisera pour créer la DIB. Ce paramètre peut être NULL.

Si hSection n’a pas la valeur NULL, il doit s’agir d’un handle vers un objet de mappage de fichiers créé en appelant la fonction CreateFileMapping avec l’indicateur PAGE_READWRITE ou PAGE_WRITECOPY. Les sections DIB en lecture seule ne sont pas prises en charge. Les handles créés par d’autres moyens entraînent l’échec de CreateDIBSection .

Si hSection n’a pas la valeur NULL, la fonction CreateDIBSection localise les valeurs de bits bitmap au décalage dwOffset dans l’objet de mappage de fichiers auquel fait référence hSection. Une application peut récupérer ultérieurement le handle hSection en appelant la fonction GetObject avec le HBITMAP retourné par CreateDIBSection.

Si hSection a la valeur NULL, le système alloue de la mémoire pour la DIB. Dans ce cas, la fonction CreateDIBSection ignore le paramètre dwOffset . Une application ne peut pas obtenir ultérieurement un handle pour cette mémoire. Le membre dshSection de la structure DIBSECTION renseigné en appelant la fonction GetObject sera NULL.

[in] offset

Décalage du début de l’objet de mappage de fichiers référencé par hSection , où le stockage des valeurs de bits bitmap doit commencer. Cette valeur est ignorée si hSection a la valeur NULL. Les valeurs de bits bitmap étant alignées sur les limites de mots doubles, dwOffset doit être un multiple de la taille d’un DWORD.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour la DIB nouvellement créée, et *ppvBits pointe vers les valeurs de bits bitmap.

Si la fonction échoue, la valeur de retour est NULL et *ppvBits est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

GetLastError peut retourner la valeur suivante :

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

Remarques

Comme indiqué ci-dessus, si hSection a la valeur NULL, le système alloue de la mémoire pour la DIB. Le système ferme le handle à cette mémoire lorsque vous supprimez ultérieurement la DIB en appelant la fonction DeleteObject . Si hSection n’a pas la valeur NULL, vous devez fermer vous-même le handle de mémoire hSection après avoir appelé DeleteObject pour supprimer l’image bitmap.

Vous ne pouvez pas coller une section DIB d’une application dans une autre application.

CreateDIBSection n’utilise pas les paramètres BITMAPINFOHEADERbiXPelsPerMeter ou biYPelsPerMeter et ne fournit pas d’informations de résolution dans la structure BITMAPINFO .

Vous devez vous assurer que le sous-système GDI a terminé tout dessin dans une bitmap créée par CreateDIBSection avant de dessiner vous-même dans l’image bitmap. L’accès à la bitmap doit être synchronisé. Pour ce faire, appelez la fonction GdiFlush . Cela s’applique à toute utilisation du pointeur vers les valeurs de bits bitmap, y compris le passage du pointeur dans les appels à des fonctions telles que SetDIBits.

ICM: Aucune gestion des couleurs n’est effectuée.

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