Menerapkan IWICBitmapEncoder
IWICBitmapEncoder
Antarmuka ini adalah mitra antarmuka IWICBitmapDecoder dan merupakan titik awal untuk mengodekan file gambar. Sama seperti IWICBitmapDecoder digunakan untuk mengambil properti tingkat kontainer dan bingkai individual dari kontainer gambar, IWICBitmapEncoder digunakan untuk mengatur properti tingkat kontainer dan menserialisasikan bingkai gambar individual ke dalam kontainer. Anda menerapkan antarmuka ini pada kelas encoder tingkat kontainer Anda.
interface IWICBitmapEncoder : public IUnknown
{
// Required methods
HRESULT Initialize ( IStream *pIStream,
WICBitmapEncoderCacheOption cacheOption );
HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
HRESULT GetEncoderInfo ( IWICBitmapEncoderInfo **pIEncoderInfo );
HRESULT CreateNewFrame ( IWICBitmapFrameEncode **ppIFrameEncode,
IPropertyBag2 **ppIEncoderOptions );
HRESULT Commit ( void );
// Optional methods
HRESULT SetPreview ( IWICBitmapSource *pIPreview );
HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
HRESULT SetColorContexts ( UINT cCount,
IWICColorContext **ppIColorContext );
HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter
**ppIMetadataQueryWriter );
HRESULT SetPalette ( IWICPalette *pIPalette);
};
Seperti yang dibahas dalam Mengimplementasikan IWICBitmapDecoder, beberapa format gambar memiliki gambar mini global, konteks warna, atau metadata, sementara banyak format gambar hanya menyediakan ini berdasarkan per bingkai. Oleh karena itu, metode untuk mengatur ini bersifat opsional pada IWICBitmapEncoder, tetapi diperlukan pada IWICBitmapFrameEncode. Kita akan membahas metode yang opsional pada IWICBitmapEncoder di bagian IWICBitmapFrameEncode, tempat metode tersebut paling umum diterapkan.
Jika Anda tidak mendukung gambar mini global, kembalikan WINCODEC_ERR_CODECNOTHUMBNAIL dari metode SetThumbnail pada IWICBitmapEncoder. Jika Anda tidak mendukung palet tingkat kontainer, atau jika gambar yang Anda kodekan tidak memiliki format terindeks, kembalikan WINCODEC_ERR_PALETTEUNAVAILABLE dari metode SetPalette. Untuk metode lain yang tidak didukung, kembalikan WINCODEC_ERR_UNSUPPORTEDOPERATION.
Initialize
Inisialisasi adalah metode pertama yang dipanggil pada IWICBitmapEncoder setelah dibuat. Aliran gambar diteruskan ke encoder, dan penelepon dapat secara opsional menentukan opsi cache. Dalam kasus dekoder, aliran bersifat baca-saja, tetapi aliran yang diteruskan ke encoder adalah aliran yang dapat ditulis, di mana encoder akan membuat serial semua data dan metadata gambar. Opsi cache pada encoder juga berbeda.
enum WICBitmapEncoderCacheOption
{
WICBitmapEncoderCacheInMemory,
WICBitmapEncoderCacheTempFile,
WICBitmapEncoderNoCache
}
Aplikasi ini memiliki pilihan untuk meminta encoder untuk menyimpan data gambar dalam memori, menyimpannya dalam file sementara, atau menulisnya langsung ke file disk tanpa penembolokan. Ketika diminta untuk menyimpan data dalam file sementara, encoder harus membuat file sementara pada disk dan menulis langsung ke file tersebut tanpa penembolokan dalam memori. Ketika penelepon memilih opsi tanpa cache, setiap bingkai harus diterapkan secara berurutan sebelum bingkai berikutnya dapat dibuat.
GetContainerFormat
GetContainerFormat diimplementasikan dengan cara yang sama seperti metode GetContainerFormat dalam Mengimplementasikan IWICBitmapDecoder.
GetEncoderInfo
GetEncoderInfo mengembalikan objek IWICBitmapEncoderInfo . Untuk mendapatkan objek IWICBitmapEncoderInfo , cukup teruskan GUID encoder Anda ke metode CreateComponentInfo pada IWICImagingFactory, lalu minta antarmuka IWICBitmapEncoderInfo di atasnya.
Lihat contoh dalam Menerapkan IWICBitmapDecoder di bawah GetDecoderInfo.
BuatNewFrame
CreateNewFrame adalah mitra encoder GetFrame di IWICBitmapDecoder. Metode ini mengembalikan objek IWICBitmapFrameEncode , yang merupakan objek yang benar-benar menserialisasikan data gambar untuk bingkai tertentu dalam kontainer.
Salah satu manfaat Windows Imaging Component (WIC) adalah menyediakan lapisan abstraksi untuk aplikasi yang memungkinkan mereka bekerja dengan semua format gambar dengan cara yang sama. Namun, tidak semua format gambar sama persis. Beberapa format gambar memiliki kemampuan yang tidak dimiliki orang lain. Agar aplikasi dapat memanfaatkan kemampuan unik tersebut, perlu menyediakan cara bagi codec untuk mengeksposnya. Ini adalah tujuan opsi encoder. Jika codec Anda mendukung opsi encoder apa pun, Anda harus membuat objek IPropertyBag2 yang mengekspos opsi encoder yang Anda dukung, dan mengembalikannya dalam parameter ppIEncoderOptions dari metode ini. Pemanggil kemudian dapat menggunakan objek IPropertyBag2 ini untuk menentukan opsi encoder apa yang didukung codec Anda. Jika pemanggil ingin menentukan nilai untuk salah satu opsi encoder yang didukung, mereka akan menetapkan nilai ke properti yang relevan di objek IPropertyBag2 dan meneruskannya ke objek IWICBitmapFrameEncode yang baru dibuat dalam metode Inisialisasinya.
Untuk membuat instans objek IPropertyBag2 , Anda harus terlebih dahulu membuat struktur PROPBAG2 untuk menentukan setiap opsi encoder yang didukung encoder Anda dan jenis datanya untuk setiap properti. Kemudian Anda harus menerapkan objek IPropertyBag2 yang memberlakukan rentang nilai untuk setiap properti pada tulis, dan mendamaikan nilai yang bertentangan atau tumpang tindih. Untuk set sederhana opsi encoder yang tidak bertentangan, Anda dapat memanggil metode CreateEncoderPropertyBag , yang akan membuat objek IPropertyBag2 sederhana menggunakan properti yang Anda tentukan dalam struktur PROPBAG2 Anda. Anda masih harus memberlakukan rentang nilai. Untuk opsi encoder yang lebih canggih, atau jika Anda perlu mendamaikan nilai yang bertentangan, Anda harus menulis implementasi IPropertyBag2 Anda sendiri.
UINT cuiPropertyCount = 0;
IPropertyBag2* pPropertyBag = NULL;
PROPBAG2* pPropBagOptions;
HRESULT hr;
// Insert code here to initialize piPropertyBag with the
// supported options for your encoder, and to initialize
// cuiPropertyCount to the number of encoder option properties
// you are exposing.
...
hr = pComponentFactory->CreateEncoderPropertyBag(
pPropBagOptions, cuiPropertyCount, &pPropertyBag);
WIC menyediakan sekumpulan kecil opsi encoder kanonis yang digunakan oleh beberapa format gambar umum. Semua opsi encoder kanonis bersifat opsional, dan codec tidak diperlukan untuk mendukung salah satunya. Alasan mereka disediakan sebagai opsi kanonis adalah karena banyak aplikasi mengekspos antarmuka pengguna bagi pengguna untuk menentukan opsi ini saat menyimpan file gambar dalam format yang mendukungnya. Menyediakan cara kanonis untuk menentukan opsi ini memudahkan aplikasi untuk mengkomunikasikannya ke encoder dengan cara yang konsisten. Opsi encoder kanonis tercantum dalam tabel berikut.
| Opsi Encoder | VARTYPE | Rentang Nilai |
|---|---|---|
| Lossless | VT_BOOL | True/False |
| ImageQuality | VT_R4 | 0.0-1.0 |
| CompressionQuality | VT_R4 | 0.0-1.0 |
| BitmapTransform | VT_UI1 | WICBitmapTransformOptions |
Jika codec Anda mendukung pengodean lossless, Anda harus mengekspos opsi encoder Lossless sebagai cara bagi aplikasi untuk meminta agar gambar dikodekan tanpa kehilangan. Jika penelepon mengatur properti ini ke True, Anda harus mengabaikan opsi ImageQuality dan mengodekan gambar tanpa kehilangan.
Opsi ImageQuality memungkinkan aplikasi untuk menentukan tingkat keakuratan untuk mengodekan gambar. Opsi ini memungkinkan pengguna melakukan tradeoff antara kualitas gambar versus kecepatan dan/atau ukuran file. JPEG adalah contoh format gambar yang mendukung tradeoff ini. Nilai 0,0 menunjukkan bahwa keakuratan sangat penting dan encoder harus menggunakan algoritma yang paling rugi. Nilai 1,0 menunjukkan bahwa keakuratan adalah yang paling penting dan encoder harus mempertahankan keakuratan tertinggi yang mungkin. (Tergantung pada codec Anda, ini mungkin identik dengan opsi Lossless. Namun, jika codec Anda mendukung pengodean lossless, dan jika opsi Lossless diatur ke True, opsi ImageQuality harus diabaikan.)
Opsi CompressionQuality memungkinkan aplikasi menentukan efisiensi pemadatan untuk digunakan saat mengodekan gambar. Algoritma yang sangat efisien dapat menghasilkan file gambar yang lebih kecil dengan kualitas yang sama dengan algoritma kompresi yang kurang efisien, tetapi mungkin membutuhkan waktu lebih lama untuk dikodekan. Opsi ini memungkinkan pengguna menentukan tradeoff antara ukuran file versus kecepatan pengodean, sambil mempertahankan tingkat kualitas yang sama. TIFF adalah contoh format gambar yang mendukung tradeoff ini. (Perhatikan bahwa format seperti JPEG mendukung tingkat kompresi yang berbeda, tetapi tingkat kompresi yang lebih tinggi menghasilkan kualitas gambar yang lebih rendah. Oleh karena itu, format gambar JPEG akan mengekspos opsi ImageQuality daripada opsi CompressionQuality.) Nilai 0,0 untuk opsi ini menunjukkan bahwa Anda harus memadatkan gambar secepat mungkin, tanpa mengurangi keakuratan, dengan mengorbankan ukuran file yang lebih besar. Nilai 1.0 menunjukkan bahwa Anda harus membuat ukuran file sekecil mungkin (pada tingkat kualitas yang sama), terlepas dari berapa lama waktu yang diperlukan untuk mengodekannya. Codec dapat mendukung opsi ImageQuality dan opsi CompressionQuality, di mana opsi ImageQuality menentukan tingkat kerugian yang dapat diterima, dan opsi CompressionQuality menawarkan tradeoff ukuran/kecepatan pada tingkat kualitas yang ditentukan.
Opsi BitmapTransform menyediakan cara bagi pemanggil untuk menentukan sudut rotasi atau orientasi flip vertikal atau horizontal saat pengodean. Enum WICBitmapTransformOptions yang digunakan untuk menentukan transformasi yang diminta adalah enum yang sama yang digunakan saat meminta transformasi selama decoding melalui antarmuka IWICBitmapSourceTransform.
Perhatikan bahwa encoder tidak terbatas pada opsi encoder kanonis. Tujuan opsi encoder adalah untuk memungkinkan encoder mengekspos kemampuannya, dan tidak ada batasan untuk jenis kemampuan yang dapat Anda ekspos. Pastikan opsi encoder Anda dikodekan dengan baik. Meskipun aplikasi dapat menggunakan tas properti yang Anda kembalikan dari metode ini untuk menemukan nama, jenis, dan rentang nilai untuk opsi yang Anda dukung, satu-satunya cara bagi mereka untuk mengetahui maknanya, atau cara mengeksposnya di antarmuka pengguna, adalah dari dokumentasi Anda.
Menjalankan
Penerapan adalah metode yang Anda panggil setelah semua data gambar dan metadata telah diserialisasikan ke dalam aliran. Anda harus menggunakan metode ini untuk membuat serialisasi data gambar Pratinjau ke dalam aliran, dan gambar mini global, metadata, palet, atau item lainnya, jika berlaku. Metode ini tidak boleh menutup aliran file, karena aplikasi yang membuka aliran diharapkan untuk menutupnya.
Bagian pada metode IWICBitmapFrameEncode:Commit memiliki detail tentang bagaimana IWICBitmapEncoderCacheOptions memengaruhi perilaku metode ini.
SetPreview
SetPreview digunakan untuk membuat pratinjau gambar. Meskipun tidak benar-benar diperlukan bahwa setiap gambar memiliki pratinjau, sangat disarankan. Kamera dan pemindai digital modern menghasilkan gambar resolusi yang sangat tinggi, yang cenderung sangat besar dan, akibatnya, membutuhkan waktu pemrosesan yang signifikan untuk mendekode. Gambar dari kamera generasi berikutnya akan lebih besar. Ada baiknya untuk memberikan versi gambar dengan resolusi yang lebih kecil dan lebih rendah, biasanya dalam format JPEG, yang dapat dengan cepat didekodekan dan ditampilkan "seketika" ketika pengguna memintanya. Aplikasi dapat meminta pratinjau sebelum meminta gambar aktual untuk didekodekan untuk memberikan pengalaman yang lebih baik bagi pengguna, dan menunjukkan kepada mereka representasi ukuran layar gambar saat orang yang menunggu untuk mendekode gambar yang sebenarnya. Meskipun codec harus menyediakan pratinjau, codec yang tidak mendukung IWICBitmapSourceTransform pasti harus melakukannya.
Jika Anda memberikan pratinjau JPEG, Anda tidak perlu menulis encoder JPEG untuk mengodekannya. Anda harus mendelegasikan ke encoder JPEG yang dikirim dengan platform WIC untuk mengodekan pratinjau dan gambar mini.
Topik terkait
-
Referensi
-
Konseptual
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk