IWICBitmapEncoder の実装

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

IWICBitmapEncoder
関連トピック

IWICBitmapEncoder

初期化する
GetContainerFormat
GetEncoderInfo
CreateNewFrame
コミット
SetPreview

このインターフェイスは IWICBitmapDecoder インターフェイスに対応し、イメージファイルをエンコードするための開始点です。 IWICBitmapDecoder を使用してイメージコンテナーからコンテナーレベルのプロパティと個々のフレームを取得するのと同様に、IWICBitmapEncoder を使用してコンテナーレベルのプロパティを設定し、個々のイメージフレームをコンテナーにシリアル化します。このインターフェイスは、コンテナーレベルのエンコーダークラスに実装します。

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

「IWICBitmapDecoder の実装」で説明したように、一部の画像形式にはグローバルサムネイル、色コンテキスト、またはメタデータが含まれていますが、多くの画像形式ではフレームごとにのみ提供されます。したがって、これらを設定するメソッドは IWICBitmapEncoder では省略可能ですが、 IWICBitmapFrameEncode では必須です。 IWICBitmapEncoder で省略可能なメソッドについては、IWICBitmapFrameEncode のセクションで説明します。これらは最も一般的に実装されています。

グローバルサムネイルをサポートしていない場合は、 IWICBitmapEncoder の SetThumbnail メソッドからWINCODEC_ERR_CODECNOTHUMBNAILを返します。コンテナーレベルのパレットをサポートしていない場合、またはエンコードするイメージにインデックス付き形式がない場合は、SetPalette メソッドからWINCODEC_ERR_PALETTEUNAVAILABLEを返します。サポートされていないその他のメソッドについては、WINCODEC_ERR_UNSUPPORTEDOPERATIONを返します。

Initialize

Initialize は、インスタンス化された後に IWICBitmapEncoder で呼び出される最初のメソッドです。イメージストリームはエンコーダーに渡され、呼び出し元は必要に応じてキャッシュオプションを指定できます。デコーダーの場合、ストリームは読み取り専用ですが、エンコーダーに渡されるストリームは書き込み可能なストリームであり、エンコーダーはすべてのイメージデータとメタデータをシリアル化します。エンコーダーのキャッシュオプションも異なります。

enum WICBitmapEncoderCacheOption
{
   WICBitmapEncoderCacheInMemory,
   WICBitmapEncoderCacheTempFile,
   WICBitmapEncoderNoCache
}

アプリケーションには、イメージデータをメモリにキャッシュするか、一時ファイルにキャッシュするか、キャッシュなしでディスクファイルに直接書き込むようエンコーダーに要求するかの選択肢があります。データを一時ファイルにキャッシュするように求められた場合、エンコーダーはディスク上に一時ファイルを作成し、メモリにキャッシュせずにそのファイルに直接書き込む必要があります。呼び出し元がキャッシュなしオプションを選択した場合は、次のフレームを作成する前に、各フレームを順番にコミットする必要があります。

GetContainerFormat

GetContainerFormat は、IWICBitmapDecoder の実装に関するページの GetContainerFormat メソッドと同じ方法で実装されます。

GetEncoderInfo

GetEncoderInfo は IWICBitmapEncoderInfo オブジェクトを 返します。 IWICBitmapEncoderInfo オブジェクトを取得するには、エンコーダーの GUID を IWICImagingFactory の CreateComponentInfo メソッドに渡し、その上で IWICBitmapEncoderInfo インターフェイスを要求します。

GetDecoderInfo の「IWICBitmapDecoder の実装」の例を参照してください。

CreateNewFrame

CreateNewFrame は、IWICBitmapDecoder の GetFrame に対応するエンコーダーです。このメソッドは、コンテナー内の特定のフレームのイメージデータを実際にシリアル化するオブジェクトである IWICBitmapFrameEncode オブジェクトを返します。

Windows Imaging Component (WIC) の利点の 1 つは、すべてのイメージ形式を同じ方法で操作できる抽象化レイヤーをアプリケーションに提供することです。ただし、すべての画像形式がまったく同じであるわけではありません。一部のイメージ形式には、他にはない機能があります。アプリケーションでこれらの固有の機能を利用できるようにするには、コーデックがそれらを公開する方法を提供する必要があります。これはエンコーダーオプションの目的です。コーデックでエンコーダーオプションがサポートされている場合は、サポートするエンコーダーオプションを公開する IPropertyBag2 オブジェクトを作成し、このメソッドの ppIEncoderOptions パラメーターで返す必要があります。呼び出し元は、この IPropertyBag2 オブジェクトを使用して、コーデックでサポートされているエンコーダーオプションを決定できます。呼び出し元がサポートされているエンコーダーオプションの値を指定する場合、IPropertyBag2 オブジェクトの関連プロパティに値を割り当て、Initialize メソッドで新しく作成された IWICBitmapFrameEncode オブジェクトに渡します。

IPropertyBag2 オブジェクトをインスタンス化するには、まず PROPBAG2 構造体を作成して、エンコーダーがサポートする各エンコーダーオプションと各プロパティのデータ型を指定する必要があります。次に、書き込み時に各プロパティの値範囲を適用し、競合または重複する値を調整する IPropertyBag2 オブジェクトを実装する必要があります。競合しないエンコーダーオプションの単純なセットの場合は、 CreateEncoderPropertyBag メソッドを呼び出すことができます。これにより、PROPBAG2 構造体で指定したプロパティを使用して単純な IPropertyBag2 オブジェクトが作成されます。値の範囲は引き続き適用する必要があります。より高度なエンコーダーオプションの場合、または競合する値を調整する必要がある場合は、独自の IPropertyBag2 実装を記述する必要があります。

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 には、一般的なイメージ形式の一部で使用される標準エンコーダーオプションの小さなセットが用意されています。すべての正規エンコーダーオプションは省略可能であり、コーデックはサポートする必要はありません。標準オプションとして提供される理由は、多くのアプリケーションが、イメージファイルをサポートする形式で保存するときに、ユーザーがこれらのオプションを指定するためのユーザーインターフェイスを公開するためです。これらのオプションを指定する標準的な方法を提供すると、アプリケーションは一貫した方法でエンコーダーに簡単に通信できます。正規エンコーダーオプションを次の表に示します。

エンコーダーオプション	VARTYPE	値の範囲
ロスレス	VT_BOOL	True/False
ImageQuality	VT_R4	0.0-1.0
CompressionQuality	VT_R4	0.0-1.0
BitmapTransform	VT_UI1	WICBitmapTransformOptions

コーデックでロスレスエンコードがサポートされている場合は、アプリケーションがイメージを無損失でエンコードするように要求する方法として、ロスレスエンコーダーオプションを公開する必要があります。呼び出し元がこのプロパティを True に設定した場合は、ImageQuality オプションを無視し、イメージを無損失でエンコードする必要があります。

ImageQuality オプションを使用すると、アプリケーションはイメージのエンコードに使用する忠実度を指定できます。このオプションを使用すると、ユーザーは画質と速度やファイルサイズの間でトレードオフを行うことができます。 JPEG は、このトレードオフをサポートするイメージ形式の例です。値 0.0 は、忠実度が低い重要度であり、エンコーダーで最も損失の多いアルゴリズムを使用する必要があることを示します。値 1.0 は、忠実度が最も重要であり、エンコーダーが可能な限り最高の忠実度を維持する必要があることを示します。 (コーデックによっては、これはロスレスオプションと同義である場合があります。ただし、コーデックでロスレスエンコードがサポートされていて、ロスレスオプションが True に設定されている場合は、ImageQuality オプションは無視する必要があります)。

CompressionQuality オプションを使用すると、アプリケーションはイメージのエンコード時に使用する圧縮の効率を指定できます。非常に効率的なアルゴリズムでは、効率の低い圧縮アルゴリズムと同じ品質の小さなイメージファイルが生成される場合がありますが、エンコードに時間がかかる場合があります。このオプションを使用すると、ファイルサイズとエンコード速度のトレードオフを指定しながら、同じレベルの品質を維持できます。 TIFF は、このトレードオフをサポートするイメージ形式の例です。 (JPEG などの形式では異なるレベルの圧縮がサポートされますが、圧縮速度が高いほど画質が低下します。したがって、JPEG イメージ形式では、CompressionQuality オプションではなく ImageQuality オプションが公開されます)。このオプションの値が 0.0 の場合は、ファイルサイズを大きくする代わりに、忠実度を下げることなく、できるだけ早くイメージを圧縮する必要があることを示します。値 1.0 は、エンコードにかかる時間に関係なく、可能な限り最小のファイルサイズ (同じ品質レベル) を作成する必要があることを示します。コーデックでは、ImageQuality オプションと CompressionQuality オプションの両方をサポートできます。ここで、ImageQuality オプションは許容される損失の程度を指定し、CompressionQuality オプションは指定された品質レベルでサイズ/速度のトレードオフを提供します。

BitmapTransform オプションは、呼び出し元がエンコード時に回転角度または垂直方向または水平方向の反転方向を指定する方法を提供します。要求された変換を指定するために使用される WICBitmapTransformOptions 列挙型は、IWICBitmapSourceTransform インターフェイスを介したデコード中に変換を要求するときに使用される列挙型と同じです。

エンコーダーは正規エンコーダーオプションに限定されないことに注意してください。エンコーダーオプションの目的は、エンコーダーが機能を公開できるようにすることであり、公開できる機能の種類に制限はありません。エンコーダーのオプションが十分に文書化されていることを確認します。アプリケーションでは、このメソッドから返されたプロパティバッグを使用して、サポートするオプションの名前、型、および値の範囲を検出できますが、その意味を確認する唯一の方法、またはユーザーインターフェイスでそれらを公開する方法は、ドキュメントから行います。

Commit

Commit は、すべてのイメージデータとメタデータがストリームにシリアル化された後に呼び出すメソッドです。このメソッドを使用して、プレビューイメージデータをストリームにシリアル化し、グローバルサムネイル、メタデータ、パレット、またはその他の項目 (該当する場合) をシリアル化する必要があります。ストリームを開いたアプリケーションはファイルストリームを閉じる必要があるため、このメソッドはファイルストリームを閉じてはいけません。

IWICBitmapFrameEncode:Commit メソッドのセクションには、IWICBitmapEncoderCacheOptions がこのメソッドの動作にどのように影響するかについて詳しく説明されています。

SetPreview

SetPreview は、イメージのプレビューを作成するために使用されます。すべてのイメージにプレビューが必要なわけではありませんが、強くお勧めします。最新のデジタルカメラとスキャナは非常に高解像度の画像を生成します。これは非常に大きくなる傾向があり、その結果、デコードにかなりの処理時間がかかります。次世代のカメラの画像はさらに大きくなります。通常は JPEG 形式で、ユーザーが要求したときに "瞬時に" デコードして表示できる、より小さく解像度の低いバージョンの画像を提供することをお勧めします。アプリケーションは、実際のイメージのデコードを要求する前にプレビューを要求して、ユーザーにより良いエクスペリエンスを提供し、実際のイメージのデコードを待機している間にイメージの画面サイズの表現を表示する場合があります。コーデックはプレビューを提供する必要がありますが、 IWICBitmapSourceTransform をサポートしていないコーデックは間違いなくそうする必要があります。

JPEG プレビューを提供する場合は、JPEG エンコーダーを記述してエンコードする必要はありません。プレビューとサムネイルの両方をエンコードするために、WIC プラットフォームに付属する JPEG エンコーダーに委任する必要があります。

リファレンス
IWICBitmapEncoder
IWICBitmapFrameEncode
概念
エンコーダーインターフェイス
IWICBitmapCodecProgressNotification の実装 (エンコーダー)
WIC-Enabled コーデックを記述する方法
Windows イメージングコンポーネントの概要

IWICBitmapEncoder の実装