Menerapkan IWICBitmapEncoder
-
IWICBitmapEncoder
- Inisialisasi
- GetContainerFormat
- GetEncoderInfo
- BuatBingkaiBaru
- Komitmen
- SetPreview
- Topik terkait
IWICBitmapEncoder
- Inisialisasi
- GetContainerFormat
- GetEncoderInfo
- BuatBingkaiBaru
- Komitmen
- SetPreview
Antarmuka ini adalah mitra antarmukaIWICBitmapDecoder 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 Menerapkan IWICBitmapDecoder, beberapa format gambar memiliki thumbnail global, konteks warna, atau metadata, sementara banyak format gambar menyediakan ini hanya pada dasar 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 diimplementasikan.
Jika Anda tidak mendukung thumbnail 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 apa pun yang tidak didukung, kembalikan WINCODEC_ERR_UNSUPPORTEDOPERATION.
Menginisialisasi
Menginisialisasi adalah metode pertama yang dipanggil pada IWICBitmapEncoder setelah diinstansiasi. Aliran gambar diteruskan ke encoder, dan pemanggil 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 menserialisasikan semua data gambar dan metadata. Opsi cache pada encoder juga berbeda.
enum WICBitmapEncoderCacheOption
{
WICBitmapEncoderCacheInMemory,
WICBitmapEncoderCacheTempFile,
WICBitmapEncoderNoCache
}
Aplikasi ini memiliki opsi untuk meminta encoder menyimpan data gambar dalam memori, menyimpannya dalam file sementara, atau menuliskannya langsung ke file disk tanpa caching. Ketika diminta untuk menyimpan data dalam file sementara, encoder harus membuat file sementara pada disk dan menulis langsung pada file itu tanpa penggunaan memori. Ketika pemanggil memilih opsi tanpa cache, setiap bingkai harus disimpan dalam urutan yang tepat sebelum bingkai berikutnya dapat dibuat.
GetContainerFormat
GetContainerFormat diimplementasikan dengan cara yang sama seperti metode GetContainerFormat dalam Implementasi IWICBitmapDecoder.
GetEncoderInfo
GetEncoderInfo mengembalikan objekIWICBitmapEncoderInfo. Untuk mendapatkan objek IWICBitmapEncoderInfo, cukup teruskan GUID encoder Anda ke metodeCreateComponentInfo pada IWICImagingFactory, lalu minta antarmuka IWICBitmapEncoderInfo di atasnya.
Lihat contoh dalam Menerapkan IWICBitmapDecoder di bawah GetDecoderInfo.
BuatBingkaiBaru
CreateNewFrame adalah mitra encoder dari GetFrame pada IWICBitmapDecoder. Metode ini mengembalikan objek IWICBitmapFrameEncode, yang merupakan objek yang menyerialkan data gambar untuk bingkai tertentu di 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 dari 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 metode ini. Pemanggil kemudian dapat menggunakan objek IPropertyBag2 ini untuk menentukan opsi encoder apa yang didukung codec Anda. Jika penelepon 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 saat menulis, 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 tetap 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 | Tipe Variabel | Rentang Nilai |
|---|---|---|
| tanpa kehilangan | VT_BOOL | Benar/Salah |
| ImageQuality | VT_R4 | 0.0-1.0 |
| Kualitas Kompresi | VT_R4 | 0.0-1.0 |
| BitmapTransform | VT_UI1 | WICBitmapTransformOptions |
Jika codec Anda mendukung pengodean tanpa kehilangan, Anda harus menyediakan opsi pengode 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 secara tanpa kehilangan.
Opsi ImageQuality memungkinkan aplikasi 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 berisiko rendah dan encoder harus menggunakan algoritma dengan tingkat kehilangan tertinggi. 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 tanpa kehilangan, dan jika opsi Lossless diatur ke True, opsi ImageQuality harus diabaikan.)
Opsi CompressionQuality memungkinkan aplikasi menentukan efisiensi kompresi yang akan 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 kehilangan kualitas yang dapat diterima, dan opsi CompressionQuality menawarkan pengorbanan ukuran/kecepatan pada tingkat mutu 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 pilihan encoder standar. Tujuan opsi encoder adalah untuk memungkinkan encoder mengekspos kemampuannya, dan tidak ada batasan untuk jenis kemampuan yang dapat Anda ekspos. Pastikan opsi encoder Anda didokumenkan dengan baik. Meskipun aplikasi dapat menggunakan kantong 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 artinya, atau cara menampilkannya di antarmuka pengguna, adalah melalui dokumentasi Anda.
Melakukan
Commit adalah metode yang Anda panggil setelah semua data gambar dan metadata dijadikan serial ke dalam aliran data. Anda harus menggunakan metode ini untuk menserialisasikan 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 diharuskan secara ketat bahwa setiap gambar memiliki pratinjau, sangat disarankan. Kamera digital modern dan pemindai menghasilkan gambar resolusi yang sangat tinggi, yang cenderung sangat besar dan, akibatnya, membutuhkan waktu pemrosesan yang signifikan untuk mendekode. Gambar dari generasi kamera berikutnya akan lebih besar. Sebaiknya berikan versi resolusi gambar 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 yang sebenarnya didekodekan untuk memberikan pengalaman yang lebih baik bagi pengguna, dan menunjukkan kepada mereka representasi dalam ukuran layar gambar saat mereka 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