ICaptureGraphBuilder2

ICaptureGraphBuilder2 インターフェースは、キャプチャグラフやその他のカスタムフィルタグラフを構築します。

SetFiltergraph メソッドは、キャプチャグラフビルダーが使用するフィルタグラフを指定します。

HRESULT 値を返します。指定可能な値には次のものがあります。

このメソッドを呼び出さない場合、キャプチャグラフビルダーは必要になったときに自動的にフィルタグラフを作成します。キャプチャグラフビルダーがすでにフィルタグラフを保持している場合、このメソッドは E_UNEXPECTED を返します。

GetFiltergraph メソッドは、キャプチャグラフビルダーが使用しているフィルタグラフを取得します。

次のいずれかの HRESULT 値を返します。

初期状態では、キャプチャグラフビルダーはフィルタグラフへのポインターを保持していません。このメソッドは、次のいずれかのメソッドが呼び出されるまで E_UNEXPECTED を返します。

• ICaptureGraphBuilder2::RenderStream
• ICaptureGraphBuilder2::SetFiltergraph
• ICaptureGraphBuilder2::SetOutputFileName

SetOutputFileName メソッドは、フィルタグラフのファイル書き込み部分を作成します。

HRESULT 値を返します。指定可能な値には次のものがあります。

このメソッドは、pType パラメーターの値に基づいてマルチプレクサフィルタを作成します。AVI の場合は AVI Mux Filter を作成します。ASF の場合は WM ASF Writer を作成します。それ以外の値の場合は、CLSID で識別されるフィルタを作成します。マルチプレクサをフィルタグラフに追加し、その IBaseFilter インターフェースへのポインターを ppf パラメーターで返します。

マルチプレクサが IFileSinkFilter インターフェースをサポートしている場合、このメソッドは IFileSinkFilter::SetFileName を呼び出し、lpwstrFile パラメーターで指定された値を使用して出力ファイル名を設定します。マルチプレクサが IFileSinkFilter インターフェースをサポートしていない場合、このメソッドは File Writer Filter をフィルタグラフに追加し、マルチプレクサをファイルライターに接続し、ファイルライターの IFileSinkFilter インターフェースを使用して SetFileName を呼び出します。pSink パラメーターが NULL でない場合、そこに IFileSinkFilter インターフェースへのポインターが格納されます。

ppf パラメーターで返されるマルチプレクサフィルタへのポインターは、ICaptureGraphBuilder2::RenderStream メソッドの pSink パラメーターとして使用できます。

カスタムのマルチプレクサフィルタの場合、入力ピンが接続される前に出力ピンでの接続をフィルタがサポートしていないと、このメソッドは失敗します。たとえば、SDK に含まれる WavDest Filter Sample にはこの制限があります。

メソッドが成功した場合、ppf パラメーターで返される IBaseFilter インターフェースには未解放の参照カウントが残ります。メソッドが成功し、かつ pSink が NULL でない場合、IFileSinkFilter インターフェースにも未解放の参照カウントが残ります。使用が終わったら必ず両方のインターフェースを解放してください。

FindInterface メソッドは、指定されたフィルタを起点として、指定されたインターフェースをグラフ内で検索します。

HRESULT 値を返します。指定可能な値には次のものがあります。

キャプチャグラフでは、さまざまなフィルタやピンが、圧縮パラメーター (IAMVideoCompression) やストリーム形式 (IAMStreamConfig) などのプロパティを設定するためのインターフェースを公開している場合があります。キャプチャデバイスによっては、アナログ信号を経路制御する IAMCrossbar や、TV チューナーデバイスを制御する IAMTVTuner など、他にも役立つインターフェースが含まれることがあります。このメソッドを使用すると、グラフを走査する特別なコードを記述することなくインターフェースを見つけられます。

• そのフィルタ
• そのフィルタのピン
• ピンを含む、下流のすべてのフィルタ
• ピンを含む、上流のすべてのフィルタ

• pCategory が &LOOK_UPSTREAM_ONLY の場合、検索はフィルタの入力ピンから始まり、上流方向へ続きます。そのフィルタ自体やフィルタより下流のものは対象になりません。pType パラメーターは無視されます。
• pCategory が &LOOK_DOWNSTREAM_ONLY の場合、検索はフィルタの出力ピンから始まり、下流方向へ続きます。そのフィルタ自体やフィルタより上流のものは対象になりません。pType パラメーターは無視されます。
• pCategory がピンカテゴリを指定している場合、検索の下流部分は、ピンカテゴリと pType パラメーターで指定されたメディアタイプの両方に一致するフィルタの出力ピンに限定されます。この場合、メソッドはそのフィルタおよびフィルタより上流のすべても検索します。

ピンカテゴリは、キャプチャフィルタのピンインターフェースを見つけるのに役立ちます。たとえば、キャプチャフィルタにはキャプチャ用とプレビュー用の別々のピンがある場合があります。ピンカテゴリを指定する場合は、メソッドが正しいフィルタとピンを選択するように、メディアタイプも指定してください。

一部のビデオキャプチャフィルタには、プレビューピンの代わりにビデオポートピン (PIN_CATEGORY_VIDEOPORT) があります。PIN_CATEGORY_PREVIEW と MEDIATYPE_Video を指定すると、メソッドはビデオポートピンをプレビューピンとして扱います。アプリケーションでこの可能性を判定する必要はありません。

Supporting Filters。キャプチャデバイスが Windows Driver Model (WDM) ドライバーを使用している場合、グラフには WDM Video Capture フィルタの上流に、TV Tuner フィルタや Analog Video Crossbar フィルタなどの特定のフィルタが必要になる場合があります。pCategory パラメーターが NULL 以外の場合、このメソッドは必要な WDM フィルタをグラフに自動的に挿入します。そのために、キャプチャフィルタの入力ピンに問い合わせてサポートするミディアムを判定し、一致するフィルタに接続します。pCategory パラメーターが NULL の場合、メソッドは上流のフィルタを追加しません。

RenderStream メソッドは、ソースフィルタの出力ピンを、必要に応じて中間フィルタを経由してシンクフィルタに接続します。

HRESULT 値を返します。返される可能性のある値には次のものがあります。

このメソッドは、2 つ以上のフィルタをチェーン状に接続することでストリームをレンダリングします。

• pSource パラメーターは、チェーンの起点となるフィルタまたは出力ピンを指定します。
• pIntermediate パラメーターは、通常は圧縮フィルタである中間フィルタを指定します。このパラメーターは NULL でもかまいません。
• pSink パラメーターは、チェーンの終端のフィルタを指定します。通常、このフィルタはプレビュー用のレンダラーか、ファイルキャプチャ用のマルチプレクサ (mux) のいずれかです。

pSink パラメーターが NULL の場合、メソッドは既定のレンダラーを使用しようとします。ビデオの場合は Video Renderer を、オーディオの場合は DirectSound Renderer を使用します。

pSource がフィルタの場合、メソッドはそのフィルタ上の出力ピンを検索します。その場合は、pCategory パラメーターと pType パラメーターを使用して検索を絞り込みます。たとえば、フィルタにプレビュー用とキャプチャ用の別々のピンがある場合は、PIN_CATEGORY_CAPTURE または PIN_CATEGORY_PREVIEW のいずれかを指定できます。pSource が出力ピンの場合は、pCategory と pType を NULL に設定します。

いずれの場合も、メソッドは未接続のピンを検索します。指定された条件を満たすピンが複数ある場合、メソッドは最初に見つかったピンを使用します。

DV キャプチャの場合、メディアタイプが MEDIATYPE_Interleaved で pSink パラメーターが NULL のときは、メソッドはインターリーブされたストリームをオーディオストリームとビデオストリームに分割し、その両方のストリームをレンダリングすることに注意してください。

RenderStream メソッドは、キャプチャグラフに必要な詳細の多くを処理します。

Smart Tee。一部のキャプチャフィルタにはキャプチャピンはあってもプレビューピンがありません。プレビューを行うには、キャプチャピンを Smart Tee Filter に接続する必要があります。このフィルタはデータをキャプチャストリームとプレビューストリームの 2 つのストリームに分割します。PIN_CATEGORY_PREVIEW または PIN_CATEGORY_CAPTURE を指定すると、必要に応じてメソッドが Smart Tee フィルタを挿入します。その後、Smart Tee フィルタ上で指定されたストリームをレンダリングします。プレビューストリームをレンダリングし、メソッドが Smart Tee フィルタを使用した場合は、VFW_S_NOPREVIEWPIN を返します。

Closed Captioning。このメソッドを使用して、クローズドキャプションをキャプチャまたはプレビューできます。キャプチャフィルタには、垂直帰線期間 (VBI) データを提供するものと、クローズドキャプションデータを提供するものがあります。どちらの場合にも対応するには、PIN_CATEGORY_VBI を使用する場合と PIN_CATEGORY_CC を使用する場合の 2 回メソッドを呼び出します。メソッドは、VBI データをクローズドキャプションに変換するのに必要なフィルタを挿入します。データをプレビューするには、pSink パラメーターを NULL に設定します。データをファイルにキャプチャするには、マルチプレクサフィルタの IBaseFilter インターフェースポインターを使用します。同じグラフでデータのキャプチャとプレビューの両方を行うことができます。NULL を使用して 1 回、マルチプレクサを使用してもう 1 回メソッドを呼び出します。pIntermediate パラメーターは NULL に設定します。

Video Port Pins。ビデオポート拡張 (VPE) ビデオキャプチャハードウェアで動作するフィルタには、プレビューピンの代わりにビデオポートピン (PIN_CATEGORY_VIDEOPORT) がある場合があります。プレビューまたはキャプチャを機能させるには、ビデオポートピンを Overlay Mixer Filter に接続する必要があります。メソッドはこの詳細を処理します。PIN_CATEGORY_VIDEOPORT を指定する必要はありません。PIN_CATEGORY_PREVIEW または PIN_CATEGORY_CAPTURE を指定すれば、メソッドがピンを正しく接続します。同様に、一部のフィルタはビデオポートピン (PIN_CATEGORY_VIDEOPORT_VBI) を使用して VBI データを提供します。PIN_CATEGORY_VIDEOPORT の場合と同様に、メソッドはこの詳細を処理します。PIN_CATEGORY_VIDEOPORT_VBI を指定する必要はありません。

Supporting Filters。キャプチャデバイスが Windows Driver Model (WDM) ドライバーを使用している場合、グラフには WDM Video Capture Filter の上流に、TV Tuner Filter や Analog Video Crossbar Filter などの特定のフィルタが必要になる場合があります。このメソッドがストリームのレンダリングに成功すると、グラフに必要な WDM フィルタも挿入されます。メソッドは、キャプチャフィルタの入力ピンに問い合わせてサポートするミディアムを判定し、一致するフィルタに接続します。

サンプルコード

// Video: 
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Video, 
    pCaptureFilter, NULL, NULL); 
// Audio:
pBuilder->RenderStream(&PIN_CATEGORY_PREVIEW, &MEDIATYPE_Audio, 
    pCaptureFilter, NULL, NULL); 

pBuilder->SetOutputFileName(&MEDIASUBTYPE_Avi, L"C:\\Example.avi", 
    &ppf, &pSink);
pBuilder->RenderStream(&PIN_CATEGORY_CAPTURE, &MEDIATYPE_Video,
    pCaptureFilter, NULL, ppf);

ファイルソース

ファイルソースには出力ピンが 1 つあるため、pCategory と pType を NULL に設定します。メソッドを 2 回呼び出します。1 回はビデオストリームをレンダリングするため、もう 1 回はオーディオストリームをレンダリングするためです。最初の呼び出しでは、ソースフィルタをパーサーフィルタに接続し、パーサーフィルタの出力ピンの 1 つをレンダリングします。2 回目の呼び出しでは、パーサーの残りの出力ピンをレンダリングします。一方のストリームだけを圧縮する場合は、必ず最初の呼び出しで圧縮フィルタを指定してください。メソッドは圧縮の種類に基づいて正しいストリームを自動的に選択します。

pBuilder->RenderStream(NULL, NULL, pSrc, pCompressor, pMux);
pBuilder->RenderStream(NULL, NULL, pSrc, NULL, pMux);

ControlStream メソッドは、キャプチャされたデータの 1 つ以上のストリームに対して開始時刻と停止時刻を設定します。

HRESULT 値を返します。指定可能な値には次のものがあります。

このメソッドは、メソッド呼び出しで指定した検索条件を使用して、キャプチャフィルタの出力ピンを特定します。次に、それらのピンに対して IAMStreamControl のメソッドを呼び出します。このメソッドにより、アプリケーションはグラフ内のフィルタやピンを列挙することなくストリームを制御できます。

フレーム単位で正確なキャプチャを行う場合や、キャプチャとプレビューを個別に制御する場合にこのメソッドを使用します。たとえば、ディスクへのキャプチャを停止しつつ、ビデオプレビューは実行したままにできます。

最初の 3 つのパラメーターで、制御対象のピンを指定します。キャプチャグラフには複数のキャプチャフィルタが存在する場合があります。たとえば、ビデオ、オーディオ、クローズドキャプションデータ用のフィルタを持つことがあります。また、キャプチャフィルタは複数の出力ピンを持つことがあります。一部のキャプチャフィルタには、プレビュー用とキャプチャ用の別々のピン、またはビデオのみのデータ用とオーディオビデオインターリーブデータ用の別々のピンがあります。たとえば、ビデオプレビューを制御するには、pCategory に PIN_CATEGORY_PREVIEW、pType に MEDIATYPE_Video を指定します。

このメソッドは一致するピンを見つけると、IAMStreamControl をサポートする別のフィルタ (通常はマルチプレクサ) を下流方向に検索します。見つかった場合は、そのフィルタにも開始時刻と停止時刻を設定します。これにより、キャプチャフィルタ用と下流フィルタ用の 2 組の停止通知が生成されます。wStopCookie パラメーターを使用するのは、下流フィルタからの停止通知だけです。このイベントを待機することで、下流フィルタが最後のサンプルを確実に受け取ることが保証されます。

下流フィルタが IAMStreamControl をサポートしていない場合、メソッドは S_FALSE を返します。その場合、最後のサンプルがレンダリングされる前に停止通知を受け取ることがあります。

MAXLONGLONG は、指定可能な最大の REFERENCE_TIME 値です。DirectShow の基底クラスライブラリでは、定数 MAX_TIME としても定義されています。

AllocCapFile メソッドは、キャプチャファイルを指定したサイズに事前割り当てします。最良の結果を得るには、常にキャプチャデータのサイズより大きく、断片化されていない事前割り当て済みのキャプチャファイルにキャプチャしてください。

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

ファイルが読み取り専用の場合、このメソッドは失敗します。

可能な限り多くの領域を割り当てることが最適です。理想的には必要以上に割り当てます。ただし、その結果、比較的少ないデータしか含まないきわめて大きなファイルになることがあります。たとえば、1 ギガバイト (GB) のキャプチャファイルに、キャプチャされたビデオが数メガバイトしか含まれていないこともあります。データを新しいファイルにコピーするには、ICaptureGraphBuilder2::CopyCaptureFile メソッドを使用します。このメソッドはデータのみをコピーし、元のファイルの空の部分は無視します。

このメソッドを使用してファイルを事前割り当てする場合は、ファイルライターフィルタに対して値 0 を指定して IFileSinkFilter2::SetMode を呼び出します。フィルタが AM_FILE_OVERWRITE に設定されていると、事前割り当てされたファイルが削除されます。一部のファイルライターフィルタはモード 0 をサポートしていないことに注意してください。

CopyCaptureFile メソッドは、キャプチャファイルから有効なメディアデータをコピーします。

HRESULT 値を返します。指定可能な値には次のものがあります。

通常、最初に大きな事前割り当て済みのファイルにキャプチャします。このメソッドは有効なデータだけを新しいファイルにコピーします。その結果、新しいファイルは元のファイルよりもはるかに小さくなります。

コピー元ファイルとコピー先ファイルは AVI ファイルである必要があります。その他のファイル形式はサポートされていません。

コピー操作の進捗を表示するには、IAMCopyCaptureFileProgress インターフェースを実装し、そのインターフェースへのポインターを pCallback パラメーターで渡します。pCallback が NULL 以外の場合、このメソッドは完了率を示す 0 から 100 までの整数を引数として、IAMCopyCaptureFileProgress::Progress メソッドを定期的に呼び出します。

FindPin メソッドは、フィルタ上の特定のピンを取得するか、指定されたピンが指定された条件に一致するかどうかを判定します。

一致するピンが見つかった場合は S_OK を返し、それ以外の場合は E_FAIL を返します。

pSource がフィルタへのポインターの場合、メソッドはそのフィルタ上で検索条件に一致する n 番目のピンを検索します。ここで n は num パラメーターで指定されます。メソッドが一致するピンを見つけると、そのピンへのポインターを ppPin パラメーターで返します。

pSource がピンへのポインターの場合、メソッドはそのピンを検索条件に照らして検証します。ピンが条件に一致する場合、メソッドは S_OK を返し、そのピンの IPin インターフェースへのポインターを ppPin パラメーターで返します。それ以外の場合は E_FAIL を返します。

いずれの場合も、メソッドが成功すると、ppPin パラメーターで返される IPin インターフェースには未解放の参照カウントが残ります。使用が終わったら必ずインターフェースを解放してください。

通常、アプリケーションでこのメソッドを使用する必要はありません。これは、ICaptureGraphBuilder2::RenderStream メソッドではフィルタグラフを構築できないような、非常に複雑なタスクのために提供されています。このメソッドを使用してキャプチャフィルタから目的のピンを取得し、その後グラフの残りの部分を手動で構築します。