ホーム › Media.MediaFoundation › IMF2DBuffer

IMF2DBuffer

COM

IID7dc9d5f9-9ed9-44ec-9bbf-0600bb589fbb継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

ビデオフレームなどの2次元サーフェスを格納するバッファを表します。(IMF2DBuffer)

解説(Remarks)

このインターフェイスへのポインターを取得するには、メディアバッファーに対して QueryInterface を呼び出します。

2次元バッファーを使用するには、ストライド (stride) を把握しておくことが重要です。ストライドとは、あるピクセル行から次の行へ進むために必要なバイト数です。サーフェスは各ピクセル行の後にパディングバイトを含む場合があるため、ストライドが画像の幅より大きくなることがあります。また、ピクセルがメモリ上で下から上へ配置されている場合、ストライドが負の値になることもあります。詳細については、Image Stride を参照してください。

すべてのビデオ形式は、連続 (contiguous) 表現(パック (packed) 表現とも呼ばれます)を定義します。この表現は、追加のパディングを持たない、システムメモリ上の DirectX サーフェスの標準レイアウトと互換性があります。RGB ビデオの場合、連続表現のピッチは画像の幅(バイト単位)を最も近い DWORD 境界に切り上げた値と等しくなります。YUV ビデオの場合、連続表現のレイアウトは YUV 形式によって異なります。プレーナー YUV 形式では、Y プレーンが U プレーンおよび V プレーンとは異なるピッチを持つことがあります。

メディアバッファーが IMF2DBuffer インターフェイスをサポートしている場合、各ピクセル行の後に追加のパディングバイトが存在する可能性があるため、基になるバッファーが連続表現を持つとは限りません。バッファーが非連続である場合、Lock メソッドと Lock2D メソッドは異なる動作をします。

Lock2D メソッドは、基になるバッファーへのポインターを返します。このバッファーは連続でない場合があります。
Lock メソッドは、連続であることが保証されたバッファーを返します。基になるバッファーが連続でない場合、このメソッドはデータを新しいバッファーにコピーし、Unlock メソッドがそれを元のバッファーにコピーし戻します。

2次元バッファーをそのネイティブ形式でアクセスするには、Lock2D メソッドを呼び出します。ネイティブ形式は連続でない場合があります。バッファーの IMFMediaBuffer::Lock メソッドは、バッファーの連続表現を返します。ただし、これにはネイティブ形式からの内部コピーが必要になる場合があります。したがって、2次元バッファーでは Lock2D メソッドを使用し、Lock メソッドは避けるべきです。Lock メソッドは最大2回のバッファーコピーを引き起こす可能性があるため、一般的に Lock2D メソッドの方が効率的であり、可能な場合はこちらを使用すべきです。基になるバッファーが連続かどうかを調べるには、IMF2DBuffer::IsContiguousFormat を呼び出します。

非圧縮画像の場合、バッファー内の有効なデータ量は、画像の幅、高さ、およびピクセルレイアウトによって決まります。このため、Lock2D を呼び出してバッファーにアクセスする場合、IMFMediaBuffer::GetCurrentLength や IMFMediaBuffer::GetMaxLength が返す値に依存しないでください。同様に、バッファー内のデータを変更した場合でも、サイズを更新するために IMFMediaBuffer::SetCurrentLength を呼び出す必要はありません。一般に、同一のメディアバッファーに対して IMF2DBuffer メソッドと IMFMediaBuffer メソッドの呼び出しを混在させることは避けるべきです。

メソッド 7

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

vtbl 3 HRESULT Lock2D(BYTE** ppbScanline0, INT* plPitch)

呼び出し元にバッファー内のメモリへのアクセスを許可します。(IMF2DBuffer.Lock2D)

ppbScanline0	BYTE**	out	画像内の最上行のピクセルの先頭バイトへのポインターを受け取ります。最上行とは、画像を視聴者に提示したときの最上部の行を指し、メモリ上の最初の行であるとは限りません。
plPitch	INT*	out	サーフェスのストライド(バイト単位)を受け取ります。ストライドは負の値になる場合があり、その場合、画像がメモリ上で下から上へ配置されていることを示します。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
D3DERR_INVALIDCALL	Direct3D サーフェスをロックできません。
MF_E_INVALIDREQUEST	現時点ではバッファーをロックできません。

解説(Remarks)

p がピクセル行の先頭バイトへのポインターである場合、p + (*plPitch) は次のピクセル行の先頭バイトを指します。バッファーは各ピクセル行の後にパディングを含む場合があるため、ストライドが画像の幅(バイト単位)より広くなることがあります。パディングバイト用に予約されたメモリは、読み取りアクセスまたは書き込みアクセスができない場合があるため、アクセスしないでください。詳細については、Image Stride を参照してください。

pbScanline0 で返されるポインターは、呼び出し元がロックを保持している間は有効です。メモリへのアクセスが完了したら、IMF2DBuffer::Unlock2D を呼び出してバッファーのロックを解除します。Lock2D の呼び出しごとに、Unlock2D を1回呼び出す必要があります。バッファーのロックを解除した後は、pbScanline0 で返されたポインターは無効になり、使用してはなりません。一般に、バッファーメモリへのアクセスが必要になったときにのみ Lock2D を呼び出し、それより早く呼び出さないのが最善です。

IMFMediaBuffer::GetCurrentLength メソッドおよび IMFMediaBuffer::GetMaxLength メソッドが返す値は、Lock2D メソッドが返すバッファーには適用されません。同じ理由から、Lock2D メソッドが返すバッファー内のデータを操作した後に IMFMediaBuffer::SetCurrentLength を呼び出す必要はありません。

Lock2D のロックが保持されている間は IMFMediaBuffer::Lock メソッドは失敗し、その逆も同様です。アプリケーションは、これらのメソッドのうち一度に1つのみを使用すべきです。

基になるバッファーが Direct3D サーフェスである場合、そのサーフェスがロック可能でなければメソッドは失敗します。

vtbl 4 HRESULT Unlock2D()

以前にロックされたバッファーのロックを解除します。IMF2DBuffer::Lock2D の呼び出しごとに、このメソッドを1回呼び出します。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。

vtbl 5 HRESULT GetScanline0AndPitch(BYTE** pbScanline0, INT* plPitch)

バッファーメモリへのポインターとサーフェスのストライドを取得します。

pbScanline0	BYTE**	out	画像内の最上行のピクセルの先頭バイトへのポインターを受け取ります。
plPitch	INT*	out	ストライド(バイト単位)を受け取ります。詳細については、Image Stride を参照してください。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
ERROR_INVALID_FUNCTION	このメソッドを呼び出す前に、バッファーをロックする必要があります。

解説(Remarks)

このメソッドを呼び出す前に、IMF2DBuffer::Lock2D を呼び出してバッファーをロックする必要があります。plPitch で返されるポインターは、バッファーがロックされている間のみ有効です。

vtbl 6 HRESULT IsContiguousFormat(BOOL* pfIsContiguous)

バッファーがそのネイティブ形式で連続かどうかを照会します。

pfIsContiguous

BOOL*

out

ブール値を受け取ります。バッファーが連続である場合は TRUE、それ以外の場合は FALSE になります。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。

解説(Remarks)

2次元バッファーに適用される「連続 (contiguous)」の定義については、IMF2DBuffer インターフェイスの「解説」セクションを参照してください。非連続バッファーの場合、IMFMediaBuffer::Lock メソッドは内部コピーを実行する必要があります。

vtbl 7 HRESULT GetContiguousLength(DWORD* pcbLength)

バッファーの内容を連続形式で格納するために必要なバイト数を取得します。

pcbLength

DWORD*

out

バッファーの内容を連続形式で格納するために必要なバイト数を受け取ります。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。

解説(Remarks)

2次元バッファーに適用される「連続 (contiguous)」の定義については、IMF2DBuffer インターフェイスの「解説」セクションを参照してください。

vtbl 8 HRESULT ContiguousCopyTo(BYTE* pbDestBuffer, DWORD cbDestBuffer)

このバッファーを呼び出し元のバッファーにコピーし、データを連続形式に変換します。

pbDestBuffer	BYTE*	out	データのコピー先となる宛先バッファーへのポインター。バッファーは呼び出し元が割り当てます。
cbDestBuffer	DWORD	in	宛先バッファーのサイズ(バイト単位)。必要なサイズを取得するには、IMF2DBuffer::GetContiguousLength を呼び出します。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	pbDestBuffer に指定されたサイズが無効です。

解説(Remarks)

元のバッファーが連続でない場合、このメソッドはコピー中に内容を連続形式に変換します。2次元バッファーに適用される「連続 (contiguous)」の定義については、IMF2DBuffer インターフェイスの「解説」セクションを参照してください。

vtbl 9 HRESULT ContiguousCopyFrom(BYTE* pbSrcBuffer, DWORD cbSrcBuffer)

連続形式を持つバッファーから、このバッファーへデータをコピーします。

pbSrcBuffer	BYTE*	in	ソースバッファーへのポインター。バッファーは呼び出し元が割り当てます。
cbSrcBuffer	DWORD	in	ソースバッファーのサイズ(バイト単位)。バッファーの最大サイズを取得するには、IMF2DBuffer::GetContiguousLength を呼び出します。

戻り値

このメソッドは HRESULT を返します。とり得る値には、次の表に示すものが含まれますが、これらに限定されません。

戻り値	説明
S_OK	メソッドは成功しました。

解説(Remarks)

このメソッドは、ソースバッファーの内容を、この IMF2DBuffer オブジェクトが管理するバッファーにコピーします。ソースバッファーは連続形式でなければなりません。コピー中、このメソッドは内容を宛先バッファーのネイティブ形式に変換し、必要に応じてバッファーのピッチを補正します。

2次元バッファーに適用される「連続 (contiguous)」の定義については、IMF2DBuffer インターフェイスのトピックの「解説」セクションを参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMF2DBuffer "{7DC9D5F9-9ED9-44EC-9BBF-0600BB589FBB}"
#usecom global IMF2DBuffer IID_IMF2DBuffer "{}"
#comfunc global IMF2DBuffer_Lock2D                3 var,var
#comfunc global IMF2DBuffer_Unlock2D              4
#comfunc global IMF2DBuffer_GetScanline0AndPitch  5 var,var
#comfunc global IMF2DBuffer_IsContiguousFormat    6 var
#comfunc global IMF2DBuffer_GetContiguousLength   7 var
#comfunc global IMF2DBuffer_ContiguousCopyTo      8 var,int
#comfunc global IMF2DBuffer_ContiguousCopyFrom    9 var,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IMF2DBuffer "{7DC9D5F9-9ED9-44EC-9BBF-0600BB589FBB}"
#usecom global IMF2DBuffer IID_IMF2DBuffer "{}"
#comfunc global IMF2DBuffer_Lock2D                3 sptr,sptr
#comfunc global IMF2DBuffer_Unlock2D              4
#comfunc global IMF2DBuffer_GetScanline0AndPitch  5 sptr,sptr
#comfunc global IMF2DBuffer_IsContiguousFormat    6 sptr
#comfunc global IMF2DBuffer_GetContiguousLength   7 sptr
#comfunc global IMF2DBuffer_ContiguousCopyTo      8 sptr,int
#comfunc global IMF2DBuffer_ContiguousCopyFrom    9 sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。