Microsoft DirectX 8.0

IGraphBuilder インターフェイス

このインターフェイスは、アプリケーションからフィルタ グラフを構築するメソッドを提供する。フィルタ グラフ マネージャがこのインターフェイスを実装する。

IGraphBuilderIFilterGraph インターフェイスを継承する。IFilterGraph が提供するのは、グラフへのフィルタの追加、2 つのピンの接続などの基本的な操作である。IGraphBuilder は、これらに加えて部分的な情報からグラフを構築するメソッドを提供する。たとえば、RenderFile メソッドは、指定されたファイル名に対応するファイル再生用のグラフを構築する。また、Render メソッドは、出力ピンに新しいフィルタを接続して、そのピンからのデータをレンダリングする。

これらのメソッドを使用すると、そのグラフのフィルタとピン接続を、アプリケーションから個別に指定する手間を省くことができる。アプリケーションの代わりに、フィルタ グラフ マネージャが、ユーザーのシステムに登録されているフィルタから選択したフィルタを、グラフに導入して接続する。フィルタ グラフ マネージャは、内部的にフィルタ マッパーを使用してレジストリ内のフィルタを検索する。詳細については、「IFilterMapper2」を参照すること。

vtable 順のメソッド

IUnknown メソッド説明
QueryInterface サポートされているインターフェイスへのポインタを取得する。
AddRef 参照カウントをインクリメントする。
Release 参照カウントをデクリメントする。
IFilterGraph メソッド説明
AddFilterグラフにフィルタを追加し、そのフィルタに名前を付ける。
RemoveFilterグラフからフィルタを削除する。
EnumFiltersグラフのフィルタすべてに対して列挙子を提供する。
FindFilterByName特定の名前で追加されたフィルタを検索する。
ConnectDirect2 つのピンを直接接続する (フィルタを通さない)。
Reconnect既存のピン接続を切断し、同じピンに再接続する。
Disconnect特定のピンを切断する。
SetDefaultSyncSourceデフォルトの同期基準 (クロック) を設定する。
IGraphBuilder メソッド説明
Connect2 つのピンを接続する。直接接続できない場合は変形を介して接続する。
Render特定の出力ピンにフィルタ チェーンを追加してレンダリングする。
RenderFile指定されたファイルをレンダリングするフィルタ グラフを構築する。
AddSourceFilter特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。
SetLogFileログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。
Abort現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。
ShouldOperationContinue現在の操作が継続すべきかどうかを照会する。

IGraphBuilder::Abort

IGraphBuilder インターフェイス

現在のタスクからできる限り早く戻るようにグラフ ビルダに要求する。

現在のタスクが完了するかどうかはわからない。グラフ ビルダを現在のタスクから最も早く戻すには、グラフ ビルダにそれを完了させる事が一番だ。

構文

HRESULT Abort(void);

戻り値

S_OK を返す。

IGraphBuilder::AddSourceFilter

IGraphBuilder インターフェイス

特定のファイルに対応するフィルタ グラフにソース フィルタを追加する。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_POINTERNULL ポインタ引数。
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 メソッドは同じソース フィルタを追加する。

IGraphBuilder::Connect

IGraphBuilder インターフェイス

2 つのピンを接続する (必要に応じて中間フィルタを使用)。

構文

HRESULT Connect(
    IPin *ppinOut,
    IPin *ppinIn
);

パラメータ

ppinOut
[in] 出力ピンへのポインタ。
ppinIn
[in] 入力ピンへのポインタ。

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK成功。
VFW_S_PARTIAL_RENDERこのムービーにサポートされないフォーマットのストリームが含まれている。
E_ABORT 操作が中止された。
E_POINTERNULL ポインタ引数。
VFW_E_CANNOT_CONNECT接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_NOT_IN_GRAPHフィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。

注意

このメソッドは、2 つのピンを直接接続するか、または必要に応じて変換フィルタを使用して間接的に接続する。失敗した場合、メソッドはファイル グラフを変更しない。フィルタ グラフ マネージャは、まずピンを直接接続しようとする。これに失敗すると、既にフィルタ グラフに属しているフィルタが提供する利用可能な変換のいずれかを使用しようとする (このとき列挙の順序は任意である)。これに失敗すると、さらに、変換を提供するフィルタをレジストリから検索しようとする。このときはメリット順に試す。

接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。

IGraphBuilder::Render

IGraphBuilder インターフェイス

この出力ピンからのデータをレンダリングするフィルタ グラフを構築する。

構文

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_POINTERNULL ポインタ引数。
VFW_E_CANNOT_CONNECT接続を確立する中間フィルタの組み合わせが見つからなかった。
VFW_E_CANNOT_RENDERストリームをレンダリングするフィルタの組み合わせが見つからなかった。
VFW_E_NO_ACCEPTABLE_TYPESこれらのピンに共通のメディア タイプがない。
VFW_E_NOT_IN_GRAPHフィルタ グラフに存在しないオブジェクトに要求された関数を実行できない。

注意

このメソッドは、レンダリングするフィルタにこの出力ピンを、直接接続するか、または必要に応じて変換フィルタを中間フィルタとして使用して間接的に接続する。フィルタは IGraphBuilder::Connect メソッドの場合と同じ順序で試される。

接続処理では、中間フィルタのピン名が ~ (チルダ) で始まる場合、フィルタ グラフ マネージャはそのフィルタのピンを無視する。詳細については、「PIN_INFO」を参照すること。

IGraphBuilder::RenderFile

IGraphBuilder インターフェイス

指定されたファイルをレンダリングするフィルタ グラフを構築する。

構文

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_POINTERNULL ポインタ引数。
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 カムコーダのようなキャプチャ デバイスのデバイス モニカを指定することもできる。フィルタ グラフ マネージャは単純なプレビューグラフを作成する。

IGraphBuilder::SetLogFile

IGraphBuilder インターフェイス

ログ ファイルを設定する。このファイルには操作を実行しようとしたとき行われた各アクションが出力される。

構文

HRESULT SetLogFile(
    HANDLE hFile
);

パラメータ

hFile
ログ ファイルのハンドル。

戻り値

S_OK を返す。

注意

このメソッドは、デバッグに使用し、フィルタ グラフの自動構築に失敗したとき、その原因を判断することを目的としている。

hFile パラメータは、開いたファイル ハンドルでなければならない。ファイルを開き、ログ出力が終わってからファイルを閉じることは、アプリケーション側の責任である。ファイル ハンドルを閉じる前に、ファイル ハンドル NULL で SetLogFile を呼び出す。こうすると、既に閉じたファイル ハンドルをコンポーネントが使用しないように防止できる。

IGraphBuilder::ShouldOperationContinue

IGraphBuilder インターフェイス

現在の操作が継続すべきかどうかを照会する。グラフからの要求に基づいて何らかの操作を実行しているフィルタでは、このメソッドを呼び出して、その操作が継続すべきかどうかを判断できる。通常、アプリケーションからこのメソッドを呼び出すことはない。

構文

HRESULT ShouldOperationContinue(void);

戻り値

HRESULT を返す。設定される値は次のとおりである。

S_OK現在の操作は継続しなければならない。
S_FALSE 現在の操作が継続してはならない。
E_UNEXPECTED 予期せぬエラー。