IWICBitmapFrameEncode の実装

[アーティクル]
06/13/2023

IWICBitmapFrameEncode

IWICBitmapFrameEncode は、 IWICBitmapFrameDecode インターフェイスに対応するエンコーダーです。このインターフェイスは、フレームレベルのエンコードクラスに実装できます。これは、各フレームのイメージビットの実際のエンコードを行うクラスです。

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 );
};

初期化する
SetSize と SetResolution
SetPixelFormat
SetColorContexts
GetMetadataQueryWriter
SetThumbnail
WritePixels
WriteSource
コミット
SetPalette

Initialize

Initialize は、インスタンス化された後に IWICBitmapFrameEncode オブジェクトで呼び出される最初のメソッドです。このメソッドには、 NULL に設定できる 1 つのパラメーターがあります。このパラメーターはエンコーダーオプションを表し、コンテナーレベルデコーダーの CreateNewFrame メソッドで作成したのと同じ IPropertyBag2 インスタンスであり、そのメソッドの pIEncoderOptions パラメーターで呼び出し元に返されます。その時点で、フレームレベルエンコーダーでサポートされているエンコードオプションを表すプロパティを IPropertyBag2 構造体に設定しました。呼び出し元は、特定のエンコードオプションパラメーターを示すこれらのプロパティの値を指定し、同じオブジェクトを渡して IWICBitmapFrameEncode オブジェクトを初期化しています。イメージビットをエンコードする場合は、指定したオプションを適用する必要があります。

SetSize と SetResolution

SetSize と SetResolution はわかりやすいものです。呼び出し元は、これらのメソッドを使用して、エンコードされたイメージのサイズと解像度を指定します。

SetPixelFormat

SetPixelFormat は、イメージをエンコードするピクセル形式を要求するために使用されます。要求されたピクセル形式がサポートされていない場合は、 pPixelFormat でサポートされている最も近いピクセル形式の GUID (in/out パラメーター) を返す必要があります。

SetColorContexts

SetColorContexts は、このイメージの 1 つ以上の有効なカラーコンテキスト (カラープロファイルとも呼ばれます) を指定するために使用されます。カラーコンテキストを指定することが重要です。後でイメージをデコードするアプリケーションは、ソースカラープロファイルから、イメージの表示または印刷に使用されるデバイスの宛先プロファイルに変換できます。カラープロファイルがないと、異なるデバイス間で一貫した色を取得することはできません。これは、エンドユーザーの写真が異なるモニターで異なって表示され、画面に表示される内容に合わせてプリントを取得できない場合に、いら立つ可能性があります。

GetMetadataQueryWriter

GetMetadataQueryWriter は、イメージフレーム上のメタデータブロックに特定のメタデータプロパティを挿入または編集するためにアプリケーションが使用できる IWICMetadataQueryWriter を返します。

IWICComponentFactory から IWICMetadataQueryWriter をインスタンス化するには、いくつかの方法があります。 IWICBitmapFrameDecode インターフェイスの GetMetadataQueryReader メソッドの IWICMetadataBlockReader から IWICMetadataQueryReader が作成されたのと同じ方法で、IWICMetadataBlockWriter から作成することもできます。

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

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

前のメソッドを使用して取得した IWICMetadataQueryReader など、既存の IWICMetadataQueryReader から作成することもできます。

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

pguidVendor パラメーターを使用すると、メタデータライターをインスタンス化するときに使用するクエリライターの特定のベンダーを指定できます。たとえば、独自のメタデータライターを指定する場合は、独自のベンダー GUID を指定できます。ユーザー設定がない場合は、このパラメーターに NULL を 渡すことができます。

SetThumbnail

SetThumbnail は、サムネイルを提供するために使用されます。すべての画像は、グローバル、各フレーム、またはその両方にサムネイルを提供する必要があります。 GetThumbnail メソッドと SetThumbnail メソッドはコンテナーレベルでは省略可能ですが、コーデックが GetThumbnail メソッドからWINCODEC_ERR_CODECNOTHUMBNAILを返す場合、Windows イメージングコンポーネント (WIC) は Frame 0 の GetThumbnail メソッドを呼び出します。いずれの場所にもサムネイルが見つからない場合、WIC は完全なイメージをデコードしてサムネイルサイズにスケーリングする必要があります。これにより、大きな画像のパフォーマンスが低下する可能性があります。

サムネイルは、デコードと表示を迅速に行うサイズと解像度である必要があります。このため、サムネイルは最も一般的に JPEG 画像です。サムネイルに JPEG を使用する場合は、エンコードする JPEG エンコーダーや、デコードする JPEG デコーダーを記述する必要はありません。サムネイルをエンコードおよびデコードするには、WIC プラットフォームに付属する JPEG コーデックに常に委任する必要があります。

WritePixels

WritePixels は、エンコードのためにメモリ内のビットマップからスキャン行を渡すために使用されるメソッドです。メソッドは、すべてのスキャンラインが渡されるまで繰り返し呼び出されます。 lineCount パラメーターは、この呼び出しで書き込まれるスキャン行の数を示します。 cbStride パラメーターは、スキャン行あたりのバイト数を示します。 cbBufferSize は、pbPixels パラメーターで渡されるバッファーのサイズを示します。このサイズには、エンコードされる実際のイメージビットが含まれます。累積呼び出しのスキャン行の合計高さが SetSize メソッドで指定された高さを超える場合は、WINCODEC_ERR_TOOMANYSCANLINESを返します。

WICBitmapEncoderCacheOption が WICBitmapEncoderCacheInMemory の場合、すべてのスキャン行が渡されるまで、スキャン行をメモリにキャッシュする必要があります。エンコーダーキャッシュオプションが WICBitmapEncoderCacheTempFile の場合、スキャン行は一時ファイルにキャッシュされ、オブジェクトの初期化時に作成されます。どちらの場合も、呼び出し元が Commit を呼び出すまでイメージをエンコードしないでください。キャッシュオプションが WICBitmapEncoderNoCache の場合、エンコーダーは、可能であれば、受信したスキャン行をエンコードする必要があります。 (一部の形式では、これは不可能であり、Commit が呼び出されるまでスキャン行をキャッシュする必要があります)。

ほとんどの生コーデックは WritePixels を実装しません。これは、生ファイル内のイメージビットの変更をサポートしていないためです。生コーデックでは WritePixels を実装する必要がありますが、メタデータを追加するとファイルのサイズが大きくなり、ディスク上でファイルを書き換える必要があるためです。その場合は、 WritePixels メソッドが行う既存のイメージビットをコピーできる必要があります。

WriteSource

WriteSource は、 IWICBitmapSource オブジェクトをエンコードするために使用されます。最初のパラメーターは、 IWICBitmapSource オブジェクトへのポインターです。 2 番目のパラメーターは、エンコードする対象領域を指定する WICRect です。このメソッドは、各四角形の幅がエンコードされる最終的なイメージの幅が同じである限り、連続して複数回呼び出すことができます。 prc パラメーターで渡される四角形の幅が SetSize メソッドで指定された幅と異なる場合は、WINCODEC_ERR_SOURCERECTDOESNOTMATCHDIMENSIONSを返します。累積呼び出しからのスキャン行の合計高さが SetSize メソッドで指定された高さを超える場合は、WINCODEC_ERR_TOOMANYSCANLINESを返します。

キャッシュオプションは、前に説明した WritePixels メソッドと同じように、このメソッドと同じように動作します。

Commit

Commit は、エンコードされたイメージビットをファイルストリームにシリアル化し、フレームのすべてのメタデータライターを反復処理して、メタデータをストリームにシリアル化するように要求するメソッドです。エンコーダーキャッシュオプションが WICBitmapEncoderCacheInMemory または WICBitmapEncoderCacheTempFile の場合、このメソッドはイメージのエンコードも行います。キャッシュオプションが WICBitmapEncoderCacheTempFile の場合、 Commit メソッドはエンコード前にイメージデータのキャッシュに使用される一時ファイルも削除する必要があります。

このメソッドは常に、イメージを構成するすべてのスキャン行または四角形が Commit メソッドまたは WriteSource メソッドを使用して渡された後に呼び出されます。 WritePixels または WriteSource の累積呼び出しによって構成される最終的な四角形のサイズは、SetSize メソッドで指定されたサイズと同じである必要があります。サイズが予想されるサイズと一致しない場合、このメソッドはWINCODECERROR_UNEXPECTEDSIZEを返す必要があります。

メタデータライターを反復処理し、各メタデータライターにストリームをシリアル化するように指示するには、GetWriterByIndex を呼び出して各ブロックのライターを反復処理し、各メタデータライターで IWICPersistStream.Save を呼び出します。

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

SetPalette メソッドを実装する必要があるのは、インデックス付き形式のコーデックのみです。イメージでインデックス付き形式を使用する場合は、このメソッドを使用して、イメージで使用される色のパレットを指定します。コーデックにインデックス付き形式がない場合は、このメソッドからWINCODEC_ERR_PALETTEUNAVAILABLEを返します。

概念
IWICBitmapCodecProgressNotification の実装 (エンコーダー)
IWICMetadataBlockWriter の実装
WIC-Enabled コーデックを記述する方法
Windows イメージングコンポーネントの概要

IWICBitmapFrameEncode の実装