Microsoft DirectX 8.0 |
このインターフェイスは、アプリケーションからフィルタ グラフを構築するメソッドを提供する。フィルタ グラフ マネージャがこのインターフェイスを実装する。
IGraphBuilder は IFilterGraph インターフェイスを継承する。IFilterGraph が提供するのは、グラフへのフィルタの追加、2 つのピンの接続などの基本的な操作である。IGraphBuilder は、これらに加えて部分的な情報からグラフを構築するメソッドを提供する。たとえば、RenderFile メソッドは、指定されたファイル名に対応するファイル再生用のグラフを構築する。また、Render メソッドは、出力ピンに新しいフィルタを接続して、そのピンからのデータをレンダリングする。
これらのメソッドを使用すると、そのグラフのフィルタとピン接続を、アプリケーションから個別に指定する手間を省くことができる。アプリケーションの代わりに、フィルタ グラフ マネージャが、ユーザーのシステムに登録されているフィルタから選択したフィルタを、グラフに導入して接続する。フィルタ グラフ マネージャは、内部的にフィルタ マッパーを使用してレジストリ内のフィルタを検索する。詳細については、「IFilterMapper2」を参照すること。
vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IFilterGraph メソッド 説明 AddFilter グラフにフィルタを追加し、そのフィルタに名前を付ける。 RemoveFilter グラフからフィルタを削除する。 EnumFilters グラフのフィルタすべてに対して列挙子を提供する。 FindFilterByName 特定の名前で追加されたフィルタを検索する。 ConnectDirect 2 つのピンを直接接続する (フィルタを通さない)。 Reconnect 既存のピン接続を切断し、同じピンに再接続する。 Disconnect 特定のピンを切断する。 SetDefaultSyncSource デフォルトの同期基準 (クロック) を設定する。 IGraphBuilder メソッド 説明 Connect 2 つのピンを接続する。直接接続できない場合は変形を介して接続する。 Render 特定の出力ピンにフィルタ チェーンを追加してレンダリングする。 RenderFile 指定されたファイルをレンダリングするフィルタ グラフを構築する。 AddSourceFilter 特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。 SetLogFile ログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。 Abort 現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。 ShouldOperationContinue 現在の操作が継続すべきかどうかを照会する。
現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。
現在のタスクが完了するかどうかはわからない。グラフ ビルダを現在のタスクから最も早く戻すには、グラフ ビルダにそれを完了させる事が一番だ。
構文
HRESULT Abort(void);
戻り値
S_OK を返す。
特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。IGraphBuilder::RenderFile メソッドはこのメソッドを呼び出してソース フィルタを検索する。
構文
HRESULT AddSourceFilter( LPCWSTR lpwstrFileName, LPCWSTR lpwstrFilterName, IBaseFilter **ppFilter );
パラメータ
- lpwstrFileName
- [in] ファイルへのポインタ。
- lpwstrFilterName
- [in] 追加するソース フィルタに付ける名前へのポインタ。
- ppFilter
- [out] 追加されたフィルタの IBaseFilter インターフェイスへのポインタのアドレス。
戻り値
HRESULT を返す。設定される値は次のとおりである。
S_OK 成功。 E_NOINTERFACE ソース フィルタで IFileSourceFilter インターフェイスがサポートされていない。 E_OUTOFMEMORY メモリ不足。 E_POINTER NULL ポインタ引数。 VFW_E_CANNOT_LOAD_SOURCE_FILTER このファイルのソース フィルタをロードできない。 VFW_E_NOT_FOUND オブジェクトまたは名前が見つからなかった。 VFW_E_UNKNOWN_FILE_TYPE このファイルのメディア タイプが認識されない。
注意
このメソッドを使用すると、グラフの残り部分の構築についてより詳細に制御し、正確に把握することができる。たとえば、IFilterGraph::AddFilter メソッドを使用して好みのレンダラを追加したうえで、IGraphBuilder::Connect メソッドを使用して 2 つのフィルタを接続することができる。そのソース フィルタが公開する IBaseFilter インターフェイスは、ppFilter パラメータに返され、参照は IUnknown::AddRef メソッドで既に追加されている。lpwstrFilterName パラメータを使用すると、このフィルタ グラフ内ではこの名前でフィルタを識別できる。詳細については、「FindFilterByName」を参照すること。
フィルタ グラフの残り部分を構築するために、追加するソース フィルタの出力ピンを探すことは、アプリケーション側の責任である。それには、出力ピンの IGraphBuilder::Render を呼び出して、フィルタ グラフ全体を自動的に構築するか、またはフィルタを個別に追加および接続する。フィルタを個別に追加する場合、非同期ファイル リーダー ソース フィルタおよび URL モニカ ソース フィルタではデータが解析されないため、これらのソース フィルタの出力ピンは、MPEG スプリッタ フィルタなどのパーサー フィルタにのみ接続できる。
IGraphBuilder::RenderFile メソッドは同じソース フィルタを追加する。
2 つのピンを接続する (必要に応じて中間フィルタを使用)。
構文
HRESULT Connect( IPin *ppinOut, IPin *ppinIn );
パラメータ
- ppinOut
- [in] 出力ピンへのポインタ。
- ppinIn
- [in] 入力ピンへのポインタ。
戻り値
HRESULT を返す。設定される値は次のとおりである。
S_OK 成功。 VFW_S_PARTIAL_RENDER このムービーにサポートされないフォーマットのストリームが含まれている。 E_ABORT 操作が中止された。 E_POINTER NULL ポインタ引数。 VFW_E_CANNOT_CONNECT 接続を確立する中間フィルタの組み合わせが見つからなかった。 VFW_E_NOT_IN_GRAPH フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。
注意
このメソッドは、2 つのピンを直接接続するか、または必要に応じて変換フィルタを使用して間接的に接続する。失敗した場合、メソッドはファイル グラフを変更しない。フィルタ グラフ マネージャは、まずピンを直接接続しようとする。これに失敗すると、既にフィルタ グラフに属しているフィルタが提供する利用可能な変換のいずれかを使用しようとする (このとき列挙の順序は任意である)。これに失敗すると、さらに、変換を提供するフィルタをレジストリから検索しようとする。このときはメリット順に試す。
接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。
この出力ピンからのデータをレンダリングするフィルタ グラフを構築する。
構文
HRESULT Render( IPin *ppinOut );
パラメータ
- ppinOut
- [in] 出力ピンへのポインタ。
戻り値
HRESULT を返す。設定される値は次のとおりである。
S_OK 成功。 VFW_S_AUDIO_NOT_RENDERED オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。 VFW_S_DUPLICATE_NAME 名前が重複しているフィルタの追加が、変更後の名前で成功した。 VFW_S_PARTIAL_RENDER このムービーにサポートされないフォーマットのストリームが含まれている。 VFW_S_VIDEO_NOT_RENDERED ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。 E_ABORT 操作が中止された。 E_POINTER NULL ポインタ引数。 VFW_E_CANNOT_CONNECT 接続を確立する中間フィルタの組み合わせが見つからなかった。 VFW_E_CANNOT_RENDER ストリームをレンダリングするフィルタの組み合わせが見つからなかった。 VFW_E_NO_ACCEPTABLE_TYPES これらのピンに共通のメディア タイプがない。 VFW_E_NOT_IN_GRAPH フィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。
注意
このメソッドは、レンダリングするフィルタにこの出力ピンを、直接接続するか、または必要に応じて変換フィルタを中間フィルタとして使用して間接的に接続する。フィルタは IGraphBuilder::Connect メソッドの場合と同じ順序で試される。
接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。
指定されたファイルをレンダリングするフィルタ グラフを構築する。
構文
HRESULT RenderFile( LPCWSTR lpwstrFile, LPCWSTR lpwstrPlayList );
パラメータ
- lpwstrFile
- [in] レンダリング対象データが格納されたファイルの名前、またはキャプチャ デバイスのモニカへのポインタ。
- lpwstrPlayList
- [in] 予約済み。NULL でなければならない。
戻り値
HRESULT を返す。設定される値は次のとおりである。
S_OK 成功。 VFW_S_AUDIO_NOT_RENDERED オーディオ ストリームを再生できない。適切なレンダラが見つからなかった。 VFW_S_DUPLICATE_NAME 名前が重複しているフィルタの追加が、変更後の名前で成功した。 VFW_S_PARTIAL_RENDER このムービーにサポートされないフォーマットのストリームが含まれている。 VFW_S_VIDEO_NOT_RENDERED ビデオ ストリームを再生できない。適切なレンダラが見つからなかった。 E_ABORT 操作が中止された。 E_FAIL 失敗。 E_INVALIDARG 引数が無効。 E_OUTOFMEMORY メモリ不足。 E_POINTER NULL ポインタ引数。 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::Connect メソッドの場合と同じ順序で試される。
接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。
指定したファイルのメディア タイプと圧縮スキームを確認するために、フィルタ グラフ マネージャはファイルの最初の数バイトを読み込み、カスタム ファイル タイプの登録に記述されているファイル署名を探す。
lpwstrFile パラメータは GraphEdit .grf ファイルを指定することができる。フィルタ グラフ マネージャはグラフをそのファイルからロードする。
lpwstrFile パラメータは USB カメラや DV カムコーダのようなキャプチャ デバイスのデバイス モニカを指定することもできる。フィルタ グラフ マネージャは単純なプレビューグラフを作成する。
ログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。
構文
HRESULT SetLogFile( HANDLE hFile );
パラメータ
- hFile
- ログ ファイルのハンドル。
戻り値
S_OK を返す。
注意
このメソッドは、デバッグに使用し、フィルタ グラフの自動構築に失敗したとき、その原因を判断することを目的としている。
hFile パラメータは、開いたファイル ハンドルでなければならない。ファイルを開き、ログ出力が終わってからファイルを閉じることは、アプリケーション側の責任である。ファイル ハンドルを閉じる前に、ファイル ハンドル NULL で SetLogFile を呼び出す。こうすると、既に閉じたファイル ハンドルをコンポーネントが使用しないように防止できる。
現在の操作が継続すべきかどうかを照会する。グラフからの要求に基づいて何らかの操作を実行しているフィルタでは、このメソッドを呼び出して、その操作が継続すべきかどうかを判断できる。通常、アプリケーションからこのメソッドを呼び出すことはない。
構文
HRESULT ShouldOperationContinue(void);
戻り値
HRESULT を返す。設定される値は次のとおりである。
S_OK 現在の操作は継続しなければならない。 S_FALSE 現在の操作が継続してはならない。 E_UNEXPECTED 予期せぬエラー。