Funzione CreateDIBSection (wingdi.h)

Articolo
03/09/2024

La funzione CreateDIBSection crea un DIB che le applicazioni possono scrivere direttamente. La funzione fornisce un puntatore alla posizione dei valori di bit bitmap. È possibile fornire un handle a un oggetto di mapping di file usato dalla funzione per creare la bitmap oppure consentire al sistema di allocare la memoria per la bitmap.

Sintassi

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

Parametri

[in] hdc

Handle per un contesto di dispositivo. Se il valore di iUsage è DIB_PAL_COLORS, la funzione usa la tavolozza logica del contesto del dispositivo per inizializzare i colori DIB.

[in] pbmi

Puntatore a una struttura BITMAPINFO che specifica vari attributi del DIB, incluse le dimensioni e i colori bitmap.

[in] usage

Tipo di dati contenuti nel membro della matrice bmiColors della struttura BITMAPINFO a cui punta pbmi (indici della tavolozza logica o valori RGB letterali). I valori seguenti sono definiti.

Valore	Significato
DIB_PAL_COLORS	Il membro bmiColors è una matrice di indici a 16 bit nel riquadro logico del contesto del dispositivo specificato da hdc.
DIB_RGB_COLORS	La struttura BITMAPINFO contiene una matrice di valori RGB letterali.

[out] ppvBits

Puntatore a una variabile che riceve un puntatore alla posizione dei valori di bit DIB.

[in] hSection

Handle a un oggetto di mapping di file che verrà usato dalla funzione per creare il DIB. Questo parametro può essere NULL.

Se hSection non è NULL, deve essere un handle per un oggetto di mapping di file creato chiamando la funzione CreateFileMapping con il flag PAGE_READWRITE o PAGE_WRITECOPY. Le sezioni DIB di sola lettura non sono supportate. Gli handle creati da altri mezzi causano l'esito negativo di CreateDIBSection .

Se hSection non è NULL, la funzione CreateDIBSection individua i valori di bit bitmap in offset dwOffset nell'oggetto di mapping file a cui fa riferimento hSection. Un'applicazione può in seguito recuperare l'handle hSection chiamando la funzione GetObject con HBITMAP restituita da CreateDIBSection.

Se hSection è NULL, il sistema alloca la memoria per DIB. In questo caso, la funzione CreateDIBSection ignora il parametro dwOffset . Un'applicazione non può ottenere in un secondo momento un handle per questa memoria. Il membro dshSection della struttura DIBSECTION compilato chiamando la funzione GetObject sarà NULL.

[in] offset

L'offset dall'inizio dell'oggetto di mapping file a cui fa riferimento hSection dove l'archiviazione per i valori di bit bitmap deve iniziare. Questo valore viene ignorato se hSection è NULL. I valori di bit bitmap sono allineati ai limiti doubleword, quindi dwOffset deve essere un multiplo delle dimensioni di un DWORD.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per il DIB appena creato e *ppvBits punta ai valori di bit bitmap.

Se la funzione ha esito negativo, il valore restituito è NULL e *ppvBits è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

GetLastError può restituire il valore seguente:

Codice di errore	Descrizione
ERROR_INVALID_PARAMETER	Uno o più parametri di input non sono validi.

Commenti

Come indicato in precedenza, se hSection è NULL, il sistema alloca la memoria per il DIB. Il sistema chiude l'handle a tale memoria quando si elimina in seguito il DIB chiamando la funzione DeleteObject . Se hSection non è NULL, è necessario chiudere l'handle di memoria hSection manualmente dopo aver chiamato DeleteObject per eliminare la bitmap.

Non è possibile incollare una sezione DIB da un'applicazione a un'altra applicazione.

CreateDIBSection non usa i parametri BITMAPINFOHEADERbiXPelsPerMeter o biYPelsPerMeter e non fornisce informazioni sulla risoluzione nella struttura BITMAPINFO .

È necessario garantire che il sottosistema GDI abbia completato qualsiasi disegno in una bitmap creata da CreateDIBSection prima di disegnare alla bitmap. L'accesso alla bitmap deve essere sincronizzato. Eseguire questa operazione chiamando la funzione GdiFlush . Ciò si applica a qualsiasi uso del puntatore ai valori di bit bitmap, incluso il passaggio del puntatore nelle chiamate alle funzioni, ad esempio SetDIBits.

ICM: Non viene eseguita alcuna gestione dei colori.

Requisiti

Requisito	Valore
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