Microsoft DirectX 8.0 |
このインターフェイスはすべての入力ピン、出力ピンによって公開される。
フィルタ グラフ マネージャはこのインターフェイスを使ってピンと接続し、フラッシュ処理を行う。アプリケーションはこのインターフェイスを使ってピンの情報を問い合わせることができる。アプリケーションは IPin メソッドを呼び出して、Connect や Disconnect や BeginFlush や EndFlush のようなピンの状態の変更を起こってはならない。ピンを接続するには、アプリケーションは IGraphBuilder 内のメソッドを使用しなければならない。
フィルタ 開発者 : CBasePin と CBaseInputPin と CBaseOutputPin クラスはこのインターフェイスを実装する。他の基底クラスはこれら 3 つのクラスから派生する。
Vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを返す。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IPin メソッド 説明 Connect ピンを他のピンと接続する。 ReceiveConnection 他のピンからの接続を許可する。 Disconnect 現在のピン接続を解除する。 ConnectedTo このピンに接続しているピンを取得する。 ConnectionMediaType 現在のピン接続のメディア タイプを取得する。 QueryPinInfo 名前、所有者フィルタ、向きなどのピンについての情報を取得する。 QueryId ピン識別子を取得する。 QueryAccept 指定したメディアタイプをピンが許容するかどうかを確認する。 EnumMediaTypes ピンの優先メディアタイプを列挙する。 QueryInternalConnections このピンに (フィルタ内で) 内部的に接続しているピンを取得する。 EndOfStream 追加データはもうないことをピンに通知する。 BeginFlush フラッシュ処理を開始する。 EndFlush フラッシュ処理を終了する。 NewSegment この呼び出しの後に受け取ったメディア サンプルがセグメント グループであることをピンに通知する。 QueryDirection ピンの向き (入力ピンか出力ピンか) を取得する。
フラッシュ処理を開始する。
構文
HRESULT BeginFlush(void);
戻り値
成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。
注意
フラッシュ処理中に、フィルタはそれが処理したどのデータをも廃棄する。フラッシュが完了するまで新しいデータは拒絶される。アップストリーム ピンが IPin::EndFlush を呼び出すと、フラッシュは完了する。フラッシュによってイベントが通常のデータフローを変更するときのフィルタ グラフのレスポンスが改善される。たとえば、シーク中にフラッシュは行われる。
BeginFlush が呼び出されると、フィルタ グラフは以下のステップを行う :
- IPin::BeginFlush 呼び出しをダウンストリームに渡す。
- IMemInputPin::Receive のようなすべてのデータ ストリーミング メソッドを失敗させる内部フラグを設定する。
- すべてのブロックが Receive メソッドへの呼び出しを返す。
BeginFlush 通知が レンダラ フィルタに届くと、レンダラは保持しているすべてのサンプルを解放する。
BeginFlush が呼び出された後、IPin::EndFlush メソッドが呼び出されるまで、ピンはアップストリームからのすべてのサンプルを受け付けずに S_FALSE を返す。
参照
フィルタ開発者が使用するデータ フロー
ピンを他のピンと接続する。
構文
HRESULT Connect( IPin *pReceivePin, const AM_MEDIA_TYPE *pmt );
パラメータ
- pReceivePin
- [in] ピンの IPin インターフェイスを受け取るポインタ。
- pmt
- [in] 接続のメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。NULL が可能。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 VFW_E_ALREADY_CONNECTED ピンは既に接続されている。 VFW_E_NO_ACCEPTABLE_TYPES 許可されたメディア タイプを見つけることができなかった。 VFW_E_NOT_STOPPED フィルタがアクティブで、ピンが動的再接続をサポートしていない。 VFW_E_TYPE_NOT_ACCEPTED 指定したメディア タイプは許可されない。
注意
pmt パラメータは NULL が可能。メジャー タイプやサブタイプやフォーマットに GUID_NULL の値を入れて部分的メディアタイプを指定することも可能。
このメソッドは接続が可能なことを検証する。ピンが接続を拒否すれば、メソッドは失敗する。受信ピンで IPin::ReceiveConnection を呼び出すことで、接続ピンはメディア タイプを提案する。
もしあれば、このピンに接続しているピンを取得する。
構文
HRESULT ConnectedTo( IPin **ppPin );
パラメータ
- ppPin
- [out] 他のピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。NULL は不可。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_POINTER NULL ポインタ引数。 VFW_E_NOT_CONNECTED ピンが接続されていない。
注意
メソッドが成功すれば、それを返す IPin インターフェイスは参照カウントが残る。使用後、解放に注意。
現在のピン接続のメディア タイプを取得する。
構文
HRESULT ConnectionMediaType( AM_MEDIA_TYPE *pmt );
パラメータ
- pmt
- [out] メディア タイプを受け取る AM_MEDIA_TYPE 構造体へのポインタ。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_POINTER NULL ポインタ引数。 VFW_E_NOT_CONNECTED ピンが接続されていない。
注意
ピンが接続されると、このメソッドは pmt にが指定する AM_MEDIA_TYPE 構造体にメディア タイプをコピーする。呼び出し元はメディア タイプのフォーマット ブロックを解放しなければならない。Microsoft® Win32® CoTaskMemFree 関数か、FreeMediaType ヘルパー関数が使用できます。
ピンが接続されないと、このメソッドは pmt が指定するメディア タイプをクリアし、エラー コードを返す。
現在のピン接続を解除する。
構文
HRESULT Disconnect(void);
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_FALSE ピンが接続されていなかった。 S_OK 成功。 VFW_E_NOT_STOPPED フィルタがアクティブ。
注意
フィルタがポーズか実行中なら、このメソッドは失敗する。ピンが IPinConnection インターフェイスをサポートするなら、フィルタがポーズか実行中のとき、IPinConnection::DynamicDisconnect を呼び出してピンの接続を解除すること。
ピンはこのメソッドを使って接続解除をしてはならない。
フラッシュ処理を終了する。
構文
HRESULT EndFlush(void);
戻り値
成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。
注意
このメソッドが呼び出されるとき、フィルタは以下の処理が行われる :
- キューにあるすべてのサンプルの廃棄を待つ。
- バッファにあるすべてのデータを解放する。
- 残っている EC_COMPLETE 通知をクリアする。
- EndFlush ダウンストリームを呼び出す。
メソッドが返ると、ピンは新しいサンプルを許可する。
参照
フィルタ開発者が使用するデータ フロー
新しい実行コマンドがフィルタに発行されるまでは、追加データはもうないことをピンに通知する。
構文
HRESULT EndOfStream(void);
戻り値
以下の HRESULT 値の 1 つを返す。
S_OK 成功。 E_UNEXPECTED ピンはこのメソッドをサポートしていない。
注意
このメソッドは入力ピンでのみ呼び出しすること。出力ピンは E_UNEXPECTED を返す。
このメソッドはエンドオブストリーム (end-of-stream) 通知をピンに送る。ピンはその通知をダウンストリームに送る。IMemInputPin::Receive を呼び出してエンドオブストリーム通知を継続して処理しなければならない。ピンが出力すべきメディア サンプルをキューに入れるなら、エンドオブストリーム通知も同様にキューに入れるべきである。IPin::BeginFlush メソッドはキュー内のすべてのエンドオブストリーム通知をフラッシュする。
ピンの優先メディアタイプを列挙する。
構文
HRESULT EnumMediaTypes( IEnumMediaTypes **ppEnum );
パラメータ
- ppEnum
- [out] IEnumMediaTypes インターフェイスへのポインタを受け取る変数のアドレス。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。 E_POINTER NULL ポインタ引数。
注意
IEnumMediaTypes インターフェイスは標準 COM 列挙子のように動作する。詳細については、「Enumerating Objects in a Filter Graph」を参照すること。メソッドが成功すると、IEnumMediaTypes インターフェイスに参照カウントが残る。使用後、解放に注意。
この呼び出しの後に受け取ったメディア サンプルが、共通の開始タイムと終了タイムとレートを持つセグメント グループであることをピンに通知する。
構文
HRESULT NewSegment( REFERENCE_TIME tStart, REFERENCE_TIME tStop, double dRate );
パラメータ
- tStart
- セグメントの開始タイム、オリジナル ソースの相対値、100ナノ秒単位。
- tStop
- セグメントの終了タイム、オリジナル ソースの相対値、100ナノ秒単位
- dRate
- セグメントが処理されるレート、オリジナル レートのパーセンテージ。
戻り値
成功なら S_OK を返す、あるいはエラーの原因を示す HRESULT 値を返す。
注意
新しいストリームを開始するたびとシーク操作が終わるたびに、ソース フィルタ (あるいはパーサーフィルタ) はこのメソッドを呼び出す。以前のデータバッチを出力した後で、新しいデータで IMemInputPin::Receive を呼び出す前に、それはダウンストリーム フィルタの入力ピンのメソッドを呼び出す。ダウンストリーム フィルタは NewSegment 呼び出しをダウンストリームに継承する。
フィルタはセグメント情報を使ってサンプルを処理する。たとえば、いくつかのフォーマットでは次のフレームなしでデルタ フレームを再構築することはできない。それゆえ、終了タイムがデルタ フレームにあると、ソース フィルタは追加フレームを送らなければならない。デコーダ フィルタはセグメント情報を基に最終フレームを決定する。たとえば、オーディオ レンダラはサンプリング レートとセグメント レートを使って、オーディオ データを正しくレンダリングする。
指定したメディアタイプをピンが許容するかどうかを確認する。
構文
HRESULT QueryAccept( const AM_MEDIA_TYPE *pmt );
パラメータ
- pmt
- [in] メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
戻り値
メディアタイプが許容されるなら S_TRUE を返す。そうでなければ、S_FALSE を返す。
注意
S_OK が返るなら、フィルタ実行中にピンが指定したフォーマットに変更できることが保証される。フィルタ実行中にフォーマットを変更する必要があり、ピンが IPinConnection をサポートするなら、IPinConnection::DynamicQueryAccept メソッドを呼び出すこと。
ピンの向き (入力ピンか出力ピンか) を取得する。
構文
HRESULT QueryDirection( PIN_DIRECTION *pPinDir );
パラメータ
- pPinDir
- [out] PIN_DIRECTION 列挙型のメンバを受け取る変数へのポインタ。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_POINTER NULL ポインタ引数。
ピン識別子を取得する
構文
HRESULT QueryId( LPWSTR *Id );
パラメータ
- Id
- [out] ピン識別子が入る文字列を受け取る変数のアドレス。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。 E_POINTER NULL ポインタ引数。
注意
このメソッドはグラフ永続性をサポートする。このメソッドを使用してピンの状態を保存し、IBaseFilter::FindPin メソッドを使ってその状態をリストアすること。ピン識別文字列はフィルタ実装によって定義されている。その識別子はフィルタ内でユニークでなければならない。
注 ピン ID は必ずしもQueryPinInfo メソッドが返す ピン名 と同じではない。
フィルタは Microsoft® Win32® CoTaskMemAlloc 関数を使用して返った文字列を割り当てる。呼び出し元は CoTaskMemFree を使ってそれを解放しなければならない。
このピンに (フィルタ内で) 内部的に接続しているピンを取得する。
構文
HRESULT QueryInternalConnections( IPin **apPin, ULONG *nPin );
パラメータ
- apPin
- [out] IPin ポインタの配列のアドレス。
- nPin
- [in, out] 入力時は配列のサイズを指定する。メソッドが返ると、この値は配列内に返るポインタの数がセットされる。
戻り値
以下の HRESULT 値の 1 つを返す。
S_FALSE 不適切な配列サイズ。 S_OK 成功。 E_FAIL 失敗。 E_NOTIMPL 実装されていない。
注意
いくつかのフィルタでは、入力ピンは固有の出力ピンに対応している。各ピンについて、このメソッドは対応するピンへのポインタの配列を書き込む。各入力ピンが各出力ピンにデータを提供するなら、ピンは E_NOTIMPL を返す。
メソッドが成功し、ゼロ以上の *nPin 値を返すと、その配列には IPin インターフェイスへのポインタが入る。使用後、各インターフェイス ポインタの解放に注意すること。
ピンについての情報を取得する。
構文
HRESULT QueryPinInfo( PIN_INFO *pInfo );
パラメータ
- pInfo
- [out] ピン情報を受け取る PIN_INFO 構造体へのポインタ。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_POINTER NULL ポインタ引数。
注意
メソッドが返るとき、PIN_INFO 構造体の pFilter メンバが NULL 以外なら、参照カウントが残る。使用後インターフェイスの解放に注意すること。
他のピンからの接続を許可する。
構文
HRESULT ReceiveConnection( IPin *pConnector, AM_MEDIA_TYPE *pmt );
パラメータ
- pConnector
- [in] 接続しているピンの IPin インターフェイスへのポインタ。
- pmt
- [in] 接続のメディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
戻り値
HRESULT 値を返す。以下のいずれかの値。
S_OK 成功。 E_POINTER NULL ポインタ引数。 VFW_E_ALREADY_CONNECTED ピンは既に接続している。 VFW_E_NOT_STOPPED フィルタがアクティブな間は接続できない。 VFW_E_TYPE_NOT_ACCEPTED 指定したメディア タイプが許可されない。
注意
接続を初期化するピンはこのメソッドを受信ピンで呼び出す。受信ピンがエラー コードを返すなら、接続は失敗する。