Funzione CreateBitmap (wingdi.h)

Articolo
03/08/2023

La funzione CreateBitmap crea una bitmap con la larghezza, l'altezza e il formato di colore specificati (piani di colore e bit per pixel).

Sintassi

HBITMAP CreateBitmap(
  [in] int        nWidth,
  [in] int        nHeight,
  [in] UINT       nPlanes,
  [in] UINT       nBitCount,
  [in] const VOID *lpBits
);

Parametri

[in] nWidth

Larghezza bitmap, in pixel.

[in] nHeight

Altezza bitmap, in pixel.

[in] nPlanes

Numero di piani di colore usati dal dispositivo.

[in] nBitCount

Numero di bit necessari per identificare il colore di un singolo pixel.

[in] lpBits

Puntatore a una matrice di dati colore utilizzati per impostare i colori in un rettangolo di pixel. Ogni riga di analisi nel rettangolo deve essere allineata a parole (le righe di analisi non allineate alle parole devono essere riempite con zeri). Le dimensioni del buffer previste, cj, possono essere calcolate usando la formula:

cj = (((nWidth * nPlanes * nBitCount + 15) >> 4) << 1) * nHeight;

Se questo parametro è NULL, il contenuto della nuova bitmap non è definito.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per una bitmap.

Se la funzione ha esito negativo, il valore restituito è NULL.

Questa funzione può restituire il valore seguente.

Codice restituito	Descrizione
ERROR_INVALID_BITMAP	La dimensione calcolata della bitmap è minore di zero.

Commenti

La funzione CreateBitmap crea una bitmap dipendente dal dispositivo.

Dopo aver creato una bitmap, è possibile selezionarla in un contesto di dispositivo chiamando la funzione SelectObject . Tuttavia, la bitmap può essere selezionata solo in un contesto di dispositivo se la bitmap e il controller di dominio hanno lo stesso formato.

La funzione CreateBitmap può essere usata per creare bitmap a colori. Per motivi di prestazioni, tuttavia, le applicazioni devono usare CreateBitmap per creare bitmap monocromatiche e CreateCompatibleBitmap per creare bitmap a colori. Ogni volta che viene selezionata una bitmap a colori restituita da CreateBitmap in un contesto di dispositivo, il sistema verifica che la bitmap corrisponda al formato del contesto di dispositivo in cui viene selezionata. Poiché CreateCompatibleBitmap accetta un contesto di dispositivo, restituisce una bitmap con lo stesso formato del contesto di dispositivo specificato. Di conseguenza, le chiamate successive a SelectObject sono più veloci con una bitmap a colori da CreateCompatibleBitmap rispetto a una bitmap a colori restituita da CreateBitmap.

Se la bitmap è monocromatica, gli zeri rappresentano il colore di primo piano e quelli rappresentano il colore di sfondo per il contesto del dispositivo di destinazione.

Se un'applicazione imposta i parametri nWidth o nHeight su zero, CreateBitmap restituisce l'handle a una bitmap monocromatica a 1 per 1 pixel.

Quando la bitmap non è più necessaria, chiamare la funzione DeleteObject per eliminarla.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wingdi.h (include Windows.h)
Libreria	Gdi32.lib
DLL	Gdi32.dll