Microsoft DirectX 8.0 |
注 : このインターフェイスの使用は避けること。既存のアプリケーションとの後方互換性を保つため、継続してサポートされるが、新しいアプリケーションでは ICaptureGraphBuilder2 インターフェイスを使用すること。
ICaptureGraphBuilder インターフェイスを利用すると、キャプチャ グラフ、プレビュー グラフ、ファイル再圧縮グラフ、または特殊なカスタム グラフまで簡単に作成できる。
このインターフェイスを使って、WDM フィルタを使用するキャプチャ グラフを作成するときは、TV チューナー フィルタやアナログ ビデオ クロスバー フィルタなど、特別なアップストリーム フィルタをグラフに追加する必要がある。これらのフィルタは、RenderStream メソッドや FindInterface を呼び出して、キャプチャ フィルタのピンをレンダリングしたとき、フィルタ グラフに組み込まれる。
このインターフェイスを実装しないこと。このインターフェイスは Microsoft® DirectShow® が自動的に実装する。
キャプチャ アプリケーションおよび再圧縮アプリケーションでこのインターフェイスを使って、フィルタ グラフの作成を簡易化する。
vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 ICaptureGraphBuilder メソッド 説明 SetFiltergraph 使用するフィルタ グラフをグラフ ビルダ オブジェクトに通知する。 GetFiltergraph ビルダが使用しているフィルタ グラフを取得する。 SetOutputFileName 指定されたファイル名でビットをディスクに保存するフィルタ グラフのレンダリング セクションを作成する。 FindInterface 指定されたインターフェイスをフィルタ、フィルタのアップストリームおよびダウンストリームで検索する。また、オプションで、指定されたインターフェイスを特定のカテゴリの出力ピンでのみ検索する。 RenderStream オプションで指定されるカテゴリのソース フィルタのピンを、オプションでほかのフィルタを経由して、レンダリング フィルタに接続する。 ControlStream グラフ内の 1 つ以上のキャプチャ フィルタ上の指定されたカテゴリのピンにストリーム コントロール メッセージを送る。 AllocCapFile キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。 CopyCaptureFile あらかじめ割り当てられたキャプチャ ファイルから有効なメディア データをコピーする。
キャプチャ ファイルを指定されたサイズにあらかじめ割り当てる。
構文
HRESULT AllocCapFile( LPCOLESTR lpwstr, DWORDLONG dwlSize );
パラメータ
- lpwstr
- [in] 作成する、またはサイズを変更するファイルの名前が格納された Unicode 文字列へのポインタ。
- dwSize
- [in] 割り当てられるファイルのサイズ (バイト単位)。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。
注意
ファイルが読み取り専用の場合、この呼び出しは失敗する。キャプチャで最良の結果を得るには、常に、キャプチャ データよりサイズが大きく、最適化され、あらかじめ割り当てられたキャプチャ ファイルにキャプチャする。
このインターフェイスの現在の DirectShow 実装環境では、Windows NT® 4.x プラットフォーム上または Windows 2000 プラットフォーム上より、Windows 9x プラットフォーム上の方がこのメソッドの呼び出しがずっと高速である点に注意すること。
グラフ内の 1 つ以上のキャプチャ フィルタ上の指定されたカテゴリのピンにストリーム コントロール メッセージを送る。
構文
HRESULT ControlStream( const GUID *pCategory, IBaseFilter *pFilter, REFERENCE_TIME *pstart, REFERENCE_TIME *pstop, WORD wStartCookie, WORD wStopCookie );
パラメータ
- pCategory
- [in] 出力ピン カテゴリを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。この値を NULL にすることはできない。
- pFilter
- [in] 制御するフィルタの IBaseFilter インターフェイスへのポインタ。NULL を指定すると、グラフ内のすべてのキャプチャ フィルタが制御される。各キャプチャ フィルタにつき 1 つの通知が取得される。
- pstart
- [in] キャプチャの開始タイムへのポインタ。NULL は今すぐ開始することを意味する。MAX_TIME は前の要求をキャンセルするか、前の要求がない場合は、何もしないことを意味する。
- pstop
- [in] キャプチャの終了タイムへのポインタ。NULL は今すぐ終了することを意味する。MAX_TIME は前の要求をキャンセルするか、前の要求がない場合は、何もしないことを意味する。
- wStartCookie
- [in] 開始動作が起きたときに送る特定の値を指定する。
- wStopCookie
- [in] 終了動作が起きたときに送る特定の値を指定する。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。現在実装されている DirectShow は、キャプチャ フィルタから送られた最後のサンプルがレンダリングされる前に終了通知が送られると S_FALSE を返し、それ以外の場合は S_OK を返す。
このメソッドが S_FALSE を返した場合、アプリケーションは、すべてのサンプルがグラフを通過してレンダリングされるまで、フィルタ グラフの終了を待機した方がよい。そうしないと、サンプルが失われることがある。
指定した説明に一致するピンがない場合、または指定されたピンの一部がストリーム コントロールをサポートできない場合、この関数は失敗コードを返す。
注意
このメソッドは、フレーム単位の精度が要求されるキャプチャや、個別のキャプチャ動作およびプレビュー動作の制御に使用する。たとえば、キャプチャ画像のプレビューだけを行うときは、ディスクへのキャプチャ画像の書き込みをオフにすることができる。
このメソッドは、ピンの IAMStreamControl インターフェイスを呼び出す。
このメソッドは、指定されたカテゴリのピンで見つかった各フィルタにつき 1 つの通知を送る。
あらかじめ割り当てられたキャプチャ ファイルから有効なメディア データをコピーする。
構文
HRESULT CopyCaptureFile( LPOLESTR lpwstrOld, LPOLESTR lpwstrNew, int fAllowEscAbort, IAMCopyCaptureFileProgress *pCallback );
パラメータ
- lpwstrOld
- [in] コピー元ファイル名が格納された Unicode 文字列へのポインタ。
- lpwstrNew
- [in] コピー先ファイル名が格納された Unicode 文字列へのポインタ。このファイルに有効なデータがコピーされる。
- fAllowEscAbort
- [in] Esc キーを押すとコピー操作が中断されるかどうかを示す値。TRUE は中断されることを示し、FALSE はこのメソッドが Esc キー操作を無視することを示す。
- pCallback
- [in] コピー操作の進行状況 (パーセント単位の達成率) を表示するために実装する IAMCopyCaptureFileProgress インターフェイスへのオプションのポインタ。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。
注意
新しいファイルには有効なデータのみが格納されるため、コピー元ファイルより新しいファイルの方がずっと小さくなることがある。通常は、常に、あらかじめ割り当てられた同じサイズの大きいファイルにキャプチャし、このメソッドを使って、各キャプチャから保存したいデータだけを新しいファイルにコピーする。
pCallback を指定した場合は、パーセント単位の達成率に相当する 0 から 100 の間の整数を指定して IAMCopyCaptureFileProgress インターフェイスの Progress メソッドを定期的に呼び出す。
指定されたインターフェイスをフィルタ、フィルタのアップストリームおよびダウンストリームで検索する。また、オプションで、指定されたインターフェイスを特定のカテゴリの出力ピンでのみ検索する。
構文
HRESULT FindInterface( const GUID *pCategory, IBaseFilter *pf, REFIID riid, void **ppint );
パラメータ
- pCategory
- [in] 出力ピン カテゴリを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。NULL は、カテゴリに関係なく、すべての出力ピンを検索することを示す。
- pf
- [in] フィルタの IBaseFilter インターフェイスへのポインタ。
- riid
- [in] 目的のインターフェイスの参照識別子。
- ppint
- [out] 空のポインタのアドレス。インターフェイスが見つかった場合、このメソッドは ppint を初期化して、見つかったインターフェイスへのポインタのアドレスを ppint に格納できるようにする。インターフェイスを使用した後は、Release メソッドを呼び出して参照カウントをデクリメントする。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。
注意
このメソッドは、カテゴリが指定されていない限り、フィルタ、フィルタのアップストリームおよびダウンストリームでインターフェイスを検索する。カテゴリが指定されている場合、このメソッドは、そのカテゴリの出力ピンのダウンストリームのみを検索の対象とする。このメソッドを使って、レンダラ、マルチプレクサ、TV チューナー、クロスバーなどを対象としてインターフェイスを検索できる。
pCategory == &LOOK_UPSTREAM_ONLY である場合、グラフ ビルダは、pf パラメータで指定されているフィルタのアップストリームを検索の対象とするが、フィルタ自体やフィルタのダウンストリームは検索の対象としない。
pCategory == &LOOK_DOWNSTREAM_ONLY である場合、グラフ ビルダは、pf パラメータで指定されているフィルタのダウンストリームを検索の対象とするが、フィルタ自体やフィルタのアップストリームは検索の対象としない
たとえば、キャプチャ グラフは、ビデオ クロスバー (ビデオ キャプチャ フィルタのアップストリーム) とオーディオ クロスバー (ビデオ クロスバーのアップストリーム) の 2 つのクロスバーを備えていることがある。次に示すコードによって、IAMCrossbar インターフェイスを実装するビデオ クロスバー フィルタを検索できる。
IAMCrossbar *pVideoCrossbar; FindInterface(NULL, pVideoCaptureFilter, IID_IAMCrossbar, (void **)&pVideoCrossbar);さらに、次に示すコードによって、オーディオ クロスバーの IAMCrossbar フィルタを検索できる。
IBaseFilter *pBaseFilter; IAMCrossbar *pAudioCrossbar; pVideoCrossbar->QueryInterface(IID_IBaseFilter, (void **)pBaseFilter); FindInterface( &LOOK_UPSTREAM_ONLY, pBaseFilter, IID_IAMCrossbar, (void **)&pAudioCrossbar); pBaseFilter->Release();
ビルダが使用しているフィルタ グラフを取得する。
構文
HRESULT GetFiltergraph( IGraphBuilder **ppfg );
パラメータ
- ppfg
- [out] IGraphBuilder インターフェイスへのポインタのアドレス。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。
注意
このメソッドは IGraphBuilder インターフェイスの参照カウントをインクリメントする。必ず Release メソッドを呼び出して、IGraphBuilder の参照カウントをデクリメントすること。
オプションで指定されるカテゴリのソース フィルタのピンを、オプションでほかのフィルタを経由して、レンダリング フィルタに接続する。
構文
HRESULT RenderStream( const GUID *pCategory, IUnknown *pSource, IBaseFilter *pfCompressor, IBaseFilter *pfRenderer );
パラメータ
- pCategory
- [in] ソース フィルタのどの出力ピンを接続するかを指定する GUID へのポインタ。通常は、次の値が含まれる。すべてのピン カテゴリの一覧については、「AMPROPERTY_PIN_CATEGORY」を参照すること。NULL は、カテゴリに関係なく、出力ピンのみをレンダリングすることを示す。
- pSource
- [in] ソース フィルタまたは出力ピンに相当する IBaseFilter インターフェイスまたは IPin インターフェイスへのポインタ。ソース フィルタは、通常、AVI ファイル ソース フィルタやキャプチャ フィルタなどのファイル ソース フィルタである。
- pfCompressor
- [in] オプションの圧縮フィルタに相当する IBaseFilter インターフェイスへのポインタ。
- pfRenderer
- [in] レンダラに相当する IBaseFilter インターフェイスへのポインタ。ICaptureGraphBuilder::SetOutputFileName の ppf (マルチプレクサ) パラメータを使用して、この値を渡すことができる。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。キャプチャ フィルタにキャプチャ ピンはあるが、プレビュー ピンがない場合、キャプチャ ピンに対して &PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を呼び出すと、VFW_S_NOPREVIEWPIN が返される。その場合、RenderStream はスマート ティー フィルタのプレビュー ピンをレンダリングする。 詳細については、「注意」を参照すること。
注意
pCategory として NULL 以外の AMPROPERTY_PIN_CATEGORY を指定し、pSource としてキャプチャ フィルタを指定した場合、このメソッドは、TV チューナーやクロスバーなど、必要とされる追加のアップストリーム フィルタのインスタンスを生成し、それらのフィルタを接続する。次に、このメソッドは、pSource のキャプチャ ピンをレンダリングする。
pSource がピンの場合は、pCategory として NULL を指定すると、このメソッドは、そのピンのストリームをレンダリングする。
ソース フィルタに出力ピンが 1 つしかない場合は、pCategory として NULL を指定する。
パラメータとして指定された pSource フィルタ、pfCompressor フィルタおよび pfRenderer フィルタは、このメソッドが呼び出される前にグラフ内に存在している必要がある。
WDM キャプチャ フィルタを使用するキャプチャ グラフを作成する場合、このメソッドは、すべての必要なアップストリーム フィルタおよびダウンストリーム フィルタを作成する。
新しい WDM VPE (ビデオ ポート エクステンション) ビデオ キャプチャ ハードウェアを使用する一部のキャプチャ フィルタは、プレビュー用として PREVIEW ピンの代わりに VIDEO PORT ピンを備えている。これらの VIDEO PORT ピンは、ビデオ レンダラに直接接続されず、オーバーレイ ミキサーと呼ばれる特殊なフィルタに接続される。アプリケーションは、この点を考慮に入れる必要はない。&PIN_CATEGORY_PREVIEW を指定して RenderStream を呼び出せば、必要な場合には、キャプチャ グラフ ビルダがオーバーレイ ミキサーを通じて VIDEO PORT ピンを正しくレンダリングする。
&PIN_CATEGORY_CAPTURE カテゴリまたは &PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を使用し、ビデオ キャプチャ フィルタのキャプチャ ピンまたはプレビュー ピンをレンダリングする場合で、キャプチャ フィルタにキャプチャ ピンはあるが、プレビュー ピンがない場合は、スマート ティー フィルタ (Qcap.dll) が自動的に使用され、キャプチャとプレビューが同時に行われる。たとえば、&PIN_CATEGORY_CAPTURE カテゴリを指定して RenderStream を呼び出すと、フィルタのキャプチャ ピンにスマート ティー フィルタが実際に接続され、スマート ティーのキャプチャ ピンがレンダリングされる。次に、&PIN_CATEGORY_PREVIEW カテゴリを指定して RenderStream を呼び出すと、実際にスマート ティーのプレビュー ピンがレンダリングされる。&PIN_CATEGORY_PREVIEW を指定して RenderStream を呼び出した結果、キャプチャ ピンとスマート ティー フィルタが使用された場合、RenderStream は VFW_S_NOPREVIEWPIN を返すことによってそれを示す。したがって、FindInterface がプレビュー インターフェイスを見つけられない場合は、キャプチャ フィルタのキャプチャ ピンのダウンストリームでプレビュー インターフェイスが見つかることがあるため、&PIN_CATEGORY_PREVIEW カテゴリと &PIN_CATEGORY_CAPTURE カテゴリを指定して FindInterface を呼び出す必要が生じることがある。
使用するフィルタ グラフをグラフ ビルダ オブジェクトに通知する。
構文
HRESULT SetFiltergraph( IGraphBuilder *pfg );
パラメータ
- pfg
- [in] これ以降の IFilterGraph::AddFilter メソッドの呼び出しで使用するフィルタ グラフを指定する IGraphBuilder インターフェイスへのポインタ。
戻り値
インターフェイスの実装に応じた HRESULT 値を返す。
注意
このメソッドを呼び出さない場合は、グラフ ビルダが自動的にフィルタ グラフを作成する。グラフ ビルダが独自のフィルタ グラフを作成した後で、このメソッドを呼び出すと、呼び出しは失敗する。
指定されたファイル名でビットをディスクに保存するフィルタ グラフのレンダリング セクションを作成する。
構文
HRESULT SetOutputFileName( const GUID *pType, LPCOLESTR lpwstrFile, IBaseFilter **ppf, IFileSinkFilter **pSink );
パラメータ
- pType
- [in] メディア サブタイプを表す GUID へのポインタ。現在サポートされている唯一の出力フォーマットは AVI であるため、これは &MEDIASUBTYPE_Avi でなければならない。
- lpwstrFile
- [in] 出力ファイル名が格納されている Unicode 文字列へのポインタ。
- ppf
- [out] マルチプレクサ フィルタに相当する IBaseFilter インターフェイスへのポインタのアドレス。このメソッドは IBaseFilter インターフェイスの参照カウントをインクリメントため、フィルタを使用した後は、このパラメータに対して Release メソッドを使用することによって、参照カウントをデクリメントする必要がある。
- pSink
- [out] フィルタ ライタに相当する IFileSinkFilter インターフェイスへのポインタのアドレス。このメソッドは IFileSinkFilter インターフェイスの参照カウントをインクリメントするため、フィルタを使用した後は、このパラメータに対して Release メソッドを使用することによって、参照カウントをデクリメントする必要がある。
戻り値
操作の状態を示す HRESULT 値を返す。
E_FAIL 失敗。 E_INVALIDARG 無効な引数。サポートされている出力フォーマットは AVI (Audio-Video Interleaved) のみである。 E_OUTOFMEMORY メモリ不足。 E_POINTER Null ポインタ引数。 E_UNEXPECTED 予期しないエラーが発生した。 NOERROR 成功。 S_OK AVI マルチプレクサ フィルタのインスタンスが正しく作成された。
注意
このメソッドは、マルチプレクサとファイル ライタをフィルタ グラフに挿入し、IFileSinkFilter::SetFileName を呼び出して出力ファイル名を設定する。
このメソッドから返される ppf パラメータを RenderStream の呼び出しで pfRenderer パラメータとして使うことができる。
このメソッドの pSink パラメータを SetFileName の呼び出しで使って、ICaptureGraphBuilder::SetOutputFileName によって設定されたファイル名を変更できる。