Share via

Menerapkan IWICBitmapDecoder

  • Artikel

IWICBitmapDecoder

Ketika aplikasi meminta dekoder, titik interaksi pertama dengan codec adalah melalui antarmuka IWICBitmapDecoder . Ini adalah antarmuka tingkat kontainer yang menyediakan akses ke properti tingkat atas kontainer dan, yang paling penting, bingkai yang dikandungnya. Ini adalah antarmuka utama pada kelas dekoder tingkat kontainer Anda.

interface IWICBitmapDecoder : IUnknown
{
// Required methods
   HRESULT QueryCapability (IStream *pIStream, 
      DWORD *pdwCapabilities );
   HRESULT Initialize ( IStream *pIStream,
      WICDecodeOptions cacheOptions );
   HRESULT GetContainerFormat ( GUID *pguidContainerFormat );
   HRESULT GetDecoderInfo ( IWICBitmapDecoderInfo **pIDecoderInfo );
   HRESULT GetFrameCount ( UINT *pCount );
   HRESULT GetFrame ( UINT index, 
      IWICBitmapFrameDecode **ppIBitmapFrame );

// Optional methods
   HRESULT GetPreview ( IWICBitmapSource **ppIPreview );
   HRESULT GetThumbnail ( IWICBitmapSource **ppIThumbnail );
   HRESULT GetColorContexts ( UINT cCount, 
      IWICColorContext **ppIColorContexts, 
      UINT *pcActualCount );
   HRESULT GetMetadataQueryReader ( IWICMetadataQueryReader **ppIMetadataQueryReader);
   HRESULT CopyPalette ( IWICPalette *pIPalette );
}

Beberapa format gambar memiliki gambar mini global, konteks warna, atau metadata, sementara banyak format gambar menyediakan ini hanya berdasarkan per bingkai. Metode untuk mengakses item ini bersifat opsional pada IWICBitmapDecoder, tetapi diperlukan pada IWICBitmapFrameDecode. Demikian juga, beberapa codec tidak menggunakan format piksel terindeks sehingga tidak perlu menerapkan metode CopyPalette pada salah satu antarmuka. Untuk informasi selengkapnya tentang metode IWICBitmapDecoder opsional, lihat Menerapkan IWICBitmapFrameDecode, tempat metode tersebut paling umum diimplementasikan.

QueryCapability

QueryCapability adalah metode yang digunakan untuk arbitrase codec. (Lihat Penemuan dan Arbitrase dalam topik Cara Kerja Komponen Pencitraan Windows ). Jika dua codec mampu mendekode format gambar yang sama, atau jika tabrakan pola terjadi di mana dua codec menggunakan pola identifikasi yang sama, metode ini memungkinkan Anda untuk memilih codec yang paling baik dapat menangani gambar tertentu.

Saat memanggil metode ini, Komponen Pencitraan Windows (WIC) meneruskan aliran aktual yang berisi gambar. Anda harus memverifikasi apakah Anda dapat mendekode setiap bingkai dalam gambar dan menghitung melalui blok metadata, untuk secara akurat menyatakan kemampuan apa yang dimiliki dekoder ini sehubungan dengan aliran file tertentu yang diteruskan ke dalamnya. Ini penting untuk semua dekode, tetapi terutama penting untuk format gambar berdasarkan kontainer Tagged Image File Format (TIFF). Proses penemuan bekerja dengan mencocokkan pola yang terkait dengan dekode dalam registri ke pola dalam file gambar aktual. Mendeklarasikan pola identifikasi Anda dalam registri menjamin bahwa dekoder Anda akan selalu terdeteksi untuk gambar dalam format gambar Anda. Namun, dekoder Anda masih dapat dideteksi untuk gambar dalam format lain. Misalnya, semua kontainer TIFF menyertakan pola TIFF, yang merupakan pola identifikasi yang valid untuk format gambar TIFF. Ini berarti bahwa, selama penemuan, setidaknya dua pola identifikasi akan ditemukan dalam file gambar untuk format gambar apa pun yang didasarkan pada kontainer gaya TIFF. Salah satunya akan menjadi pola TIFF dan yang lainnya akan menjadi pola format gambar aktual. Meskipun lebih kecil kemungkinannya, mungkin ada tabrakan pola antara format gambar lain yang tidak terkait juga. Inilah sebabnya mengapa penemuan dan arbitrase adalah proses dua tahap. Selalu verifikasi bahwa aliran gambar yang diteruskan ke QueryCapability sebenarnya adalah instans format gambar Anda sendiri yang valid. Selain itu, jika codec Anda mendekode format gambar yang tidak Anda miliki spesifikasinya, implementasi QueryCapability Anda harus memeriksa keberadaan fitur apa pun yang mungkin valid di bawah spesifikasi format gambar yang tidak diterapkan codec Anda. Ini akan memastikan bahwa pengguna tidak mengalami kegagalan pendekodean yang tidak perlu atau mendapatkan hasil yang tidak terduga dengan codec Anda.

Sebelum melakukan operasi apa pun pada gambar, Anda harus menyimpan posisi aliran saat ini, sehingga Anda dapat memulihkannya ke posisi semula sebelum kembali dari metode . Enumerasi WICBitmapDecoderCapabilities yang menentukan kemampuan didefinisikan sebagai berikut:

enum WICBitmapDecoderCapabilities
{   
   WICBitmapDecoderCapabilitySameEncoder,
   WICBitmapDecoderCapabilityCanDecodeAllImages,
   WICBitmapDecoderCapabilityCanDecodeSomeImages,
   WICBitmapDecoderCapabilityCanEnumerateMetadata,
   WICBitmapDecoderCapabilityCanDecodeThumbnail
}

Anda harus menyatakan WICBitmapDecoderCapabilitySameEncoder hanya jika encoder Anda adalah yang mengodekan gambar. Setelah memverifikasi apakah Anda dapat mendekode setiap bingkai dalam kontainer, nyatakan WICBitmapDecoderCapabilityCanDecodeSomeImages jika Anda dapat mendekode beberapa tetapi tidak semua bingkai, WICBitmapDecoderCapabilityCanDecodeAllImages jika Anda dapat mendekode semua bingkai, atau tidak jika Anda tidak dapat mendekode salah satunya. (Kedua enum ini saling eksklusif; jika Anda mengembalikan WICBitmapDecoderCapabilityCanDecodeAllImages, WICBitmapDecoderCapabilityCanDecodeSomeImages akan diabaikan.) Deklarasikan WICBitmapDecoderCapabilityCanEnumerateMetadata setelah memverifikasi bahwa Anda dapat menghitung melalui blok metadata dalam kontainer gambar. Anda tidak perlu memeriksa gambar mini di setiap bingkai. Jika ada gambar mini global dan Anda dapat mendekodekannya, Anda dapat mendeklarasikan WICBitmapDecoderCapabilityCanDecodeThumbnail. Jika tidak ada gambar mini global, maka coba dekodekan gambar mini untuk Bingkai 0. Jika tidak ada gambar mini di salah satu tempat ini, jangan nyatakan kemampuan ini.

Setelah menentukan kemampuan dekoder sehubungan dengan aliran gambar yang diteruskan ke metode ini, lakukan operasi OR dengan WICBitmapDecoderCapabilities yang telah Anda verifikasi bahwa dekoder ini dapat melakukan pada gambar ini, dan mengembalikan hasilnya. Ingatlah untuk memulihkan aliran ke posisi aslinya sebelum kembali.

Initialize

Inisialisasi dipanggil oleh aplikasi setelah dekoder dipilih untuk mendekode gambar tertentu. Aliran gambar diteruskan ke dekoder, dan pemanggil dapat secara opsional menentukan opsi cache WICDecodeOptions untuk menangani metadata dalam file.

enum WICDecodeOptions
{
   WICDecodeMetadataCacheOnDemand,
   WICDecodeMetadataCacheOnLoad
}

Beberapa aplikasi menggunakan metadata lebih dari yang lain. Sebagian besar aplikasi tidak perlu mengakses semua metadata dalam file gambar, dan akan meminta metadata tertentu karena mereka membutuhkannya. Aplikasi lain lebih suka menyimpan semua metadata di depan daripada menjaga aliran file tetap terbuka dan melakukan I/O disk setiap kali mereka perlu mengakses metadata. Jika pemanggil tidak menentukan opsi cache metadata, perilaku penembolokan default harus cache sesuai permintaan. Ini berarti tidak ada metadata yang harus dimuat ke dalam memori sampai aplikasi membuat permintaan khusus untuk metadata tersebut. Jika aplikasi menentukan WICDecodeMetadataCacheOnLoad, metadata harus segera dimuat dalam memori dan di-cache. Ketika metadata di-cache saat dimuat, aliran file dapat dirilis setelah metadata di-cache.

GetContainerFormat

Untuk mengimplementasikan GetContainerFormat, cukup kembalikan GUID format gambar gambar tempat dekoder dibuat. Metode ini juga diimplementasikan pada IWICMetadataBlockReader dan IWICBitmapEncoder.

GetDecoderInfo

GetDecoderInfo mengembalikan objek IWICBitmapDecoderInfo . Untuk mendapatkan objek IWICBitmapDecoderInfo , cukup teruskan GUID decoder Anda ke metode CreateComponentInfo pada IWICImagingFactory, lalu minta antarmuka IWICBitmapDecoderInfo di atasnya, seperti yang ditunjukkan dalam contoh berikut.

IWICComponentInfo* pComponentInfo = NULL;
HRESULT hr;
 
hr = m_pImagingFactory->CreateComponentInfo(CLSID_This, &pComponentInfo);

hr = pComponentInfo->QueryInterface(IID_IWICBitmapDecoderInfo, (void**)ppIDecoderInfo);

GetFrameCount

GetFrameCount hanya mengembalikan jumlah bingkai dalam kontainer. Beberapa format kontainer mendukung beberapa bingkai, dan yang lain hanya mendukung satu bingkai per kontainer.

GetFrame

GetFrame adalah metode penting pada antarmuka IWICBitmapDecoder karena bingkai berisi bit gambar aktual, dan objek dekoder bingkai yang dikembalikan dari metode ini adalah objek yang melakukan decoding aktual dari gambar yang diminta. Itu adalah objek lain yang perlu Anda terapkan saat menulis dekoder. Untuk informasi selengkapnya tentang dekode bingkai, lihat Menerapkan IWICBitmapFrameDecode.

GetPreview

GetPreview mengembalikan pratinjau gambar. Untuk diskusi terperinci tentang pratinjau, lihat Metode Implementasi IWICBitmapEncoder pada antarmuka Implementasi IWICBitmapEncoder .

Jika format gambar Anda berisi pratinjau JPEG yang disematkan, sangat disarankan agar, alih-alih menulis dekoder JPEG untuk mendekodenya, Anda mendelegasikan ke dekoder JPEG yang dikirim dengan platform WIC untuk mendekode pratinjau dan gambar mini. Untuk melakukan ini, cari ke awal data gambar pratinjau di aliran dan panggil metode CreateDecoderFromStream pada IWICImagingFactory.

IWICBitmapDecoder* pPreviewDecoder = NULL;
IWICBitmapFrameDecode* pPreviewFrame = NULL;
IWICBitmapSource* pPreview = NULL;
HRESULT hr;

hr = m_pImagingFactory->CreateDecoderFromStream(
                               m_pStream, NULL, 
                               WICDecodeMetadataCacheOnDemand, &pPreviewDecoder);
hr = pPreviewDecoder->GetFrame(0, pPreviewFrame);
hr = pPreviewFrame->QueryInterface(IID_IWICBitmapSource, (void**)&pPreview);

Referensi

IWICBitmapDecoder

IWICBitmapFrameDecode

Konseptual

Antarmuka Decoder

Menerapkan IWICBitmapCodecProgressNotification (Decoder)

Cara Menulis WIC-Enabled CODEC

Gambaran Umum Komponen Pencitraan Windows