Share via

Menerapkan IWICBitmapFrameEncode

  • Artikel

IWICBitmapFrameEncode

IWICBitmapFrameEncode adalah rekan encoder dengan antarmuka IWICBitmapFrameDecode . Anda dapat mengimplementasikan antarmuka ini pada kelas pengodean tingkat bingkai Anda, yang merupakan kelas yang melakukan pengodean aktual bit gambar untuk setiap bingkai.

interface IWICBitmapFrameEncode : public IUnknown
{
   // Required methods
   HRESULT Initialize ( IPropertyBag2 *pIEncoderOptions );
   HRESULT SetSize ( UINT width,
               UINT height );
   HRESULT SetResolution ( double dpiX,
               double dpiY );
   HRESULT SetPixelFormat (WICPixelFormatGUID *pPixelFormat);
   HRESULT SetColorContexts ( UINT cCount,
               IWICColorContext **ppIColorContext );
   HRESULT GetMetadataQueryWriter ( IWICMetadataQueryWriter 
               **ppIMetadataQueryWriter );
   HRESULT SetThumbnail ( IWICBitmapSource *pIThumbnail );
   HRESULT WritePixels ( UINT lineCount,
               UINT cbStride,
               UINT cbBufferSize,
               BYTE *pbPixels );
   HRESULT WriteSource ( IWICBitmapSource *pIWICBitmapSource,
               WICRect *prc );
   HRESULT Commit ( void );

// Optional method
   HRESULT SetPalette ( IWICPalette *pIPalette );
};

Initialize

Inisialisasi adalah metode pertama yang dipanggil pada objek IWICBitmapFrameEncode setelah dibuat. Metode ini memiliki satu parameter, yang dapat diatur ke NULL. Parameter ini mewakili opsi encoder, dan merupakan instans IPropertyBag2 yang sama dengan yang Anda buat dalam metode CreateNewFrame pada decoder tingkat kontainer, dan diteruskan kembali ke pemanggil dalam parameter pIEncoderOptions dari metode tersebut. Pada saat itu, Anda mengisi struktur IPropertyBag2 dengan properti yang mewakili opsi pengodean yang didukung oleh encoder tingkat bingkai Anda. Penelepon sekarang telah memberikan nilai bagi properti tersebut untuk menunjukkan parameter opsi pengodean tertentu, dan meneruskan objek yang sama kembali kepada Anda untuk menginisialisasi objek IWICBitmapFrameEncode . Anda harus menerapkan opsi yang ditentukan saat mengodekan bit gambar.

SetSize dan SetResolution

SetSize dan SetResolution adalah penjelasan mandiri. Pemanggil menggunakan metode ini untuk menentukan ukuran dan resolusi untuk gambar yang dikodekan.

SetPixelFormat

SetPixelFormat digunakan untuk meminta format piksel untuk mengodekan gambar. Jika format piksel yang diminta tidak didukung, Anda harus mengembalikan GUID format piksel terdekat yang didukung dalam pPixelFormat, yang merupakan parameter masuk/keluar.

SetColorContexts

SetColorContexts digunakan untuk menentukan satu atau beberapa konteks warna yang valid (juga dikenal sebagai profil warna) untuk gambar ini. Penting untuk menentukan konteks warna, sehingga aplikasi yang mendekode gambar di lain waktu dapat mengonversi dari profil warna sumber ke profil tujuan perangkat yang digunakan untuk menampilkan atau mencetak gambar. Tanpa profil warna, tidak mungkin untuk mendapatkan warna yang konsisten di berbagai perangkat. Ini bisa membuat frustrasi pengguna akhir ketika foto mereka terlihat berbeda pada monitor yang berbeda, dan mereka tidak bisa mendapatkan cetakan untuk mencocokkan apa yang mereka lihat di layar.

GetMetadataQueryWriter

GetMetadataQueryWriter mengembalikan IWICMetadataQueryWriter yang dapat digunakan aplikasi untuk menyisipkan atau mengedit properti metadata tertentu dalam blok metadata pada bingkai gambar.

Anda dapat membuat instans IWICMetadataQueryWriter dari IWICComponentFactory dengan beberapa cara. Anda dapat membuatnya dari IWICMetadataBlockWriter Anda, cara yang sama seperti IWICMetadataQueryReader dibuat dari IWICMetadataBlockReader dalam metode GetMetadataQueryReader pada antarmuka IWICBitmapFrameDecode .

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

hr = m_piComponentFactory->CreateQueryWriterFromBlockWriter( 
      static_cast<IWICMetadataBlockWriter*>(this), 
      &piMetadataQueryWriter);

Anda juga dapat membuatnya dari IWICMetadataQueryReader yang ada, seperti yang diperoleh menggunakan metode sebelumnya.

hr = m_piComponentFactory->CreateQueryWriterFromReader( 
      piMetadataQueryReader, pguidVendor, &piMetadataQueryWriter);

Parameter pguidVendor memungkinkan Anda menentukan vendor tertentu untuk digunakan penulis kueri saat membuat instans penulis metadata. Misalnya, jika Anda menyediakan penulis metadata Anda sendiri, Anda mungkin ingin menentukan GUID vendor Anda sendiri. Anda dapat meneruskan NULL ke parameter ini jika Anda tidak memiliki preferensi.

SetThumbnail

SetThumbnail digunakan untuk menyediakan gambar mini. Semua gambar harus menyediakan gambar mini baik secara global, pada setiap bingkai, atau keduanya. Metode GetThumbnail dan SetThumbnail bersifat opsional di tingkat kontainer tetapi, jika codec mengembalikan WINCODEC_ERR_CODECNOTHUMBNAIL dari metode GetThumbnail , Komponen Pencitraan Windows (WIC) akan memanggil metode GetThumbnail untuk Bingkai 0. Jika tidak ada gambar mini yang ditemukan di kedua tempat, WIC harus mendekode gambar lengkap dan menskalakannya ke ukuran gambar mini, yang dapat dikenakan penalti performa besar untuk gambar yang lebih besar.

Gambar mini harus berukuran dan resolusi yang membuatnya cepat didekodekan dan ditampilkan. Untuk alasan ini, gambar mini adalah gambar JPEG yang paling umum. Perhatikan bahwa, jika Anda menggunakan JPEG untuk gambar mini, Anda tidak perlu menulis encoder JPEG untuk mengodekannya, atau dekoder JPEG untuk mendekodenya. Anda harus selalu mendelegasikan ke codec JPEG yang dikirim dengan platform WIC untuk pengodean dan pendekodean gambar mini.

WritePixels

WritePixels adalah metode yang digunakan untuk meneruskan baris pemindaian dari bitmap dalam memori untuk pengodean. Metode ini akan dipanggil berulang kali sampai semua baris pemindaian telah diteruskan. Parameter lineCount menunjukkan berapa banyak baris pemindaian yang akan ditulis dalam panggilan ini. Parameter cbStride menunjukkan jumlah byte per baris pemindaian. cbBufferSize menunjukkan ukuran buffer yang diteruskan dalam parameter pbPixels, yang berisi bit gambar aktual yang akan dikodekan. Jika tinggi gabungan baris pemindaian dari panggilan kumulatif lebih besar dari tinggi yang ditentukan dalam metode SetSize, kembalikan WINCODEC_ERR_TOOMANYSCANLINES.

Ketika WICBitmapEncoderCacheOption adalah WICBitmapEncoderCacheInMemory, baris pemindaian harus di-cache dalam memori sampai semua baris pemindaian telah diteruskan. Jika opsi cache encoder adalah WICBitmapEncoderCacheTempFile, baris pemindaian harus di-cache dalam file sementara, dibuat saat menginisialisasi objek. Dalam salah satu kasus ini, gambar tidak boleh dikodekan sampai pemanggil memanggil Penerapan. Dalam kasus di mana opsi cache adalah WICBitmapEncoderNoCache, encoder harus mengodekan baris pemindaian seperti yang diterima, jika memungkinkan. (Dalam beberapa format, ini tidak dimungkinkan, dan baris pemindaian harus di-cache hingga Penerapan dipanggil.)

Sebagian besar codec mentah tidak akan mengimplementasikan WritePixels, karena tidak mendukung perubahan bit gambar dalam file mentah. Codec mentah masih harus mengimplementasikan WritePixels, namun, karena ketika metadata ditambahkan, itu dapat meningkatkan ukuran file, mengharuskan file ditulis ulang pada disk. Dalam hal ini, perlu untuk dapat menyalin bit gambar yang ada, yang merupakan apa yang dilakukan metode WritePixels .

WriteSource

WriteSource digunakan untuk mengodekan objek IWICBitmapSource . Parameter pertama adalah penunjuk ke objek IWICBitmapSource . Parameter kedua adalah WICRect yang menentukan wilayah yang menarik untuk dikodekan. Metode ini dapat dipanggil beberapa kali berturut-turut, selama lebar setiap persegi panjang adalah lebar gambar akhir yang sama untuk dikodekan. Jika lebar persegi panjang yang dilewatkan dalam parameter rangkaian berbeda dari lebar yang ditentukan dalam metode SetSize, kembalikan WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONS. Jika tinggi gabungan baris pemindaian dari panggilan kumulatif lebih besar dari tinggi yang ditentukan dalam metode SetSize, kembalikan WINCODEC_ERR_TOOMANYSCANLINES.

Opsi cache bekerja dengan cara yang sama dengan metode ini seperti metode WritePixels yang dijelaskan sebelumnya.

Menjalankan

Penerapan adalah metode yang menserialisasikan bit gambar yang dikodekan ke aliran file, dan melakukan iterasi melalui semua penulis metadata untuk bingkai yang meminta mereka untuk menserialisasikan metadata mereka ke aliran. Dalam kasus di mana opsi cache encoder adalah WICBitmapEncoderCacheInMemory atau WICBitmapEncoderCacheTempFile, metode ini juga bertanggung jawab untuk mengodekan gambar, dan ketika opsi cache adalah WICBitmapEncoderCacheTempFile, metode Commit juga harus menghapus file sementara yang digunakan untuk menyimpan data gambar sebelum pengodean.

Metode ini selalu dipanggil setelah semua baris pemindaian atau persegi panjang yang membentuk gambar telah diteruskan menggunakan metode Commit atau WriteSource . Ukuran persegi panjang akhir yang terdiri melalui akumulasi panggilan ke WritePixels atau WriteSource harus berukuran sama seperti yang ditentukan dalam metode SetSize. Jika ukurannya tidak cocok dengan ukuran yang diharapkan, metode ini harus mengembalikan WINCODECERROR_UNEXPECTEDSIZE.

Untuk melakukan iterasi melalui penulis metadata dan memberi tahu setiap penulis metadata untuk menserialisasikan metadatanya ke aliran, panggil GetWriterByIndex untuk melakukan iterasi melalui penulis untuk setiap blok, dan panggil IWICPersistStream.Simpan pada setiap penulis metadata.

IWICMetadataWriter* piMetadataWRiter = NULL;
IWICPersistStream* piPersistStream = NULL;
HRESULT hr;

for (UINT x=0; x < m_blockCount; x++) 
{
    hr = GetWriterByIndex(x, & piMetadataWriter);
hr = piMetadataWriter->QueryInterface(
IID_IWICPersistStream,(void**)&piPersistStream);

hr = piPersistStream->Save(m_piStream, 
WICPersistOptions.WicPersistOptionDefault, 
true);
...
}

SetPalette

Hanya codec yang memiliki format terindeks yang perlu menerapkan metode SetPalette . Jika gambar menggunakan format terindeks, gunakan metode ini untuk menentukan palet warna yang digunakan dalam gambar. Jika codec Anda tidak memiliki format terindeks, kembalikan WINCODEC_ERR_PALETTEUNAVAILABLE dari metode ini.

Konseptual

Menerapkan IWICBitmapCodecProgressNotification (Encoder)

Menerapkan IWICMetadataBlockWriter

Cara Menulis codec WIC-Enabled

Gambaran Umum Komponen Pencitraan Windows