IWICBitmapSource
COM公式ドキュメント
ピクセルを取得する元となるソースを参照するメソッドを公開します。ただし、書き戻すことはできません。
解説(Remarks)
このインターフェイスは、ビットマップ、デコーダー、フォーマットコンバーター、スケーラーにアクセスし、それらを相互に連結するための共通の手段を提供します。このインターフェイスを実装するコンポーネントは、グラフとして相互に接続し、イメージングデータを引き出すことができます。
このインターフェイスは、読み取り可能であること、すなわちピクセルを生成できることのみを定義します。ビットマップの変更や書き込みは、ストレージを持つビットマップに固有の特殊化とみなされ、派生インターフェイス IWICBitmap で定義されます。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
ビットマップのピクセル単位の幅と高さを取得します。
| puiWidth | DWORD* | out | ビットマップのピクセル幅を受け取るポインター。 |
| puiHeight | DWORD* | out | ビットマップのピクセル高さを受け取るポインター。 |
戻り値
型: HRESULT
このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
ビットマップソースのピクセルフォーマットを取得します。
| pPixelFormat | GUID* | out | ビットマップが格納されているピクセルフォーマット GUID を受け取ります。利用可能なピクセルフォーマットの一覧については、Native Pixel Formats のトピックを参照してください。 |
戻り値
型: HRESULT
このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
解説(Remarks)
このメソッドが返すピクセルフォーマットは、イメージが格納されているピクセルフォーマットとは必ずしも一致しません。 コーデックは、ストレージのピクセルフォーマットから出力ピクセルフォーマットへのフォーマット変換を行う場合があります。
ピクセルと物理世界の測定値との間のサンプリングレートを取得します。
| pDpiX | DOUBLE* | out | x 軸方向の dpi 解像度を受け取るポインター。 |
| pDpiY | DOUBLE* | out | y 軸方向の dpi 解像度を受け取るポインター。 |
戻り値
型: HRESULT
このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
解説(Remarks)
GIF や ICO など一部のフォーマットは、DPI を完全にはサポートしていません。 GIF の場合、このメソッドはアスペクト比から DPI 値を算出し、基準となる DPI (96.0, 96.0) を使用します。 ICO フォーマットは DPI をまったくサポートしておらず、ICO イメージに対しては常に (96.0,96.0) を返します。
さらに、WIC 自体は、イメージ内の DPI 値に基づいてイメージを変換することはありません。 返された解像度に基づいてイメージを変換するのは、呼び出し側の責任です。
インデックス付きピクセルフォーマットのカラーテーブルを取得します。
| pIPalette | IWICPalette* | in | IWICPalette。パレットは CreatePalette メソッドを使用して作成できます。 |
戻り値
型: HRESULT
次のいずれかの値を返します。
| 戻り値コード | 説明 |
|---|---|
| パレットが利用できませんでした。 | |
| パレットが正常にコピーされました。 |
解説(Remarks)
IWICBitmapSource が IWICBitmapFrameDecode である場合、フレームレベルのパレットが利用できないときは、この関数がイメージのグローバルパレットを返すことがあります。 グローバルパレットは CopyPalette メソッドを使用して取得することもできます。
オブジェクトにピクセルを生成するよう指示します。
| prc | WICRect* | inoptional | コピーする矩形。NULL 値はビットマップ全体を指定します。 |
| cbStride | DWORD | in | ビットマップのストライド。 |
| cbBufferSize | DWORD | in | バッファーのサイズ。 |
| pbBuffer | BYTE* | out | バッファーへのポインター。 |
戻り値
型: HRESULT
このメソッドが成功すると、S_OK を返します。それ以外の場合は、HRESULT エラーコードを返します。
解説(Remarks)
CopyPixels は、実際の処理をトリガーする 2 つの主要なイメージ処理ルーチンの 1 つです (もう 1 つは Lock)。 これはオブジェクトに対し、そのアルゴリズムに従ってピクセルを生成するよう指示します。これには、ディスクに格納された JPEG の一部のデコード、メモリブロックのコピー、あるいは複雑なグラデーションの解析的な計算などが含まれる場合があります。 アルゴリズムは、インターフェイスを実装するオブジェクトに完全に依存します。
呼び出し側は、prc パラメーターを使用して、操作を対象領域 (ROI) の矩形に限定できます。 ROI のサブ矩形は、ビットマップの境界内に完全に収まっている必要があります。 NULL の ROI を指定すると、ビットマップ全体が返されることを意味します。
呼び出し側はメモリ管理を制御し、コピー結果を格納する出力バッファー (pbBuffer) をそのバッファーの範囲 (cbBufferSize) とともに提供する必要があります。 cbStride パラメーターは、出力バッファー内で垂直方向に隣接する 2 つのピクセル間のバイト数を定義します。 呼び出し側は、ビットマップの幅、高さ、ピクセルフォーマット、およびコピーメソッドに指定したサブ矩形に基づいて、呼び出しを完了するのに十分なバッファーがあることを保証する必要があります。
JPEG のようにコストの高い IWICBitmapSource のコピーを多数実行する必要がある場合は、まずメモリ内 IWICBitmap を作成することをお勧めします。
コーデック開発者向けの注意事項
呼び出される側は、出力バッファーの各行の先頭 (prc->Width*bitsperpixel+7)/8 バイトにのみ書き込む必要があります (この場合、1 行とは連続する cbStride バイトの列を指します)。Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IWICBitmapSource "{00000120-A8F2-4877-BA0A-FD2B6645FB94}" #usecom global IWICBitmapSource IID_IWICBitmapSource "{}" #comfunc global IWICBitmapSource_GetSize 3 var,var #comfunc global IWICBitmapSource_GetPixelFormat 4 var #comfunc global IWICBitmapSource_GetResolution 5 var,var #comfunc global IWICBitmapSource_CopyPalette 6 sptr #comfunc global IWICBitmapSource_CopyPixels 7 var,int,int,var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWICBitmapSource "{00000120-A8F2-4877-BA0A-FD2B6645FB94}" #usecom global IWICBitmapSource IID_IWICBitmapSource "{}" #comfunc global IWICBitmapSource_GetSize 3 sptr,sptr #comfunc global IWICBitmapSource_GetPixelFormat 4 sptr #comfunc global IWICBitmapSource_GetResolution 5 sptr,sptr #comfunc global IWICBitmapSource_CopyPalette 6 sptr #comfunc global IWICBitmapSource_CopyPixels 7 sptr,int,int,sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。