Microsoft DirectX 8.0

IMemAllocator インターフェイス

ピン間でデータを移動させるために、メディア サンプルを割り当てる。

入力ピンが IMemInputPin インターフェイスを公開するとき、アロケータを共有するピンによってこのインターフェイスは使われる。そのピンはどのピンがアロケータを提供するかをネゴシエートする。アロケータを使って、メモリ バッファを割り当て、からのバッファを取得し、バッファを解放する。すべてのフィルタがそれ自身のアロケータを作成するわけではないので、1 つのアロケータを複数のフィルタが使用する場合もある。詳細については、「フィルタの接続」を参照すること。

アプリケーションは通常このインターフェイスを使わない。

アロケータを使うには次のステップを行う。

  1. IMemAllocator::SetProperties メソッドを呼び出して、バッファの数と各バッファのサイズを含むバッファ要求を指定する。
  2. IMemAllocator::Commit メソッドを呼び出して、バッファを割り当てる。
  3. Call IMemAllocator::GetBuffer メソッドを呼び出して、メディア サンプルを取得する。このメソッドは次のサンプルが有効になるまでブロックする。
  4. 各サンプルについて終了したとき、サンプルで IUnknown::Release メソッドを呼び出す。サンプルはその参照カウントがゼロになっても削除されない。代わりに、サンプルはアロケータのフリー リストを返す。
  5. そのアロケータの使用が終わったとき、IMemAllocator::Decommit メソッドを呼び出してバッファ用のメモリを解放する。

Vtable 順のメソッド

IUnknown メソッド説明
QueryInterface サポートされているインターフェイスへのポインタを取得する。
AddRef 参照カウントをインクリメントする。
Release 参照カウントをデクリメントする。
IMemAllocator メソッド説明
SetProperties割り当てるバッファの数と各バッファのサイズを指定する。
GetPropertiesアロケータが作成するバッファの数とバッファのプロパティを取得する。
Commitバッファ メモリを割り当てる。
Decommitバッファ用のメモリを解放する。
GetBufferカラのバッファを持つメディアサンプルを取得する。
ReleaseBufferメディア サンプルを解放する。

IMemAllocator::Commit

IMemAllocator インターフェイス

バッファ メモリを割り当てる。

構文

HRESULT Commit(void);

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK成功。
E_OUTOFMEMORYメモリ不足。
VFW_E_SIZENOTSETバッファ要求はセットされなかった。

注意

このメソッドを呼び出す前に、IMemAllocator::SetProperties メソッドを呼び出してバッファ要求を指定すること。

IMemAllocator::GetBuffer メソッドを呼び出す前に、必ずこのメソッドを呼び出すこと。

IMemAllocator::Decommit

IMemAllocator インターフェイス

バッファ用のメモリを解放する。

構文

HRESULT Decommit(void);

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

IMemAllocator::GetBuffer メソッドで待っているスレッドはエラーを返す。IMemAllocator::Commit メソッドが呼び出されるまでは、以降の GetBuffer への呼び出しは失敗する。

IMemAllocator::GetBuffer

IMemAllocator インターフェイス

カラのバッファを持つメディアサンプルを取得する。

構文

HRESULT GetBuffer(
    IMediaSample **ppBuffer,
    REFERENCE_TIME *pStartTime,
    REFERENCE_TIME *pEndTime,
    DWORD dwFlags
);

パラメータ

ppBuffer
[out] バッファの IMediaSample インターフェイスへのポインタを受け取る変数のアドレス。
pStartTime
[in] サンプルの開始タイムへのポインタ、あるいは NULL 。
pEndTime
[in] サンプルの終了タイムへのポインタ、あるいは NULL 。
dwFlags
[in] ゼロあるいはそれ以上のフラグの組み合わせ。
  • AM_GBF_NOTASYNCPOINT: このサンプルは同期ポイントではない。このサンプルには動的なフォーマット変更は許可されない。
  • AM_GBF_PREVFRAMESKIPPED: このサンプルは不連続後の最初である。(ビデオ レンダラのみがこのフラグを使う)
  • AM_GBF_NOWAIT: バッファが有効になるのを待つべきではない。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK成功。
VFW_E_NOT_COMMITTEDアロケータはデコミットである。
VFW_E_TIMEOUTタイム アウト。

注意

デフォルトでは、このメソッドはフリー サンプルが利用できるまで、あるいはアロケータがデコミットになるまでブロックする。呼び出し元が AM_GBF_NOWAIT フラグを指定し、サンプルが利用できないなら、アロケータは VFW_E_TIMEOUT 値を戻してすぐに返る。しかし、アロケータによるこのフラグのサポートは必須ではない。

ppBuffer で返るサンプルは利用可能なバッファポインタを持つ。呼び出し元はサンプルの他のプロパティを設定する責任がある、それはたとえばタイム スタンプやメディア タイムや同期ポイント プロパティなどである (詳細については、「IMediaSample」を参照すること)。

pStartTime パラメータと pEndTime パラメータはサンプルに適用されない。アロケータはこれらの値を使ってどのバッファを取得したかを確認する場合がある。たとえば、ビデオ レンダラ フィルタはこれらの値を使って Microsoft® DirectDraw® サーフェイスとの同期をスイッチする。サンプルのタイム スタンプを設定するには IMediaSample::SetTime メソッドを呼び出すこと。

このメソッドを呼び出す前に IMemAllocator::Commit メソッドを必ず呼び出さなければならない。IMemAllocator::Decommit メソッドが呼び出された後ではこの呼び出しは失敗する。メソッドが成功すると、IMediaSample インターフェイスには参照カウントが残る。使用したときインターフェイスの解放に注意。

IMemAllocator::GetProperties

IMemAllocator インターフェイス

アロケータが作成するバッファの数とバッファのプロパティを取得する。

構文

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

パラメータ

pProps
[out] アロケータ プロパティを受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

IMemAllocator::Commit メソッドが呼び出されるまで、このメソッドへの呼び出しは成功しない場合がある。

IMemAllocator::ReleaseBuffer

IMemAllocator インターフェイス

メディア サンプルを解放する。

構文

HRESULT ReleaseBuffer(
    IMediaSample *pBuffer
);

パラメータ

pBuffer
[in] メディア サンプルの IMediaSample インターフェイスへのポインタ。

戻り値

成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。

注意

メディア サンプルの参照カウントがゼロになると、このメソッドは pBuffer にそれ自身を入れて呼び出す。このメソッドはサンプルを解放して、アロケータの利用可能なサンプルのリストに戻す。

IMemAllocator::SetProperties

IMemAllocator インターフェイス

割り当てるバッファの数と各バッファのサイズを指定する。

構文

HRESULT SetProperties(
    ALLOCATOR_PROPERTIES *pRequest,
    ALLOCATOR_PROPERTIES *pActual
);

パラメータ

pRequest
バッファ要求が入る ALLOCATOR_PROPERTIES 構造体へのポインタ。
pActual
実際のバッファプロパティを受け取る ALLOCATOR_PROPERTIES 構造体へのポインタ。

戻り値

HRESULT 値を返す。以下の表に示されるいずれかの値。

S_OK成功。
E_POINTERNULL ポインタ引数。
VFW_E_ALREADY_COMMITTEDフィルタがアクティブな間は割り当てたメモリを変更することはできない。
VFW_E_BADALIGN不適切な引数が指定された。
VFW_E_BUFFERS_OUTSTANDING1 つ以上のバッファがまだアクティブ。

注意

このメソッドはバッファ要求を指定するが、バッファを割り当てるわけではない。IMemAllocator::Commit メソッドを呼び出してバッファを割り当てること。

呼び出し元は 2 つの ALLOCATOR_PROPERTIES 構造体を割り当てる。pRequest パラメータにはバッファの数と各バッファのサイズを含む呼び出し元のバッファ要求が入る。メソッドが返ると、pActual パラメータにはアロケータによってセットされた実際のバッファ プロパティが入る。

このメソッドが呼び出されるとき、アロケータはコミットされていなければならない、あるいは利用可能なバッファを持っていなければならない。