ホーム › Media.MediaFoundation › IMFMediaBuffer

IMFMediaBuffer

COM

IID045fa593-8799-42b8-bc8d-8968c6453507継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

メディアデータを格納するメモリブロックを表します。

解説(Remarks)

バッファに2次元の画像データ(非圧縮のビデオフレームなど)が含まれている場合は、バッファに対して IMF2DBuffer インターフェイスをクエリしてください。IMF2DBuffer のメソッドは2次元データ向けに最適化されています。

メディアサンプルからバッファを取得するには、次の IMFSample メソッドのいずれかを呼び出します。

新しいバッファオブジェクトを作成するには、次の関数のいずれかを使用します。

関数	説明
MFCreateMemoryBuffer	バッファを作成し、システムメモリを割り当てます。
MFCreateMediaBufferWrapper	既存のメディアバッファをラップするメディアバッファを作成します。
MFCreateDXSurfaceBuffer	DirectX サーフェイスを管理するバッファを作成します。
MFCreateAlignedMemoryBuffer	バッファを作成し、指定したアライメントでシステムメモリを割り当てます。

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

メソッド 5

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

vtbl 3 HRESULT Lock(BYTE** ppbBuffer, DWORD* pcbMaxLength, DWORD* pcbCurrentLength)

呼び出し元に、読み取りまたは書き込みのためのバッファ内メモリへのアクセスを与えます。

ppbBuffer	BYTE**	out	バッファの先頭へのポインターを受け取ります。
pcbMaxLength	DWORD*	outoptional	バッファに書き込むことができるデータの最大量を受け取ります。このパラメーターは NULL にできます。同じ値が IMFMediaBuffer::GetMaxLength メソッドによって返されます。
pcbCurrentLength	DWORD*	outoptional	バッファ内の有効なデータの長さをバイト単位で受け取ります。このパラメーターは NULL にできます。同じ値が IMFMediaBuffer::GetCurrentLength メソッドによって返されます。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
D3DERR_INVALIDCALL	Direct3D サーフェイスバッファの場合、サーフェイスのロック時にエラーが発生しました。
MF_E_INVALIDREQUEST	現時点ではバッファをロックできません。

解説(Remarks)

このメソッドは、pcbMaxLength パラメーターで返される最大サイズまで、バッファ全体へのアクセスを呼び出し元に与えます。pcbCurrentLength で返される値は、バッファ内に既に存在する有効なデータのサイズであり、バッファの合計サイズより小さい場合があります。

ppbBuffer で返されるポインターは有効であることが保証されており、ロックが保持されている間はバッファ全体にわたって安全にアクセスできます。バッファへのアクセスが終わったら、IMFMediaBuffer::Unlock を呼び出してバッファのロックを解除します。Lock の各呼び出しに対して、Unlock を1回呼び出す必要があります。バッファのロックを解除した後は、ppbBuffer で返されたポインターは無効になり、使用してはなりません。一般に、Lock はバッファのメモリにアクセスする必要があるときにのみ呼び出し、それより前に呼び出さないのが最適です。

バッファをロックしても、他のスレッドが Lock を呼び出すのを妨げることはないため、スレッドの同期のためにこのメソッドに依存すべきではありません。

このメソッドはメモリを割り当てることがありますが、メモリの所有権を呼び出し元に移すことはありません。メモリを解放したり破棄したりしないでください。メディアバッファが破棄されるときに、メディアバッファがメモリを解放します。

バッファの内容を変更した場合は、IMFMediaBuffer::SetCurrentLength を呼び出して現在の長さを更新してください。

このメソッドは内部的にメモリを割り当てることがあるため、バッファが IMF2DBuffer インターフェイスをサポートしている場合は、代わりに IMF2DBuffer::Lock2D メソッドを使用してバッファをロックすべきです。2次元バッファの場合、指定する MF2DBuffer_LockFlags の値によっては、Lock2DSize メソッドが Lock メソッドより効率的になることがあります。MF2DBuffer_LockFlags_Read を指定して Lock2DSize を呼び出すと、バッファのロック解除時にコピーバックが発生せず、MF2DBuffer_LockFlags_Write を指定して呼び出すと、内部バッファからのコピーが発生しません。LockFlags_ReadWrite を指定して Lock2DSize を呼び出すと、Lock および Lock2D と同じ動作になり、ロック解除時にコピー元からのコピーとコピーバックの両方が発生します。最良のパフォーマンスを得るための一般的な指針は、可能な限り IMFMediaBuffer および IMF2DBuffer の使用を避け、代わりに必要最小限のロックフラグで IMF2DBuffer2 を使用することです。バッファが Lock2D を使用してロックされている場合、Lock メソッドは MF_E_INVALIDREQUEST を返す可能性があることに注意してください。

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

vtbl 4 HRESULT Unlock()

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

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
D3DERR_INVALIDCALL	Direct3D サーフェイスバッファの場合、サーフェイスのロック解除時にエラーが発生しました。

解説(Remarks)

以前に Lock を呼び出していないのに Unlock を呼び出すのはエラーです。

このメソッドを呼び出した後は、Lock メソッドが返したポインターを使用しないでください。もはや有効であることは保証されません。

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

vtbl 5 HRESULT GetCurrentLength(DWORD* pcbCurrentLength)

バッファ内の有効なデータの長さを取得します。

pcbCurrentLength

DWORD*

out

有効なデータの長さをバイト単位で受け取ります。バッファに有効なデータが含まれていない場合、値は0になります。

戻り値

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

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

解説(Remarks)

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

vtbl 6 HRESULT SetCurrentLength(DWORD cbCurrentLength)

バッファ内の有効なデータの長さを設定します。

cbCurrentLength

DWORD

有効なデータの長さをバイト単位で指定します。この値は、IMFMediaBuffer::GetMaxLength メソッドによって返される、バッファに割り当てられたサイズより大きくすることはできません。

戻り値

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

戻り値	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	指定された長さがバッファの最大サイズを超えています。

解説(Remarks)

バッファにデータを書き込む場合は、このメソッドを呼び出してください。

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

vtbl 7 HRESULT GetMaxLength(DWORD* pcbMaxLength)

バッファに割り当てられたサイズを取得します。

pcbMaxLength

DWORD*

out

バッファに割り当てられたサイズをバイト単位で受け取ります。

戻り値

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

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

解説(Remarks)

バッファには有効なデータが含まれている場合と含まれていない場合があり、有効なデータが含まれている場合でも、バッファに割り当てられたサイズより小さいことがあります。有効なデータの長さを取得するには、IMFMediaBuffer::GetCurrentLength を呼び出してください。

このインターフェイスは、Windows Media Format 11 SDK 再頒布可能コンポーネントがインストールされている場合、次のプラットフォームで利用できます。

Windows XP Service Pack 2 (SP2) 以降。
KB900325 (Windows XP Media Center Edition 2005) および KB925766 (October 2006 Update Rollup for Windows XP Media Center Edition) がインストールされた Windows XP Media Center Edition 2005。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IMFMediaBuffer "{045FA593-8799-42B8-BC8D-8968C6453507}"
#usecom global IMFMediaBuffer IID_IMFMediaBuffer "{}"
#comfunc global IMFMediaBuffer_Lock              3 var,var,var
#comfunc global IMFMediaBuffer_Unlock            4
#comfunc global IMFMediaBuffer_GetCurrentLength  5 var
#comfunc global IMFMediaBuffer_SetCurrentLength  6 int
#comfunc global IMFMediaBuffer_GetMaxLength      7 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IMFMediaBuffer "{045FA593-8799-42B8-BC8D-8968C6453507}"
#usecom global IMFMediaBuffer IID_IMFMediaBuffer "{}"
#comfunc global IMFMediaBuffer_Lock              3 sptr,sptr,sptr
#comfunc global IMFMediaBuffer_Unlock            4
#comfunc global IMFMediaBuffer_GetCurrentLength  5 sptr
#comfunc global IMFMediaBuffer_SetCurrentLength  6 int
#comfunc global IMFMediaBuffer_GetMaxLength      7 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。