Microsoft DirectX 8.0 |
このインターフェイスは、フィルタ グラフを通るデータの流れを制御するメソッドを提供する。ここには、グラフを実行、ポーズ、および停止するメソッドが含まれる。フィルタ グラフ マネージャがこのインターフェイスを実装する。フィルタグラフの状態についての詳細については、「フィルタ グラフのデータ フロー」を参照すること。
IMediaControl はグラフを構築する Automation 互換のメソッドも提供する。Microsoft® Visual Basic® アプリケーションでは、これらのメソッドを使用して、フィルタ グラフを構築したり、グラフに関する情報を取得したりすることができる。C/C++ アプリケーションでは、このインターフェイスではなく、効率のよい IGraphBuilder および IFilterGraph2 のメソッドを使用すること。
vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IDispatch メソッド 説明 GetTypeInfoCount このディスプインターフェイスにタイプ情報が利用可能かどうかを判断する。 GetTypeInfo GetTypeInfoCount が成功した場合に、このディスプインターフェイスのタイプ情報を取得する。 GetIDsOfNames (引数を含む) プロパティおよびメソッドのテキスト名を対応するディスパッチ識別子 (DISPID) に変換する。 Invoke DISPID およびその他の必要なパラメータが指定された場合は、このディスプインターフェイスのメソッドを呼び出すか、またはプロパティにアクセスする。 IMediaControl メソッド 説明 Run フィルタ グラフのすべてのフィルタを実行する。 Pause フィルタ グラフのフィルタをすべてポーズする。 Stop フィルタ グラフのすべてのフィルタを停止する。 StopWhenReady フィルタがキューに入れられるようにフィルタグラフをポーズにし、次にフィルタグラフを停止する。 GetState フィルタ グラフの状態を取得する。 RenderFile Visual Basic アプリケーションで用いられ、指定したファイルをレンダリングするフィルタグラフを構築する。 AddSourceFilter Visual Basic で用いられ、与えられたファイル名を読み込むことのできるソースフィルタをグラフに追加する。 get_FilterCollection Visual Basic アプリケーションで用いられ、グラフのフィルタを表す IFilterInfo インターフェイスの集合を取得し、指定したファイルをレンダリングするフィルタ グラフを構築する。 get_RegFilterCollection Visual Basic アプリケーションで用いられ、ローカル システムで利用可能な登録されたフィルタを表す IRegFilterInfo インターフェイスの集合を取得する。
Visual Basic で用いられ、与えられたファイル名を読み込むことのできるソースフィルタをグラフに追加する。
構文
HRESULT AddSourceFilter( BSTR strFilename, IDispatch **ppUnk );
パラメータ
- strFilename
- [in] ソース ビデオが格納されたファイルの名前。
- ppUnk
- [out] フィルタの IFilterInfo インターフェイスを受け取るポインタのアドレス。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。 VFW_E_CANNOT_LOAD_SOURCE_FILTER このファイルのソース フィルタをロードできない。 VFW_E_NOT_FOUND オブジェクトまたは名前が見つからなかった。 VFW_E_UNKNOWN_FILE_TYPE このファイルのメディア タイプが認識されない。
注意
このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IGraphBuilder::AddSourceFilter メソッドを呼び出すこと。
Visual Basic アプリケーションで用いられ、グラフのフィルタを表す IFilterInfo インターフェイスの集合を取得し、指定したファイルをレンダリングするフィルタ グラフを構築する。
構文
HRESULT get_FilterCollection( IDispatch **ppUnk );
パラメータ
- ppUnk
- [out, retval] IFilterInfo オブジェクトの集合の IAMCollection インターフェイスを受け取るポインタのアドレス。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。
注意
このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IFilterGraph::EnumFilters メソッドを呼び出すこと。
Visual Basic アプリケーションで用いられ、ローカル システムで利用可能な登録されたフィルタを表す IRegFilterInfo インターフェイスの集合を取得する。
構文
HRESULT get_RegFilterCollection( IDispatch **ppUnk );
パラメータ
- ppUnk
- [out, retval] IAMCollection オブジェクトの IDispatch インターフェイスを受け取るポインタのアドレス。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。
注意
このメソッドは IDispatch インターフェイス ポインタを返す。したがって、主に Automation クライアントから使用する。C/C++ アプリケーションでこの操作を最も効率よく実行するには、IFilterMapper::EnumMatchingFilters メソッドを呼び出すこと。
フィルタ グラフの状態 (ポーズ、実行、または停止) を取得する。
状態は必ずしも同期して移行するとは限らない。したがって、このメソッドを呼び出したとき、フィルタ グラフは新しい状態に移行している途中かもしれない。その場合、移行が完了するか、または指定されたタイムアウト時間が過ぎるまで、メソッドはブロックする。
構文
HRESULT GetState( LONG msTimeout, OAFilterState *pfs );
パラメータ
- msTimeout
- [in] タイムアウトの時間幅 (ミリ秒単位)、またはタイムアウト時間が無制限であることを指定する INFINITE。
- pfs
- [out] 返された (フィルタ グラフの) 状態を受け取るポインタ。この値は FILTER_STATE 列挙型のメンバである。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 VFW_S_STATE_INTERMEDIATE フィルタ グラフは取得された状態に移行中。 VFW_S_CANT_CUE フィルタ グラフはポーズしているが、データをキューに入れることができない。 E_FAIL 失敗。
注意
アプリケーションはこのメソッドを使って IMediaControl::Run 呼び出し後再生が開始されたかどうかを確かめることができる。一般的に、アプリケーションはフィルタ グラフをどの状態にしたかをトラックするメカニズムを自分自身で持つべきだ。通常アプリケーションは現在の状態を使って、どのユーザー インターフェイス コントロールが使用可能にするかを決定する。たとえば、グラフが実行状態にあるなら、アプリケーションは「再生」ボタンを使用不可にし、「停止」と「ポーズ」ボタンを使用可能にする。
フィルタ グラフが新しい状態に移行中である場合は、以前の状態ではなく新しい状態が返される。
メソッドがブロックされているときに、別のスレッドから呼び出して状態を変更すると、このメソッドはエラーを返す。
GetState での待機中にスレッドはメッセージを処理できないため、タイムアウト値への INFINITE の指定は避けること。Windows メッセージを処理するスレッドから GetState を呼び出す場合は、ユーザー入力への応答に支障がないように、できるだけ短い待機時間を指定すること。特に、ネットワークやインターネット経由でソースがストリームされる場合は、状態の移行が完了するまでに非常に時間がかかるため、注意が必要である。
フィルタ グラフの状態の詳細については、「フィルタ グラフのデータ フロー」を参照すること。
フィルタ グラフのフィルタをすべてポーズする。
フィルタ グラフをポーズすると、次にグラフを実行するとき即座にレンダリングするため、グラフがキューに入る。グラフがポーズしているとき、データは処理されるが、レンダリングは行われない。データは、バッファに余裕がある限り、グラフに引き渡され、変換フィルタで処理されるが、そのデータをレンダリング フィルタがレンダリングすることはない。ただし、ビデオ レンダラは現在のサンプルの静止したポスター フレームを表示する。
構文
HRESULT Pause(void);
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_FALSE グラフのポーズに成功したが、状態の移行が完了していないフィルタがある。 S_OK グラフのフィルタがすべてポーズ状態への移行を完了した。
注意
このメソッドが S_FALSE を返す場合は、GetState メソッドを呼び出して、状態の移行の完了を待機するか、または移行が完了しているか確認すること。
失敗した場合、メソッドは、戻る前にグラフを停止する。
Visual Basic アプリケーションで用いられ、指定したファイルをレンダリングするフィルタグラフを構築する。
構文
HRESULT RenderFile( BSTR strFilename );
パラメータ
- strFilename
- レンダリングするファイルの名前。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 VFW_S_AUDIO_NOT_RENDERED オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。 VFW_S_DUPLICATE_NAME 名前が重複しているフィルタの追加が、変更後の名前で成功した。 VFW_S_PARTIAL_RENDER このムービーにサポートされないフォーマットのストリームが含まれている。 VFW_S_VIDEO_NOT_RENDERED ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。 E_ABORT 操作が中止された。 VFW_E_CANNOT_CONNECT 接続を確立する中間フィルタの組み合わせが見つからなかった。 VFW_E_CANNOT_LOAD_SOURCE_FILTER このファイルのソース フィルタをロードできない。 VFW_E_CANNOT_RENDER ストリームをレンダリングするフィルタの組み合わせが見つからなかった。 VFW_E_INVALID_FILE_FORMAT ファイル フォーマットが無効。 VFW_E_NOT_FOUND オブジェクトまたは名前が見つからなかった。 VFW_E_NOT_IN_GRAPH フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。 VFW_E_UNKNOWN_FILE_TYPE このファイルのメディア タイプが認識されない。 VFW_E_UNSUPPORTED_STREAM ファイルを再生できない。フォーマットがサポートされていない。
注意
このメソッドでは、アプリケーションからフィルタ グラフ マネージャに、レンダリングするメディア ファイルの名前を渡すことができる。フィルタ グラフ マネージャは、そのファイルの再生に必要なフィルタのグラフを構築する。このメソッドは、IGraphBuilder::RenderFile メソッドと同等の役目をする Automation 互換のメソッドである。C/C++ アプリケーションではこのメソッドを使用すること。
フィルタ グラフのすべてのフィルタを実行する。グラフが実行中、データはグラフを通って移動しレンダリングされる。
構文
HRESULT Run (void);
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_FALSE グラフは実行の準備をしているが、実行状態への移行が完了していないフィルタがある。 S_OK グラフのフィルタがすべて実行状態への移行を完了した。
注意
IMediaControl::Pause あるいは IMediaControl::Stop が呼び出されるまで、メソッドは実行状態になる。再生がストリームの終りについたとき、フィルタはそれ以上データを流せないが、グラフは実行のままである。そのとき、アプリケーションはグラフを停止あるいはポーズにできる。エンドオブストリーム (EOS) イベントの詳細については、「IMediaEvent」と「EC_COMPLETE」を参照すること。
このメソッドはストリームの初めまでシークしない。グラフを実行し、それをポーズして、次に再度それを実行すると、ポーズ位置から再生される。エンドオブストリーム (EOS) まで着いた後で、グラフを実行させると、何も起こらない。グラフをシークするには、IMediaSeeking インターフェイスを使うこと。
このメソッドが S_FALSE を返す場合は、GetState メソッドを呼び出して、状態の移行の完了を待機することができる。メソッドが失敗した場合、グラフの一部のフィルタは実行状態に切り替えられている可能性がある。ストリームが複数あるグラフでは、ストリームがすべて正常に再生されることもある。グラフを停止するかどうかはアプリケーション側で判断しなければならない。
グラフのフィルタをすべて停止する。
構文
HRESULT Stop(void);
戻り値
成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。
注意
グラフが実行中なら、今メソッドはそれを停止させる前にポーズさせる。ポーズ中は、ビデオ レンダラは現在のフレームをポスター フレームとしてディスプレイにコピーできる。
このメソッドはストリームの初めまでシークしない。このメソッドを呼び出し、次に IMediaControl::Run を呼び出すと、停止位置から再生される。グラフをシークするには、IMediaSeeking インターフェイスを使うこと。
フィルタ グラフ マネージャはグラフ内のすべてのフィルタで Pause を呼び出し、次にポーズ操作の完了を待たずすべてのフィルタで IMediaFilter::Stopメソッドを呼び出す。それゆえポーズ操作の完了前に Stop メソッドの呼び出しを受け取るフィルタがあるかもしれない。カスタム レンダリング フィルタを開発しているなら、こういったケースを考慮して、実行状態にまだある間に Stop を受け取ったら、最初にフィルタをポーズするようにしなければならない。しかし、ほとんどのフィルタはこういった場合に特に何かする必要はない。
参照
IMediaControl::StopWhenReady
フィルタがキューに入れられるようにフィルタ グラフをポーズにし、次にフィルタ グラフを停止する。
構文
HRESULT StopWhenReady(void);戻り値
成功した場合は、S_OK を返す。それ以外の場合は、エラーの原因を示す HRESULT 値を返す。
注意
グラフが停止しているときフィルタ グラフをシークしたいなら、このメソッドは有用である。フィルタグラフが停止している限り、現在位置の変更をしても新しいフレームでビデオ ウィンドウを再描画はしない。それゆえ、IMediaSeeking::SetPositions はビデオ ウィンドウをアップデートしない。シーク操作後ウィンドウをアップデートするには StopWhenReady を呼び出す。このメソッドはグラフをポーズ状態に移行させ、ポーズ処理が完了するのを待ち、グラフを停止状態に再度移行させる。ポーズ処理はデータをグラフのキューに入れるので、ビデオ レンダラはそれを受け取り、新しいフレームを表示する。
このメソッドは非同期である。それはここのスレッドのポーズが完了するのを待つ。呼び出されたスレッドはブロックせず、アプリケーションはユーザー入力に反応することができる。メソッドが帰ると、ポーズ操作が完了する前であっても、グラフの論理状態は停止となる。この時点で GetState メソッドを呼び出すと State_Stopped が返る。
ポーズ操作が完了する前に (ポーズ、実行、シークのような) 状態変更コマンドを受け取ると、新しいコマンドは途中の stop コマンドをキャンセルする。ポーズ操作は完了するが、グラフは停止しない。