Fungsi CreateDIBSection (wingdi.h)

Artikel
03/04/2024

Fungsi CreateDIBSection membuat DIB yang dapat ditulis aplikasi secara langsung. Fungsi ini memberi Anda penunjuk ke lokasi nilai bitmap bit. Anda dapat menyediakan handel ke objek pemetaan file yang akan digunakan fungsi untuk membuat bitmap, atau Anda dapat membiarkan sistem mengalokasikan memori untuk bitmap.

Sintaks

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

Parameter

[in] hdc

Handel ke konteks perangkat. Jika nilai iUsage DIB_PAL_COLORS, fungsi menggunakan palet logis konteks perangkat ini untuk menginisialisasi warna DIB.

[in] pbmi

Penunjuk ke struktur BITMAPINFO yang menentukan berbagai atribut DIB, termasuk dimensi dan warna bitmap.

[in] usage

Jenis data yang terkandung dalam anggota array bmiColors dari struktur BITMAPINFO yang diacu oleh pbmi (baik indeks palet logis atau nilai RGB harfiah). Nilai berikut ditentukan.

Nilai	Makna
DIB_PAL_COLORS	Anggota bmiColors adalah array indeks 16-bit ke dalam palet logis konteks perangkat yang ditentukan oleh hdc.
DIB_RGB_COLORS	Struktur BITMAPINFO berisi array nilai RGB harfiah.

[out] ppvBits

Penunjuk ke variabel yang menerima penunjuk ke lokasi nilai bit DIB.

[in] hSection

Handel ke objek pemetaan file yang akan digunakan fungsi untuk membuat DIB. Parameter ini bisa NULL.

Jika hSection bukan NULL, itu harus menjadi handel ke objek pemetaan file yang dibuat dengan memanggil fungsi CreateFileMapping dengan bendera PAGE_READWRITE atau PAGE_WRITECOPY. Bagian DIB baca-saja tidak didukung. Handel yang dibuat dengan cara lain akan menyebabkan CreateDIBSection gagal.

Jika hSection bukan NULL, fungsi CreateDIBSection menemukan nilai bitmap bit pada offset dwOffset dalam objek pemetaan file yang dirujuk oleh hSection. Aplikasi nantinya dapat mengambil handel hSection dengan memanggil fungsi GetObject dengan HBITMAP yang dikembalikan oleh CreateDIBSection.

Jika hSectionNULL, sistem mengalokasikan memori untuk DIB. Dalam hal ini, fungsi CreateDIBSection mengabaikan parameter dwOffset . Aplikasi nantinya tidak dapat memperoleh handel ke memori ini. Anggota dshSection dari struktur DIBSECTION yang diisi dengan memanggil fungsi GetObject akan null.

[in] offset

Offset dari awal objek pemetaan file yang direferensikan oleh hSection di mana penyimpanan untuk nilai bitmap bit akan dimulai. Nilai ini diabaikan jika hSection ADALAH NULL. Nilai bitmap bit diselaraskan pada batas kata ganda, sehingga dwOffset harus berupa kelipatan ukuran DWORD.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke DIB yang baru dibuat, dan *ppvBits menunjuk ke nilai bitmap bit.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL, dan *ppvBits adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

GetLastError dapat mengembalikan nilai berikut:

Kode kesalahan	Deskripsi
ERROR_INVALID_PARAMETER	Satu atau beberapa parameter input tidak valid.

Keterangan

Seperti disebutkan di atas, jika hSectionNULL, sistem mengalokasikan memori untuk DIB. Sistem menutup handel ke memori tersebut ketika Anda kemudian menghapus DIB dengan memanggil fungsi DeleteObject . Jika hSection bukan NULL, Anda harus menutup handel memori hSection sendiri setelah memanggil DeleteObject untuk menghapus bitmap.

Anda tidak dapat menempelkan bagian DIB dari satu aplikasi ke aplikasi lain.

CreateDIBSection tidak menggunakan parameter BITMAPINFOHEADERbiXPelsPerMeter atau biYPelsPerMeter dan tidak akan memberikan informasi resolusi dalam struktur BITMAPINFO .

Anda perlu menjamin bahwa subsistem GDI telah menyelesaikan gambar apa pun ke bitmap yang dibuat oleh CreateDIBSection sebelum Anda menggambar sendiri ke bitmap. Akses ke bitmap harus disinkronkan. Lakukan ini dengan memanggil fungsi GdiFlush . Ini berlaku untuk penggunaan penunjuk apa pun ke nilai bitmap bit, termasuk meneruskan penunjuk dalam panggilan ke fungsi seperti SetDIBits.

ICM: Tidak ada manajemen warna yang dilakukan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	wingdi.h (sertakan Windows.h)
Pustaka	Gdi32.lib
DLL	Gdi32.dll