Win32 API 日本語リファレンス
ホーム › Graphics.Imaging › IWICBitmapSourceTransform

IWICBitmapSourceTransform

COM
📘 Microsoft Learn (日本語) · English
IID3b16811b-6a43-4ec9-b713-3d5a0c13b940継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

特定の操作を、基盤となる IWICBitmapSource の実装に委譲するためのメソッドを公開します。

解説(Remarks)

IWICBitmapSourceTransform インターフェイスは、デコード中にピクセルのスケーリング、反転、回転、または形式変換をネイティブに実行できるコーデックによって実装されます。変換がデコード処理と組み合わされるため、ネイティブな変換は非ネイティブな変換よりも一般的にパフォーマンス上の利点があります。標準搭載の IWICBitmapScaler、IWICBitmapFlipRotator、および IWICFormatConverter の実装は、いずれも対応する IWICBitmapFrameDecode の直後に配置された場合に IWICBitmapSourceTransform インターフェイスを利用します。そのため、一般的なケースではアプリケーションはこのパフォーマンス向上を自動的に受けられ、このインターフェイスを直接使用する必要はありません。ただし、複数の変換を連結する場合や、カスタム変換を実装する場合には、IWICBitmapSourceTransform インターフェイスを直接使用することでパフォーマンス上の利点が得られることがあります。

メソッド 4

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT CopyPixels(WICRect* prc, DWORD uiWidth, DWORD uiHeight, GUID* pguidDstFormat, WICBitmapTransformOptions dstTransform, DWORD nStride, DWORD cbBufferSize, BYTE* pbBuffer)

指定された入力パラメーターを使用してピクセルデータをコピーします。

prcWICRect*inコピーするピクセルの矩形。
uiWidthDWORDinソースビットマップをスケーリングする幅。このパラメーターは IWICBitmapSourceTransform::GetClosestSize で取得できる値と等しくなければなりません。
uiHeightDWORDinソースビットマップをスケーリングする高さ。このパラメーターは IWICBitmapSourceTransform::GetClosestSize で取得できる値と等しくなければなりません。
pguidDstFormatGUID*in

ピクセルを返す際に希望するピクセル形式の GUID。

この GUID は GetClosestPixelFormat の呼び出しで取得した形式でなければなりません。

dstTransformWICBitmapTransformOptionsin

ピクセルコピーの前に実行する、希望する回転または反転。

この変換は DoesSupportTransform の呼び出しでサポートされている操作でなければなりません。

dstTransform が指定されている場合、nStride は変換後のストライドであり、元のソースのピクセル形式ではなく pguidDstFormat のピクセル形式に基づきます。

nStrideDWORDin出力先バッファーのストライド。
cbBufferSizeDWORDin出力先バッファーのサイズ。
pbBufferBYTE*out出力バッファー。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

コーデック開発者向けの注意事項

prc に NULL を渡した場合、画像全体がコピーされます。

このメソッドのコーデック開発者向けの実装の詳細については、Implementing IWICBitmapSourceTransform を参照してください。

複数の変換操作が要求された場合、結果は操作を実行する順序に依存します。 コーデック間で予測可能性と一貫性を確保するため、すべてのコーデックがこれらの操作を同じ順序で実行することが重要です。 推奨される操作の順序は次のとおりです。

  1. スケーリング
  2. クロップ
  3. 反転/回転

ピクセル形式の変換は他の変換に影響を与えないため、任意のタイミングで実行できます。

最初のパラメーター prc は、画像をクリップするための対象領域を指定するために使用します。 慣例として、スケーリングはクリップの前に実行されるため、画像をスケーリングとクリップの両方を行う場合、対象領域は画像がスケーリングされた後で決定する必要があります。

dstTransform が指定されている場合、ストライドは変換後のストライドであり、元のフレームのピクセル形式ではなく CopyPixels の呼び出しで指定された pixelFormat に基づきます。

vtbl 4 HRESULT GetClosestSize(DWORD* puiWidth, DWORD* puiHeight)

希望する寸法に対して、実装がネイティブにスケーリングできる最も近い寸法を返します。

puiWidthDWORD*inout希望する幅。サポートされる最も近い幅を受け取るポインター。
puiHeightDWORD*inout希望する高さ。サポートされる最も近い高さを受け取るポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows が提供するコーデックは、ネイティブスケーリングについて次のサポートを提供します。

vtbl 5 HRESULT GetClosestPixelFormat(GUID* pguidDstFormat)

希望する形式が与えられたとき、IWICBitmapSourceTransform の実装がネイティブにピクセルをコピーできる最も近いピクセル形式を取得します。

pguidDstFormatGUID*inout希望する形式に最も近いサポート対象のピクセル形式の GUID を受け取るポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows が提供するコーデックは、次のサポートを提供します。

vtbl 6 HRESULT DoesSupportTransform(WICBitmapTransformOptions dstTransform, BOOL* pfIsSupported)

特定の変換オプションが IWICBitmapSourceTransform インターフェイスの実装によってネイティブにサポートされているかどうかを判定します。

dstTransformWICBitmapTransformOptionsinサポートされているかどうかを確認する WICBitmapTransformOptions。
pfIsSupportedBOOL*out変換オプションがサポートされているかどうかを示す値を受け取るポインター。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows が提供するコーデックは、次のレベルのサポートを提供します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IWICBitmapSourceTransform "{3B16811B-6A43-4EC9-B713-3D5A0C13B940}"
#usecom global IWICBitmapSourceTransform IID_IWICBitmapSourceTransform "{}"
#comfunc global IWICBitmapSourceTransform_CopyPixels             3 var,int,int,var,int,int,int,var
#comfunc global IWICBitmapSourceTransform_GetClosestSize         4 var,var
#comfunc global IWICBitmapSourceTransform_GetClosestPixelFormat  5 var
#comfunc global IWICBitmapSourceTransform_DoesSupportTransform   6 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。