CreateDIBSection, fonction (wingdi.h)

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.

[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 :

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

Voir aussi

BITMAPINFO

Fonctions bitmap

Vue d’ensemble des bitmaps

CreateFileMapping

DIBSECTION

DeleteObject

GdiFlush

GetDIBColorTable

Getobject

SetDIBColorTable

SetDIBits