Fungsi SetDIBitsToDevice (wingdi.h)

Artikel
03/08/2023

Fungsi SetDIBitsToDevice mengatur piksel dalam persegi panjang yang ditentukan pada perangkat yang terkait dengan konteks perangkat tujuan menggunakan data warna dari gambar DIB, JPEG, atau PNG.

Sintaks

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Parameter

[in] hdc

Handel ke konteks perangkat.

[in] xDest

Koordinat x, dalam unit logis, dari sudut kiri atas persegi tujuan.

[in] yDest

Koordinat y, dalam unit logis, dari sudut kiri atas persegi panjang tujuan.

[in] w

Lebar, dalam unit logis, gambar.

[in] h

Tinggi, dalam unit logis, dari gambar.

[in] xSrc

Koordinat x, dalam unit logis, dari sudut kiri bawah gambar.

[in] ySrc

Koordinat y, dalam unit logis, dari sudut kiri bawah gambar.

[in] StartScan

Baris pemindaian awal dalam gambar.

[in] cLines

Jumlah baris pemindaian DIB yang terkandung dalam array yang diacu oleh parameter lpvBits .

[in] lpvBits

Penunjuk ke data warna yang disimpan sebagai array byte. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] lpbmi

Penunjuk ke struktur BITMAPINFO yang berisi informasi tentang DIB.

[in] ColorUse

Menunjukkan apakah anggota bmiColors dari struktur BITMAPINFO berisi nilai atau indeks merah, hijau, biru (RGB) eksplisit ke dalam palet. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Parameter fuColorUse harus menjadi salah satu nilai berikut.

Nilai	Makna
DIB_PAL_COLORS	Tabel warna terdiri dari array indeks 16-bit ke dalam palet logika yang saat ini dipilih.
DIB_RGB_COLORS	Tabel warna berisi nilai RGB harfiah.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah baris pemindaian yang ditetapkan.

Jika garis pemindaian nol diatur (seperti ketika dwHeight adalah 0) atau fungsi gagal, fungsi mengembalikan nol.

Jika driver tidak dapat mendukung gambar file JPEG atau PNG yang diteruskan ke SetDIBitsToDevice, fungsi akan gagal dan mengembalikan GDI_ERROR. Jika kegagalan terjadi, aplikasi harus kembali pada dukungan JPEG atau PNG sendiri untuk mendekompresi gambar menjadi bitmap, lalu meneruskan bitmap ke SetDIBitsToDevice.

Keterangan

Kecepatan gambar bitmap optimal diperoleh ketika bitmap bit adalah indeks ke dalam palet sistem.

Aplikasi dapat mengambil warna dan indeks palet sistem dengan memanggil fungsi GetSystemPaletteEntries . Setelah warna dan indeks diambil, aplikasi dapat membuat DIB. Untuk informasi selengkapnya tentang palet sistem, lihat Warna.

Baris pemindaian harus diselaraskan pada DWORD kecuali untuk bitmap terkompresi RLE.

Asal DIB bawah-atas adalah sudut kiri bawah bitmap; asal DIB atas bawah adalah sudut kiri atas.

Untuk mengurangi jumlah memori yang diperlukan untuk mengatur bit dari DIB besar pada permukaan perangkat, aplikasi dapat membagi output dengan berulang kali memanggil SetDIBitsToDevice, menempatkan bagian bitmap yang berbeda ke dalam array lpvBits setiap kali. Nilai parameter uStartScan dan cScanLines mengidentifikasi bagian bitmap yang terkandung dalam array lpvBits .

Fungsi SetDIBitsToDevice mengembalikan kesalahan jika dipanggil oleh proses yang berjalan di latar belakang saat sesi MS-DOS layar penuh berjalan di latar depan.

Jika anggota biCompressionBITMAPINFOHEADER BI_JPEG atau BI_PNG, lpvBits menunjuk ke buffer yang berisi gambar JPEG atau PNG. Anggota biSizeImage menentukan ukuran buffer. Parameter fuColorUse harus diatur ke DIB_RGB_COLORS.
Untuk memastikan penampungan metafile yang tepat saat mencetak, aplikasi harus memanggil escape CHECKJPEGFORMAT atau CHECKPNGFORMAT untuk memverifikasi bahwa printer mengenali gambar JPEG atau PNG, masing-masing, sebelum memanggil SetDIBitsToDevice.

ICM: Manajemen warna dilakukan jika manajemen warna telah diaktifkan dengan panggilan ke SetICMMode dengan parameter iEnableICM diatur ke ICM_ON. Jika bitmap yang ditentukan oleh lpbmi memiliki BITMAPV4HEADER yang menentukan anggota gamma dan titik akhir, atau BITMAPV5HEADER yang menentukan anggota gamma dan titik akhir atau profilData dan anggota profileSize, maka panggilan memperlakukan piksel bitmap seperti yang dinyatakan dalam ruang warna yang dijelaskan oleh anggota tersebut, bukan di ruang warna sumber konteks perangkat.

Contoh

Misalnya, lihat Menguji Printer untuk Dukungan JPEG atau PNG.

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