Microsoft DirectX 8.0 |
フィルタ グラフ マネージャは、グラフを動的に構築する IGraphConfig を公開する。このインターフェイスを使用すると、アプリケーションおよびフィルタから、ストリームからのデータを失わずに、実行状態にあるフィルタ グラフを再構成できる。
グラフを動的に再構築する最も直接的な方法は、Reconnect メソッドを呼び出す方法である。グラフを動的に再構築するための細かい処理の大半は、メソッド側で実行する。独自の技法を使う必要がある場合のために、IGraphConfig は Reconfigure メソッドも提供する。このメソッドは、フィルタ グラフをロックしたうえで、アプリケーション側のコールバック関数を呼び出し、その関数がグラフを再構成する。このメソッドでは、処理の大半をアプリケーション側で実行する。詳細については、「動的グラフ作成」を参照すること。
フィルタを追加および削除する処理を最適化するため、フィルタ グラフはフィルタのキャッシュを保持する。Reconnect メソッドの呼び出しでは、グラフから削除されるフィルタをキャッシュに追加するように指定できる。また、必要になりそうなフィルタがある場合は、AddFilterToCache を呼び出してそのフィルタをキャッシュに直接追加することもできる。IGraphBuilder::Render メソッド、IGraphBuilder::RenderFile メソッド、および IGraphBuilder::Connect メソッドは、キャッシュ内のフィルタを優先的に使用する。また、Reconnect メソッドでは、再接続にキャッシュ内のフィルタだけを使用するように指定することもできる。キャッシュに保持されているフィルタは、実際にはグラフの一部ではないので注意すること。キャッシュ内のフィルタは、ピンには接続されない状態で停止している。
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IGraphConfig メソッド 説明 Reconnect 2 つのピンの間の動的な再接続を実行する。 Reconfigure フィルタ グラフをロックし、アプリケーションまたはフィルタのコールバック関数を呼び出して、動的な再構成を実行する。 AddFilterToCache フィルタ キャッシュにフィルタを追加する。 RemoveFilterFromCache フィルタ キャッシュからフィルタを削除する。 EnumCacheFilter フィルタ キャッシュ内のフィルタを列挙する。 GetStartTime フィルタ グラフが最後に実行状態に切り替わったときに使用された基準タイムを取得する。 PushThroughData 指定されたピンにフィルタ グラフを通じてデータを引き渡す。 SetFilterFlags フィルタの構成情報を設定する。 GetFilterFlags フィルタの構成情報を取得する。 RemoveFilterEx フィルタ グラフからフィルタを削除する。
フィルタ キャッシュにフィルタを追加する。
構文
HRESULT AddFilterToCache( IBaseFilter *pFilter );
パラメータ
- pFilter
- [in] フィルタの IBaseFilter インターフェイスへのポインタ。
戻り値
次のいずれかの HRESULT 値を返す。
E_FAIL 失敗。 E_POINTER Null ポインタ引数。 S_FALSE フィルタは既にキャッシュに入っている。 S_OK フィルタがキャッシュに追加された。
注意
このメソッドを呼び出す前に、フィルタのピンをすべて切断しなければならない。切断しなかった場合、このメソッドは失敗する。フィルタがフィルタ グラフに含まれている場合、そのフィルタは削除される。また、フィルタが停止状態にない場合、そのフィルタは停止状態に切り替えられる。
フィルタ キャッシュ内のフィルタを列挙する。
構文
HRESULT EnumCacheFilter( IEnumFilters **pEnum );
パラメータ
- pEnum
- [out] フィルタ列挙子の IEnumFilters インターフェイスへのポインタのアドレス。
戻り値
次のいずれかの HRESULT 値を返す。
E_OUTOFMEMORY 必要なメモリの割り当てに失敗した。 E_POINTER Null ポインタ引数。 S_OK 成功。
フィルタの構成情報を取得する。
構文
HRESULT GetFilterFlags( IBaseFilter *pFilter, DWORD *pdwFlags );
パラメータ
- pFilter
- [in] フィルタ グラフのフィルタへのポインタ。
- pdwFlags
- [out] 現在の構成フラグを受け取る DWORD 型変数へのポインタ。
戻り値
次のいずれかの HRESULT 値を返す。
E_POINTER Null ポインタ引数。 S_OK 成功。 VFW_E_NOT_IN_GRAPH フィルタがグラフに含まれていない。
参照
フィルタ グラフが最後に実行状態に切り替わったときに使用された基準タイムを取得する。
構文
HRESULT GetStartTime( REFERENCE_TIME *prtStart );
パラメータ
- prtStart
- [out] 開始タイムを受け取る変数へのポインタ。
戻り値
次のいずれかの HRESULT 値を返す。
S_OK 成功。 VFW_E_WRONG_STATE フィルタ グラフが実行状態にない。
注意
フィルタ グラフが現在実行状態にないと、このメソッドは失敗する。
指定されたピンにフィルタ グラフを通じてデータを引き渡す。
構文
HRESULT PushThroughData( IPin *pOutputPin, IPinConnection *pConnection, HANDLE hEventAbort );
パラメータ
- pOutputPin
- [in] フィルタ グラフの出力ピンへのポインタ。
- pConnection
- [in] フィルタ グラフの入力ピンへのポインタ、または NULL。
- hEventAbort
- [in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、そのフィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。
戻り値
成功した場合は、S_OK を返す。それ以外の場合は、次のいずれかのエラー コードか、または一覧に示されていないその他の値を返す。
E_OUTOFMEMORY 必要なメモリの割り当てに失敗した。 VFW_E_NOT_FOUND 候補となる入力ピンが見つからない。 VFW_E_STATE_CHANGED 操作中にフィルタの状態が変化した。
注意
このメソッドは、特定の出力ピンから特定の入力ピンへ、待機中のデータを引き渡す。また、入力ピンを指定しないと、フィルタ グラフから最適な入力ピンを検索できる。データの引き渡しを行っているスレッドからは、このメソッドを呼び出さないこと。
フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。
フィルタ グラフをロックし、アプリケーションまたはフィルタのコールバック関数を呼び出して、動的な再構成を実行する。
構文
HRESULT Reconfigure( IGraphConfigCallback *pCallback, PVOID pvContext, DWORD dwFlags, HANDLE hAbortEvent );
パラメータ
- pCallback
- [in] アプリケーションまたはフィルタの IGraphConfigCallback コールバック インターフェイスへのポインタ。
- pvContext
- [in] コールバック ルーチンに渡す PVOID 型変数へのポインタ。
- dwFlags
- [in] コールバック ルーチンに渡すアプリケーションで定義したフラグ。
- hAbortEvent
- [in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、フィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。
戻り値
成功した場合は、S_OK を返す。それ以外の場合は、エラー コードを返す。フィルタ グラフをロックできなかった場合には、コールバック ルーチンが返す HRESULT にかかわりなく、エラー コードは VFW_E_WRONG_STATE となる。また、フィルタを実行状態に切り替えられなかったことを示すエラー コードもある。
注意
このメソッドは、アプリケーションまたはフィルタで特殊な動的グラフ構築を実装するために提供される。ただし、通常は IGraphConfig::Reconnect メソッドで目的を達成できる。また、実装の細かい処理の大半がメソッド側で実行されるという点でも、IGraphConfig::Reconnect メソッドを優先的に使用すること。
このメソッドを呼び出す前に、必要に応じてストリームをブロックし、グラフを通じてデータを引き渡すこと (詳細については、「IPinFlowControl::Block」および「IGraphConfig::PushThroughData」を参照すること)。コールバック メソッドが成功した場合、IGraphConfig::Reconfigure はフィルタをすべて実行状態に切り替えようとする (ブロックされているデータの流れを、呼び出し元で解除しなければならない)。それ以外の場合は、コールバック メソッドが返したエラー コードを返す。
フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。
2 つのピンの間の動的な再接続を実行する。
構文
HRESULT Reconnect( IPin *pOutputPin, IPin *pInputPin, const AM_MEDIA_TYPE *pmtFirstConnection, IBaseFilter *pUsingFilter, HANDLE hAbortEvent, DWORD dwFlags );
パラメータ
- pOutputPin
- [in] 出力ピンへのポインタ。NULL の場合がある。その場合、pInputPin が NULL であってはならない。
- pInputPin
- [in] 入力ピンへのポインタ。NULL の場合がある。その場合、pOutputPin が NULL であってはならない。
- pmtFirstConnection
- [in] 再接続の最初のピン接続に使用するメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。このパラメータが NULL の場合、最初の接続のメディア タイプは限定されない。
- pUsingFilter
- [in] 再接続に使用するフィルタへのポインタ (省略可能)。フィルタは既にグラフに含まれていなければならない。NULL の場合がある。
- hAbortEvent
- [in] イベントのハンドル。フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出す場合は、このパラメータに、フィルタが停止状態に切り替わったときに通知済になるイベントのハンドルを指定しなければならない。それ以外の場合、このパラメータは NULL でかまわない。詳細については、「注意」を参照すること。
- dwFlags
- [in] 再接続の実行方法を指定する AM_GRAPH_CONFIG_RECONNECT_FLAGS 列挙型のフラグの組み合わせ。
戻り値
成功した場合は、S_OK を返す。 それ以外の場合は、次のいずれかのエラー コードか、または一覧に示されていないその他の値を返す。
E_INVALIDARG 無効な引数。たとえば、pInputPin と pOutputPin の両方に NULL が指定された場合など。 E_NOINTERFACE 入力ピンで IPinConnection がサポートされていない。 VFW_E_CANNOT_CONNECT フィルタを接続できない。 VFW_E_STATE_CHANGED フィルタの状態が変化した。操作を完了できない。
注意
出力ピンを 1 つだけ指定すると、メソッドはもう一方のピンを検索する。ただしデフォルトでは、IFilterGraph::AddFilter メソッドでグラフに追加したフィルタが見つかると検索が失敗する。この動作をオーバーライドするには、IGraphConfig::SetFilterFlags を呼び出してフィルタの AM_FILTER_FLAGS_REMOVABLE フラグを設定する。
再接続は以下のステップで実行され、その大半はこのメソッド内で処理される。
- まず、メソッドを呼び出す前に、再構成しようとしているパスに沿ったデータの流れを確実にブロックする。呼び出し元がアプリケーションの場合、これには IPinFlowControl::Block メソッドを呼び出さなければならない。アプリケーションではなくフィルタから呼び出す場合、データの流れをフィルタ側で内部的に制御できる可能性がある。
- 指定する出力ピンと入力ピンによって、再接続の始点と終点が定義される。入力ピンは IPinConnection インターフェイスをサポートしなければならない。これらのピンのいずれかを指定しない (NULL パラメータを渡す) と、メソッドは、フィルタ グラフから再接続の候補となるピンを検索する (入力ピンは出力ピンからダウンストリームへ、出力ピンは入力ピンからアップストリームへ検索する)。
- メソッドが、フィルタ グラフを通じて待機中のデータを引き渡す (内部的に PushThroughData を呼び出す)。
- グラフに挿入するフィルタを指定した場合、そのフィルタの入力ピンに最初の出力ピンが接続され、そのフィルタの出力ピンが最後の入力ピンに接続される。フィルタを指定しなかった場合には、出力ピンが入力ピンに直接接続される。いずれの場合も、接続の確立に必要な変換フィルタがあれば挿入される。ただし、適切なフラグを設定すると、この動作をオーバーライドできる (詳細については、dwFlags パラメータの説明を参照すること)。
- 最後に、新しいフィルタが実行状態に切り替えられる。データの流れを再開することは、呼び出し元の責任である。呼び出し元がアプリケーションの場合、これには、フラグをセットせずに IPinFlowControl::Block を呼び出せばよい。
フィルタのデータ処理スレッドのいずれかからこのメソッドを呼び出すと、デッドロックに陥る危険性がある。このメソッドがフィルタ グラフをロックするため、IMediaFilter::Stop の呼び出しを受け取ったとき、フィルタが停止できない可能性がある。この状況を避けるため、このメソッドはフィルタが提供するイベント オブジェクトのハンドルを利用する。フィルタは、その Stop メソッドの呼び出しを受け取ったら、イベントを通知しなければならない。
フィルタ グラフからフィルタを削除する。
構文
HRESULT RemoveFilterEx( IBaseFilter *pFilter, DWORD Flags );
パラメータ
- pFilter
- [in] グラフから削除するフィルタへのポインタ。
- Flags
- [in] REM_FILTER_FLAGS 列挙型のフラグの組み合わせ。
戻り値
成功した場合は、S_OK を返す。それ以外の場合は、失敗の原因を示す HRESULT 値を返す。
注意
このメソッドは、IFilterGraph::RemoveFilter メソッドをメソッドの動作を指定するフラグを受け付けるように拡張したものである。このフラグを使うと、アプリケーションは自動的にピンから切り離すことなくフィルタを削除できる、それは接続されているフィルタ グループを新しいグラフに移動するときパフォーマンスを改善する。
デフォルトでは、削除の前にフィルタが切断される。フィルタを切断しないためには、REMFILTERF_LEAVECONNECTED フラグを使用する。
フィルタ キャッシュからフィルタを削除する。
構文
HRESULT RemoveFilterFromCache( IBaseFilter *pFilter );
パラメータ
- pFilter
- [in] キャッシュから削除するフィルタへのポインタ。
戻り値
次のいずれかの HRESULT 値を返す。
E_POINTER Null ポインタ引数。 S_FALSE フィルタがキャッシュに入っていない。 S_OK キャッシュからのフィルタの削除に成功した。
フィルタの構成情報を設定する。
構文
HRESULT SetFilterFlags( IBaseFilter *pFilter, DWORD dwFlags );
パラメータ
- pFilter
- [in] フィルタ グラフのフィルタへのポインタ。
- dwFlags
- [in] 新しい構成フラグを指定する値。可能な値は次のいずれかである。
ゼロ (0) フラグをセットしない。 AM_FILTER_FLAGS_REMOVABLE 動的な再接続の間にフィルタを削除できる。詳細については、「注意」を参照すること。
戻り値
次のいずれかの HRESULT 値を返す。
E_POINTER Null ポインタ引数。 E_INVALIDARG 無効な引数。 S_OK 成功。 VFW_E_NOT_IN_GRAPH フィルタがグラフに含まれていない。
注意
AM_FILTER_FLAGS_REMOVABLE フラグは、IGraphConfig::Reconnect メソッドの動作を変更する。Reconnect メソッドは、2 つのピンの間の動的な再接続を実行する。一方のピンだけを指定し、もう片方のピンを指定しなかった場合、Reconnect は指定されたピンからアップストリームまたはダウンストリームに向かって適切なピンを検索する。ただしデフォルトでは、IFilterGraph::AddFilter メソッドでグラフに追加したフィルタが見つかると検索が失敗する。この動作をオーバーライドするには、SetFilterFlags を呼び出してフィルタの AM_FILTER_FLAGS_REMOVABLE フラグを設定する。