IWICBitmapFrameEncode の実装

[アーティクル]
09/24/2022

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

SetSize と SetResolution

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

SetPixelFormat

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

SetColorContexts

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

GetMetadataQueryWriter

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

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

IWICMetadataQueryWriter* piMetadataQueryWriter = NULL;
HRESULT hr;

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

前のメソッドを使用して取得したものなど、既存の 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 (Encoder) の実装
IWICMetadataBlockWriter の実装
WIC-Enabled CODEC を記述する方法
Windows イメージングコンポーネントの概要

IWICBitmapFrameEncode の実装