Fungsi StretchDIBits (wingdi.h)

Artikel
03/04/2024

Fungsi StretchDIBits menyalin data warna untuk persegi panjang piksel dalam gambar DIB, JPEG, atau PNG ke persegi tujuan yang ditentukan. Jika persegi panjang tujuan lebih besar dari persegi panjang sumber, fungsi ini membentangkan baris dan kolom data warna agar pas dengan persegi tujuan. Jika persegi panjang tujuan lebih kecil dari persegi panjang sumber, fungsi ini memadatkan baris dan kolom dengan menggunakan operasi raster yang ditentukan.

Sintaks

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Parameter

[in] hdc

Handel ke konteks perangkat tujuan.

[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] DestWidth

Lebar, dalam unit logis, dari persegi tujuan.

[in] DestHeight

Tinggi, dalam unit logis, persegi panjang tujuan.

[in] xSrc

Koordinat x, dalam piksel, persegi panjang sumber dalam gambar.

[in] ySrc

Koordinat y, dalam piksel, persegi panjang sumber dalam gambar.

[in] SrcWidth

Lebar, dalam piksel, persegi panjang sumber dalam gambar.

[in] SrcHeight

Tinggi, dalam piksel, persegi panjang sumber dalam gambar.

[in] lpBits

Penunjuk ke bit gambar, yang disimpan sebagai array byte. Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in] lpbmi

Penunjuk ke struktur BITMAPINFO yang berisi informasi tentang DIB.

[in] iUsage

Menentukan apakah anggota bmiColors dari struktur BITMAPINFO disediakan dan, jika demikian, apakah bmiColors berisi nilai atau indeks merah, hijau, biru (RGB) eksplisit. Parameter iUsage harus menjadi salah satu nilai berikut.

Nilai	Makna
DIB_PAL_COLORS	Array berisi indeks 16-bit ke dalam palet logis konteks perangkat sumber.
DIB_RGB_COLORS	Tabel warna berisi nilai RGB harfiah.

Untuk informasi lebih lanjut, lihat bagian Keterangan.

[in] rop

Kode operasi raster yang menentukan bagaimana piksel sumber, kuas konteks perangkat tujuan saat ini, dan piksel tujuan akan digabungkan untuk membentuk gambar baru. Untuk daftar beberapa kode operasi raster umum, lihat BitBlt.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah baris pemindaian yang disalin. Perhatikan bahwa nilai ini bisa negatif untuk konten yang dicerminkan.

Jika fungsi gagal, atau tidak ada baris pemindaian yang disalin, nilai yang dikembalikan adalah 0.

Jika driver tidak dapat mendukung gambar file JPEG atau PNG yang diteruskan ke StretchDIBits, 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 StretchDIBits.

Keterangan

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

StretchDIBits membuat gambar cermin bitmap jika tanda-tanda parameter nSrcWidth dan nDestWidth , atau jika parameter nSrcHeight dan nDestHeight berbeda. Jika nSrcWidth dan nDestWidth memiliki tanda yang berbeda, fungsi ini membuat gambar cermin bitmap di sepanjang sumbu x. Jika nSrcHeight dan nDestHeight memiliki tanda yang berbeda, fungsi membuat gambar cermin bitmap di sepanjang sumbu y.

StretchDIBits membuat gambar top-down jika tanda anggota biHeight dari struktur BITMAPINFOHEADER untuk DIB negatif. Untuk contoh kode, lihat Mengukur GAMBAR JPEG atau PNG.

Fungsi ini memungkinkan gambar JPEG atau PNG diteruskan sebagai gambar sumber. Bagaimana setiap parameter digunakan tetap sama, kecuali:

Jika anggota biCompressionBITMAPINFOHEADER BI_JPEG atau BI_PNG, lpBits menunjuk ke buffer yang masing-masing berisi gambar JPEG atau PNG. Anggota biSizeImage dari struktur BITMAPINFOHEADER menentukan ukuran buffer. Parameter iUsage harus diatur ke DIB_RGB_COLORS. Parameter dwRop harus diatur ke SRCCOPY.
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 StretchDIBits.

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 lpBitsInfo memiliki BITMAPV4HEADER yang menentukan anggota gamma dan titik akhir, atau BITMAPV5HEADER yang menentukan anggota gamma dan titik akhir atau anggota profileData dan 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 Mengukur Gambar 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