Microsoft DirectX 8.0 |
動的再接続とフォーマット変更をサポートする出力ピンを実装する。
宣言 : Amfilter.h
このクラスは CBaseOutputPin ピンから派生し、IPinFlowControl インターフェイスを実装する。それは 動的グラフ作成 に重要ないくつかの操作をサポートする :
このピンは 3 つの状態が可能である: ブロックされている (Blocked)、ブロック解除されている (not Blocked)、待機状態 (Pending)。待機 状態では、ピンがブロックされた状態になる前に、他のスレッド操作が完了するのを待っている。ピンがブロックされている間、フィルタはデータをピンから出力できない、あるいはピンの接続を変更できない。
所有するフィルタは、複数のスレッド間の調整を行うにために、あるルールに従わなければならない。フィルタ グラフのスレッドの詳細については、「スレッドとクリティカル セクション」を参照すること。最初に、ストリーミング スレッドは、次のメソッドのいずれかを呼び出す前に、必ずStartUsingOutputPin メソッドを呼び出さなければならない。
その後で、StopUsingOutputPin メソッドを呼び出さなければならない。
次に、アプリケーション スレッドは前述の一覧にあるいずれのメソッドも呼び出してはならない。また、ストリーミング スレッドは、ピンをブロックまたはブロック解除するクラス メソッドを呼び出してはならない。このようなメソッドには、Block、SynchronousBlockOutputPin、AsynchronousBlockOutputPin、および UnblockOutputPin がある。
これらのルールはストリーミング スレッドがピンを使用中に、アプリケーション スレッドがそのピンをブロックできなくするため (または逆も) である。ストリーミング スレッドが StartUsingOutputPin を呼び出した後、そのスレッドが StopUsingOutputPin を呼び出すまで、ピンはブロックされない。逆にピンがブロックされると、StartUsingOutputPin はピンが非ブロックになるまで待つ。
StopUsingOutputPin の呼び出しを忘れないために、CAutoUsingOutputPin クラスを使うことができる。それは 終了する前に自動的に StopUsingOutputPin を呼び出す。
(IBaseFilter::JoinFilterGraph メソッド内で) 自身のフィルタがフィルタ グラフに参加あるいは退出するとき、ピンの SetConfigInfo メソッドを呼び出さなければならない。
Protected メンバ変数 | |
---|---|
m_BlockStateLock | ブロック状態を保護するクリティカル セクション。 |
m_hUnblockOutputPinEvent | ピンがブロックされていないときに通知済のイベント。 |
m_hNotifyCallerPinBlockedEvent | ピンのブロックに成功したとき、あるいはユーザーが待機ブロックをキャンセルできないとき、通知済のイベント。 |
m_BlockState | ブロック状態。 |
m_dwBlockCallerThreadID | このピンで最後に IPinFlowControl::Block メソッドを呼び出したスレッドの ID。 |
m_dwNumOutstandingOutputPinUsers | このピンを使用しているストリーミング スレッドの数。 |
m_hStopEvent | フィルタが停止した、あるいはピンがデータをフラッシュしたとき、通知済のイベント。 |
m_pGraphConfig | 動的再接続を実行する IGraphConfig インターフェイスへのポインタ。 |
m_bPinUsesReadOnlyAllocator | ピンのアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。 |
Protected メソッド | |
SynchronousBlockOutputPin | ピンをブロックする。ピンがブロックされるまで返らない。 |
AsynchronousBlockOutputPin | ピンをブロックする。ピンがブロックされるまでに返ることがある。 |
UnblockOutputPin | ピンをブロック解除する。 |
BlockOutputPin | ピンをブロックする。 |
WaitEvent | 指定したイベントが通知済になるまで待つ。 |
Public メソッド | |
CDynamicOutputPin | コンストラクタ メソッド。 |
~CDynamicOutputPin | デストラクタ メソッド。 |
SetConfigInfo | IGraphConfig ポインタと停止イベントを指定する。 |
DeliverBeginFlush | 接続した入力ピンにフラッシュ処理を要求する。 |
DeliverEndFlush | 接続した入力ピンにフラッシュ処理の終了を要求する。 |
Inactive | ピンにフィルタが停止していることを通知する。 |
Active | ピンにフィルタが今アクティブであることを通知する。 |
CompleteConnect | 入力ピンへの接続を完了する。 仮想。 |
StartUsingOutputPin | ストリーミング操作でピンのアクセスを獲得する。 仮想。 |
StopUsingOutputPin | ストリーミング操作の後ピンへのアクセスを解放する。 仮想。 |
StreamingThreadUsingOutputPin | スレッドがピンでストリーミング操作を行っているかどうかを確認する。仮想。 |
ChangeOutputFormat | 接続しているメディア タイプを動的に変更し、新しいセグメント情報を出力する。 |
ChangeMediaType | 接続しているメディア タイプを動的に変更する。 |
DynamicReconnect | 新しいメディア タイプと動的再接続を行う。 |
IPin メソッド | |
Disconnect | 現在のピン接続を解除する。 |
IPinFlowControl メソッド | |
Block | ピンからのデータのフローをブロック、あるいはブロック解除する。 |
ブロック状態を保護するクリティカル セクション。
構文
CCritSec m_BlockStateLock;
注意
次のメンバ関数を使う前にこのクリティカルセッションを保持すること :
ピンがブロックされていないときに通知済のイベント。
構文
HANDLE m_hUnblockOutputPinEvent;
ピンのブロックが成功したとき、あるいはユーザーがブロック待機をキャンセルしたときに通知済のイベント。
構文
HANDLE m_hNotifyCallerPinBlockedEvent;
注意
この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。
ブロック状態。
構文
BLOCK_STATE m_BlockState;
注意
次の状態を確認する。
- NOT_BLOCKED
- PENDING
- BLOCKED
この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。
このピンで最後に IPinFlowControl::Block メソッドを呼び出したスレッドの識別子。このメンバ変数は、ピンがブロックされているときだけ有効である。
構文
DWORD m_dwBlockCallerThreadID;
注意
この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。
このピンを使用しているストリーミング スレッドの数。
構文
DWORD m_dwNumOutstandingOutputPinUsers;
注意
StartUsingOutputPin メソッドはこの変数をインクリメントし、StopUsingOutputPin メソッドはデクリメントする。この値がゼロより大きいとき、いくつかのスレッドがこのピンを使ってデータをストリームしている、あるいは接続タイプを変更している。この間はピンをブロック状態にできない。
この変数にアクセスする前に、m_BlockStateLock クリティカル セクションを保持すること。
参照
StreamingThreadUsingOutputPin
フィルタが停止した、あるいはピンがデータをフラッシュしたとき、通知済のイベント。
構文
HANDLE m_hStopEvent;
動的再接続を実行する IGraphConfig インターフェイスへのポインタ。
構文
IGraphConfig* m_pGraphConfig;
ピンのアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。 この値が TRUE ならサンプルは読み込み専用。デフォルト値は FALSE。
構文
BOOL m_bPinUsesReadOnlyAllocator;
フィルタがアクティブになったことをピンに通知する。
構文
HRESULT Active(void);
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_OK 成功。 E_FAIL 失敗。SetConfigInfo が呼び出されなかった。
注意
このメソッドは、CBaseOutputPin::Active メソッドをオーバーライドする。また、m_hStopEvent イベントをリセットする。所有するフィルタが SetConfigInfo を呼び出していない場合、このメソッドは E_FAIL を返す。
ピンをブロックする。ピンがブロックされる前に返ることがある。
構文
HRESULT AsynchronousBlockOutputPin( HANDLE hNotifyCallerPinBlockedEvent );
パラメータ
- hNotifyCallerPinBlockedEvent
- イベントへのハンドル。出力ピンがブロックされるか、呼び出し元がブロック処理を取り消すと、イベントは通知済になる。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK 成功。 VFW_E_PIN_ALREADY_BLOCKED ピンは既に他のスレッドでブロックされている。 VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD ピンは既に呼び出し元のスレッドでブロックされている。
注意
ストリーミング スレッドからこのメソッドを呼び出してはならない。
ほかのストリーミング スレッドがピンを使っていない場合、このメソッドはすぐにピンをブロックする。それ以外の場合、このメソッドはピンの状態を "保留中" にして返る。ストリーミング処理が完了すると、ストリーミング スレッドは StopUsingOutputPin メソッドを呼び出してピンをブロックし、hNotifyCallerPinBlockedEvent イベントに通知する。保留中のブロックを取り消すには、UnblockOutputPin メソッドを呼び出す。
ピンからのデータの流れをブロック、またはブロック解除する。IPinFlowControl::Block メソッドを実装する。
構文
HRESULT Block( DWORD dwBlockFlags, HANDLE hEvent );
パラメータ
- dwBlockFlags
- ピンをブロックするか、ブロック解除するかを示すフラグ。次のいずれかの値でなくてはならない。
- ゼロ : ピンからのデータの流れをブロック解除する。
- AM_PIN_FLOW_CONTROL_BLOCK : ピンからのデータの流れをブロックする。
- hEvent
- イベント オブジェクトへのハンドル、または NULL。
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_FALSE ピンは既にブロック解除されている。 S_OK 成功。 E_INVALIDARG 無効な引数。 VFW_E_PIN_ALREADY_BLOCKED ピンはほかのスレッドで既にブロックされている。 VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD ピンは呼び出し元スレッドで既にブロックされている。
注意
このメソッドの詳細については、「IPinFlowControl::Block」を参照すること。このメソッドは、内部的には次のプロテクト メソッドのいずれかを呼び出す。
- ブロック (非同期) : AsynchronousBlockOutputPin
- ブロック (同期) : SynchronousBlockOutputPin
- ブロック解除 : UnblockOutputPin
ブロック解除は、常に同期に実行される。
ピンをブロックする。ピンがブロックされている間は、StartUsingOutputPin メソッドがピンのブロック解除を待つ。ブロック状態によって、出力ピンはサンプルの出力、出力フォーマットの変更、または再接続ができなくなる。
構文
void BlockOutputPin(void);
注意
このメソッドを呼び出す前に、m_BlockStateLock クリティカル セクションを保持すること。ストリーミング スレッドがこのピンを使用している、あるいはデータを出力している、あるいは接続を変更しているなら、このメソッドを呼び出してはならない。ストリーミング スレッドがこのピンを使用しているかどうかをチェックするには、StreamingThreadUsingOutputPin メソッドを呼び出すこと。
コンストラクタ メソッド。
構文
CDynamicOutputPin( TCHAR *pObjectName, CBaseFilter *pFilter, CCritSec *pLock, HRESULT *phr, LPCWSTR pName );
パラメータ
- pObjectName
- オブジェクトの名前を含む文字列へのポインタ。詳細については、「CBaseObject」を参照すること。
- pFilter
- このピンを作成したフィルタへのポインタ。
- pLock
- 状態変更を継続するために用いる CCritSec ロックへのポインタ。フィルタ ロック CBaseFilter.m_pLock と同じクリティカル セクションを使うこと。
- phr
- メソッドの成功または失敗を示す HRESULT 値を受け取る変数へのポインタ。値を S_OK に初期化してからオブジェクトを作成する。この値は、エラーが発生したときだけ変更される。
- pName
- ピン識別子を含む Unicode 文字列へのポインタ。詳細については、「IPin::QueryId」を参照すること。
デストラクタ メソッド。
構文
~CDynamicOutputPin(void);
接続のメディア タイプを動的に変更する。この変更は、フィルタ グラフの実行中にだけ発生する。このメソッドが呼び出されると、古いメディア タイプのサンプルは、出力できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。
構文
HRESULT ChangeMediaType( const CMediaType *pmt );
パラメータ
- pmt
- メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK 成功。 E_FAIL 失敗。 所有するフィルタが SetConfigInfo を呼び出さなかった可能性が高い。 VFW_E_NOT_CONNECTED ピンが接続されていない。
注意
このメソッドを呼び出す前に StartUsingOutputPin メソッドを呼び出すこと。
このメソッドは最初にダウンストリーム入力ピンが再接続なしに新しいフォーマットを受け入れるかどうかをチェックする。それは IPinConnection インターフェイスで入力ピンに問い合わせる。入力ピンが IPinConnection をサポートするなら、メソッドは提案されたメディア タイプで IPinConnection::DynamicQueryAccept メソッドを呼び出す。入力ピンが新しいメディア タイプを受け入れるなら、メソッドは IPin::ReceiveConnection メソッドを呼び出して、アロケータ要求を再処理する。
一方、ダウンストリーム ピンが IPinConnection をサポートしない、あるいは新しいメディア タイプを拒否したなら、メソッドは DynamicReconnect メソッドを呼び出して動的再接続を実行する。
接続しているメディア タイプを動的に変更し、新しいセグメント情報を出力する。このメソッドが呼び出されると、古いメディア タイプのサンプルは、出力できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。
構文
HRESULT ChangeOutputFormat( const AM_MEDIA_TYPE *pmt, REFERENCE_TIME tSegmentStart, REFERENCE_TIME tSegmentStop, double dSegmentRate );
パラメータ
- pmt
- メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
- tSegmentStart
- セグメントの開始タイム。
- tSegmentStop
- セグメントの終了タイム。
- dSegmentRate
- セグメント レート。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK 成功。 E_FAIL 失敗。多分所有者であるフィルタが SetConfigInfo を呼び出さなかった。 VFW_E_NOT_CONNECTED ピンが接続されていない。
注意
このメソッドはフィルタ実行中にフォーマットタイプを変更する。ダウンストリーム ピンが新しいフォーマットを承認すれば、再接続は不要である。そうでなければ、メソッドはピンを再接続しようとする。メソッドはフォーマットの変更に成功すると、新セグメント情報を出力する。このメソッドは ChangeMediaType メソッドを呼び出してフォーマット変更を実行する。
このメソッドを呼び出す前に StartUsingOutputPin メソッドを呼び出さなければならない。
入力ピンへの接続を完了する。
構文
virtual HRESULT CompleteConnect( IPin *pReceivePin );
パラメータ
- pReceivePin
- 入力ピンの IPin インターフェイスへのポインタ。
戻り値
成功した場合は S_OK を返す。または、HRESULT 値を返し、失敗の原因を示す。
注意
このメソッドは、CBaseOutputPin::CompleteConnect メソッドにオーバーライドする。動的な再接続をサポートするため、このメソッドは、フィルタがアクティブな場合にアロケータをコミットする。基底クラスでは、フィルタが停止しているときだけに接続は発生するので、アロケータは常に CBaseOutputPin::Active メソッドでコミットされる。
接続した入力ピンにフラッシュ処理を要求する。
構文
HRESULT DeliverBeginFlush(void);
戻り値
成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。
注意
このメソッドは CBaseOutputPin::DeliverBeginFlush メソッドをオーバーライドする。それは m_hStopEvent イベントを設定する。
接続した入力ピンにフラッシュ処理の終了を要求する。
構文
HRESULT DeliverEndFlush(void);
戻り値
成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。
注意
このメソッドは CBaseOutputPin::DeliverEndFlush メソッドをオーバーライドする。それは m_hStopEvent イベントをリセットする。
現在のピン接続を解除する。IPin::Disconnect メソッドを実装する。
構文
HRESULT Disconnect(void);
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_FALSE ピンは接続されなかった。 S_OK 成功。
注意
このメソッドは、CBasePin::Disconnect メソッドにオーバーライドし、フィルタがアクティブな間に切断ができるようにする。
新しいメディア タイプを使って動的な再接続を行う。再接続は、フィルタ グラフが実行中に行うことができる。
構文
HRESULT DynamicReconnect( const CMediaType *pmt );
パラメータ
- pmt
- メディア タイプを指定する AM_MEDIA_TYPE 構造体へのポインタ。
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_OK 成功。 E_FAIL 失敗。所有するフィルタが、SetConfigInfo メソッドを呼び出さなかった可能性が高い。
注意
このメソッドは、ピンにデータを提供するスレッドと同じスレッドから呼び出されなければならない。このメソッドが呼び出されると、古いメディア タイプのサンプルは提供できなくなる。呼び出し元は、古いサンプルが待機中でないことを確認しなければならない。
StartUsingOutputPin を呼び出して、このメソッドを呼び出す。
ピンにフィルタが停止していることを通知する。
構文
HRESULT Inactive(void);
戻り値
成功なら S_OK を返す、 それ以外なら失敗の原因を示す HRESULT 値を返す。
注意
このメソッドは CBaseOutputPin::Inactive メソッドをオーバーライドする。それは m_hStopEvent イベントを設定する。
IGraphConfig ポインタを指定し、イベントを停止する。
構文
void SetConfigInfo( IGraphConfig *pGraphConfig, HANDLE hStopEvent );
パラメータ
- pGraphConfig
- IGraphConfig インターフェイスへのポインタ、あるいは NULL。
- hStopEvent
- フィルタが停止するときに通知済のイベントへのハンドル、あるいは NULL。
注意
フィルタは、フィルタ グラフに参加するときに、このメソッドを呼び出さなければならない。フィルタ グラフ マネージャは、IGraphConfig をサポートしている。hStopEvent パラメータについては、手動リセット イベントを作成する。フィルタがフィルタ グラフから退出するとき、両方のパラメータを NULL にして、このメソッドをもう一度呼び出す。
ストリーミング操作でピンのアクセスを獲得する。
構文
virtual HRESULT StartUsingOutputPin(void);
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK 成功。 E_UNEXPECTED 予期せぬエラー。 VFW_E_STATE_CHANGED フィルタは停止された。または、ピンがフラッシングを開始した。
注意
接続された入力ピンにデータを出力するメソッド、または接続のメディア タイプを変更するメソッドを呼び出す前に、このメソッドを呼び出すこと。次の一覧は、このルールの適用先となるメソッドの例を示している。
- ChangeOutputFormat
- ChangeMediaType
- DynamicReconnect
- CBaseOutputPin::Deliver
- CBaseOutputPin::DeliverEndOfStream
- CBaseOutputPin::DeliverNewSegment
- IMemInputPin::Receive
- IMemInputPin::ReceiveMultiple
- IPin::EndOfStream
- IPin::NewSegment
その後で、StopUsingOutputPin メソッドを呼び出してピンへのアクセスを解放する。
ピンがブロックされているなら、StartUsingOutputPin はピンがブロック解除になるまで待つ。このメソッドが待っている間フィルタが停止するなら、メソッドはすぐに VFW_E_STATE_CHANGED を返す。ピンは StopUsingOutputPin への対応する呼び出しなしに何度StartUsingOutputPin が呼び出されたかという数を維持する。このカウントがゼロ以外のときに、他のスレッドがピンをブロックしようとすると、ピンはそのブロック状態を「待機」に設定する。最終的な StopUsingOutputPin 呼び出しで、ピンはストリーミング操作がすべて完了した後でブロック状態になる。
このメソッドを呼び出すときは、m_BlockStateLock クリティカル セクションを保持してはならない。そうでないと、ピンがブロックされたときブロック解除ができなくなりデッドロックを起こす。
ストリーミング操作の後ピンへのアクセスを解放する。
構文
virtual void StopUsingOutputPin(void);
参照
スレッドがピンでストリーミング操作を行っているかどうかを確認する。
構文
virtual bool StreamingThreadUsingOutputPin(void);
戻り値
スレッドがピンでストリーミング操作を行っていれば TRUE を返す。それ以外なら FALSE を返す。
注意
StartUsingOutputPin メソッドから正しく返されたスレッドがあり、対応する StopUsingOutputPin メソッドを呼び出さないと、このメソッドは TRUE を返す。
ピンをブロックする。ピンがブロック解除されるまで返らない。
構文
HRESULT SynchronousBlockOutputPin(void);
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_OK 成功。 VFW_E_PIN_ALREADY_BLOCKED ピンは既にほかのスレッドでブロックされている。 VFW_E_PIN_ALREADY_BLOCKED_ON_THIS_THREAD ピンは既に呼び出し元スレッドでブロックされている。
注意
ストリーミング スレッドからこのメソッドを呼び出さないこと。
ピンをブロック解除する。ピンがブロック解除されると、サンプルの出力、出力フォーマットの変更、および再接続ができるようになる。
構文
HRESULT UnblockOutputPin(void);
戻り値
次の表に示されるいずれかの HRESULT 値を返す。
S_FALSE Pin は既にブロック解除されている。 S_OK 成功。
指定されたイベントが通知済になるまで待つ。
構文
static HRESULT WaitEvent( HANDLE hEvent );
パラメータ
- hEvent
- イベントへのハンドル。
戻り値
HRESULT 値を返す。以下の表に示されるいずれかの値。
S_OK 成功。 E_UNEXPECTED 予期しないエラー。