IWICBitmapEncoder の実装
IWICBitmapEncoder
このインターフェイスは 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 エンコーダーに委任する必要があります。
関連トピック
-
リファレンス
-
概念