Microsoft DirectX 8.0 |
入力ピンを実装する抽象基底クラス
宣言 : Amfilter.h
このクラスは IMemInputPin インターフェイスのサポートを追加し、さらに CBasePin によって提供される IPin インターフェイスのサポートを追加する。
このクラスを使用するには、新しいクラスを派生し、少なくとも以下のメソッドにオーバーライドする。
Protected メンバ変数 | |
---|---|
m_pAllocator | メモリ アロケータへのポインタ。 |
m_bReadOnly | アロケータが読み込み専用メディア サンプルを扱うかどうかを示すフラグ。 |
m_bFlushing | 現在フラッシュしているピンかどうかを示すフラグ。 |
m_SampleProps | 最新サンプルのプロパティ。 |
Public メソッド | |
CBaseInputPin | コンストラクタ メソッド。 |
~CBaseInputPin | デストラクタ メソッド。 |
BreakConnect | 接続からピンを解放する。 |
IsReadOnly | アロケータが読み込み専用メディア サンプルを使用するかどうか確認する。 |
IsFlushing | フィルタが現在フラッシュしているかどうか確認する。 |
CheckStreaming | ピンがサンプルを受け入れるかどうか決定する。仮想。 |
PassNotify | 品質コントロール メッセージを適切なオブジェクトに送る。 |
Inactive | ピンにフィルタが現在アクティブではないと通知する。仮想。 |
SampleProps | 最新サンプルのプロパティを取得。 |
IPin メソッド | |
BeginFlush | フラッシュ処理を開始する。 |
EndFlush | フラッシュ処理を終了する。 |
IMemInputPin メソッド | |
GetAllocator | このピンが提出したメモリ アロケータを取得する。 |
NotifyAllocator | 接続のアロケータを指定する。 |
GetAllocatorRequirements | 入力ピンが要求したアロケータ プロパティを取得する。 |
Receive | ストリーム内の次のメディア サンプルを取得する。 |
ReceiveMultiple | ストリーム内の複数のサンプルを取得する。 |
ReceiveCanBlock | Receive メソッドへの呼び出しがブロックになるかどうかを決定する。 |
IQualityControl メソッド | |
Notify | 品質コントロール メッセージを取得する。 |
メモリ アロケータへのポインタ。
構文
IMemAllocator *m_pAllocator;
アロケータが読み込み専用メディア サンプルを扱うかどうかを示すフラグ。 TRUE ならアロケータは読み込み専用サンプルを扱う。
構文
BYTE m_bReadOnly;
現在フラッシュしているピンかどうかを示すフラグ。TRUE ならピンはフラッシュしている。
構文
BYTE m_bFlushing;
最新サンプルのプロパティ。
構文
AM_SAMPLE2_PROPERTIES m_SampleProps;
フラッシュ処理を開始する。IPin::BeginFlush メソッドの実装。
構文
HRESULT BeginFlush(void);
戻り値
S_OK を返す。
注意
このメソッドは m_bFlushing フラグを TRUE にし、 Receive メソッドにこれ以上のサンプルを拒絶させる。
派生クラスはこのメソッドをオーバーライドし、次のステップを実行しなければならない。
- ダウンストリーム入力ピンの IPin::BeginFlush メソッドを呼び出す。ピンがまだメディア サンプル ダウンストリームを出力していないのなら、このステップは省略できる。出力ピンが CBaseOutputPin メソッドから出力されている場合は、 CBaseOutputPin::DeliverBeginFlush が呼び出せる。
- 基底クラス メソッドを呼び出す。
- キューにあるデータの廃棄を開始する。
- ブロックされている Receive メソッドへの呼び出しから戻る。
接続からピンを解放。
構文
HRESULT BreakConnect(void);
戻り値
成功すれば S_OK を返す、それ以外の場合エラーの原因を含む HRESULT 値を返す。
注意
このメソッドは CBasePin::BreakConnect メソッドをオーバーライドする。アロケータをデコミットにし、IMemAllocator インターフェイスを解放する。
このメソッドをオーバーライドする際は、オーバーライドするメソッドから基底クラスメソッドを呼び出すこと。そうしないとメモリ リークを起こす可能性がある。
コンストラクタ メソッド
構文
CBaseInputPin( TCHAR *pObjectName, CBaseFilter *pFilter, CCritSec *pLock, HRESULT *phr, LPCWSTR pPinName );
パラメータ
- pObjectName
- オブジェクトのデバッグ用の名前が入る文字列。詳細については、「CBaseObject」を参照すること。
- pFilter
- このピンを作成したフィルタへのポインタ。
- pLock
- CCritSec ロックへのポインタで、状態移行を継続するために使用する。これはフィルタ ロック CBaseFilter.m_pLock と同様のクリティカル セクションとなりうる。
- phr
- メソッドの成功・失敗を示す HRESULT 値を取得する変数のポインタ。
- pPinName
- (ピン ID としても使われる)ピン名が入る Unicode 文字列。
注意
すべてのパラメータは直接 CBasePin コンストラクタに送られる。
デストラクタ メソッド。
構文
~CBaseInputPin(void);
ピンがサンプルを受け入れるかどうか決定する。
構文
virtual HRESULT CheckStreaming(void);
戻り値
次の表に示す HRESULT 値の 1 つを返す。
S_OK 成功。 S_FALSE ピンは現在フラッシュしている。 VFW_E_RUNTIME_ERROR ランタイム エラーが起きた。 VFW_E_WRONG_STATE ピンは停止された。
注意
派生クラスはこのメソッドをオーバーライドし更にチェックを行うことができる。オーバーライドするメソッドではまた基底クラスの実装を呼び出す。
CBasePin::Receive メソッドはこのメソッドを呼び出す。同様に、CBasePin::EndOfStream メソッドをオーバーライドして、このメソッドを呼び出すべきである。
フラッシュ処理を終了する。IPin::EndFlush メソッドの実装。
構文
HRESULT EndFlush(void);
戻り値
S_OK を返す。
注意
このメソッドは m_bFlushing フラグを TRUE にセットし、Receive メソッドにサンプルを受け入れさせる。
派生クラスはこのメソッドをオーバーライドし、次のステップを実行しなければならない。
- バッファにあるデータを解放し、すべてのキューにあるサンプルを廃棄。
- ペンディングのEC_COMPLETE 通知をクリア。
- 基底クラス メソッドを呼び出す。
- ダウンストリーム 入力ピンの IPin::EndFlush を呼び出す。そのピンがまだメディア サンプル ダウンストリームをまだ送り出していない場合、このステップはスキップできる。出力ピンが CBaseOutputPin クラスから派生されているのなら、CBaseOutputPin::DeliverEndFlush メソッドが呼び出せる。
このピンが提出したメモリ アロケータを取得する。IMemInputPin::GetAllocator メソッドの実装。
構文
HRESULT GetAllocator( IMemAllocator **ppAllocator );
パラメータ
- ppAllocator
- アロケータの IMemAllocator インターフェイスへのポインタを受け取る変数のアドレス。
戻り値
成功なら S_OK を返す、それ以外の場合 CoCreateInstance からエラーコードを返す。
注意
このメソッドは CMemAllocator オブジェクトを作成する。フィルタがダウンストリーム ピンからのアロケータあるいはカスタム アロケータを使用するなら、このメソッドをオーバーライドすべきだ。
メソッドが成功すると、IMemAllocator インターフェイスは未処理の参照カウントを持つ。解放時には注意が必要。
入力ピンが要求したアロケータ プロパティを取得する。
構文
HRESULT GetAllocatorRequirements( ALLOCATOR_PROPERTIES *pProps );
パラメータ
- pProps
- 要求で満たされた ALLOCATOR_PROPERTIES 構造体へのポインタ。
戻り値
E_NOTIMPL を返す。
注意
出力ピンがメモリ アロケータを初期化するとき、このメソッドを呼び出して入力ピンがバッファ要求を持っているかどうかを調べることができる。詳細については、「CBaseOutputPin::DecideAllocator」を参照すること。
このメソッドの実装は任意である。フィルタが固有のアラインメントや前置値要求を持っているなら、このメソッドをオーバーライドすべきだ。
ピンにフィルタが現在アクティブではないと通知する。
構文
HRESULT Inactive(void);
戻り値
HRESULT 値を返す。次の表は、可能な値を示している。
S_OK 成功。 VFW_E_NO_ALLOCATOR 有効なメモリ アロケータがない。
注意
このメソッドは CBasePin::Inactive メソッドをオーバーライドする。それは IMemAllocator::Decommit メソッドを呼び出して、メモリ アロケータをデコミットにする。
このメソッドをオーバーライドするなら、そのオーバーライド メソッドから基底クラス メソッドを呼び出すこと。
フィルタが現在フラッシュしているかどうか確認する。
構文
BOOL IsFlushing(void);
戻り値
m_bFlushing メンバ変数を返す。
アロケータが読み込み専用メディア サンプルかどうか確認する。
構文
BOOL IsReadOnly(void);
戻り値
m_bReadOnly メンバ変数を返す。
品質変更が要求されたことをピンに知らせる。IQualityControl::Notify メソッドの実装。
構文
HRESULT Notify( IBaseFilter *pSelf, Quality q );
パラメータ
- pSelf
- 品質コントロール メッセージを送っているフィルタへのポインタ。
- q
- 品質コントロール メッセージを含む Quality 構造体。
戻り値
S_OK を返す。
注意
普通、フィルタは品質コントロール メッセージをアップストリーム出力ピンに送り、入力ピンには送らない。それゆえこのメソッドは何もしない場合以外は S_OK を返す。
詳細については、「品質コントロールの管理」を参照すること。
接続のアロケータを指定する。IMemInputPin::NotifyAllocator メソッドの実装。
構文
HRESULT NotifyAllocator( IMemAllocator *pAllocator, BOOL bReadOnly );
パラメータ
- pAllocator
- アロケータの IMemAllocator インターフェイスへのポインタ。
- bReadOnly
- このアロケータからのサンプルが読み込み専用かどうかを指定するフラグ。TRUE であればサンプルは読み込み専用。
戻り値
S_OK を返す。
注意
ピンが接続している間、出力ピンはアロケータを選択し、このメソッドを呼び出して入力ピンに通知する。出力ピンは入力ピンが IMemInputPin::GetAllocator メソッドで提供したアロケータを使用できる、あるいは自分自身のアロケータを提供できる。
品質コントロール メッセージを適切なオブジェクトに送る。
構文
HRESULT PassNotify( Quality q );
パラメータ
- q
- 品質コントロール メッセージを含む Quality 構造体。
戻り値
HRESULT 値を返す。次の表は、可能な値を示している。
S_OK 成功。 VFW_E_NOT_FOUND メッセージを受け入れるオブジェクトを見つけられない。
注意
フィルタが品質コントロール メッセージを取り扱わないなら、このメソッドを呼び出すこと。このメソッドはオブジェクトの 1 つに次の優先順でそのメッセージを送る :
- IQualityControl::SetSink が呼び出されたなら、外部品質コントロール マネージャ。
- アップストリーム出力ピン。
詳細については、「品質コントロールの管理」を参照すること。
ストリーム中の次のメディア サンプルを取得。IMemInputPin::Receive の実装。
構文
HRESULT Receive( IMediaSample *pSample );
パラメータ
- pSample
- サンプルの IMediaSample インターフェイスへのポインタ。
戻り値
HRESULT 値を返す。次の値のいずれか。
S_OK 成功。 S_FALSE ピンは現在フラッシュしている、サンプルは拒否される。 E_POINTER NULL ポインタ引数。 VFW_E_INVALIDMEDIATYPE 不適切なメディア タイプ。 VFW_E_RUNTIME_ERROR A ランタイム エラーが発生した。 VFW_E_WRONG_STATE ピンは停止中。
注意
アップストリーム出力ピンはこのメソッドを呼び出し、入力ピンにサンプルを出力する。入力ピンは次の 1 つを行わなければならない :
- 戻る前にサンプルを処理する。
- 戻り、ワーカー スレッドでサンプルを処理する。
- サンプルを拒否する。
ピンがワーカー スレッドを使ってサンプルを処理するなら、このメソッド内のサンプルへの参照カウントを追加する。このメソッドが戻った後で、アップストリーム ピンはサンプルを解放する。サンプルの参照カウントがゼロになると、サンプルは再使用のためにアロケータを返す。
このメソッドは同期され、ブロックできる。メソッドがブロックすると、ピンの ReceiveCanBlock メソッドは S_OK を返す。
基底クラスでは、このメソッドは次のステップを実行する :
- CheckStreaming メソッドを呼び出し、ピンがサンプルを今処理できることを検証する。できない場合たとえばピンが停止中メソッドは失敗する。
- サンプル プロパティを取得し、そのフォーマットが変更されたかどうかをチェック(次を参照)。
- フォーマットが変更になったなら、メソッドは CBasePin::CheckMediaType メソッドを呼び出し、新しいフォーマットが受け入れ可能かどうかを調べる。
- 新しいフォーマットが受け入れ可能でないなら、メソッドは CBasePin::EndOfStream メソッドを呼び出し、EC_ERRORABORT イベントをポストし、エラーコードを返す。
- エラーがないのであれば、メソッドは S_OK を返す。
フォーマット変更についてのテストは次のように行う :
- そのサンプルが IMediaSample2 インターフェイスをサポートするなら、AM_SAMPLE2_PROPERTIES 構造体の dwSampleFlags メンバをチェックする。AM_SAMPLE_TYPECHANGED フラグが含まれていれば、フォーマットは変更されている。
- そうではなく、IMediaSample2 サンプルをサポートしていないなら、IMediaSample::GetMediaType メソッドを呼び出す。メソッドが 非 NULL 値で返るなら、フォーマットは変更されている。
基底クラスでは、このメソッドはサンプルを処理しない。派生クラスはこのメソッドをオーバーライドし、処理を実行しなければならない(この結果はフィルタに完全に依存する)。 派生クラスは基底クラス メソッドを呼び出し、以前に記述されたエラーをチェックすべきだ。
IMemInputPin::Receive メソッドへの呼び出しがブロックされるかどうかを調べる。 IMemInputPin::ReceiveCanBlock メソッドの実装。
構文
HRESULT ReceiveCanBlock(void);
戻り値
Returns an HRESULT 値を返す。次の値のいずれか。
S_FALSE ピンは Receive を呼び出してもブロックしない。 S_OK ピンは Receive を呼び出すとブロックする可能性がある。
注意
Receive メソッドの呼び出しがブロックしないと保証されるなら、S_FALSE を返す。それ以外の場合は、S_OK かエラー コードを返す。Receive メソッドがダウンストリーム ピンの Receive を呼び出すと、ダウンストリーム ピンはブロックする可能性がある、 ReceiveCanBlock はアカウントにそのファクタを渡さなければならない。
アップストリーム フィルタはこのメソッドを使用して、スレッド戦略を決めることができる。Receive メソッドがブロックする可能性があるなら、アップストリーム フィルタはデータをバッファするワーカー スレッドの使用を決める事も可能だ。この戦略の実装については「COutputQueueクラス」を参照すること。
基底クラスでは、次のいずれかが真のときこのメソッドは S_OK を返す :
- フィルタが出力ピンを持たない。
- このフィルタに接続する入力ピンがブロックするかもしれないと通知する。
- このフィルタに接続されている入力ピンが IMemInputPin インターフェイスをサポートしない。
ストリーミング内の複数のサンプルを取得する。IMemInputPin::ReceiveMultiple メソッドの実装。
構文
HRESULT ReceiveMultiple( IMediaSample **pSamples, long nSamples, long *nSamplesProcessed );
パラメータ
- pSamples
- nSamples サイズの、複数の IMediaSample ポインタの配列のアドレス。
- nSamples
- 処理するサンプルの数。
- nSamplesProcessed
- 処理されたサンプルの数を受け取る変数のポインタ。
戻り値
HRESULT 値を返す。次の表は、可能な値を示している。
S_OK 成功。 S_FALSE ピンは現在フラッシュしている、サンプルは拒否された。 E_POINTER NULL ポインタ引数。 VFW_E_INVALIDMEDIATYPE 不適切なメディア タイプ。 VFW_E_RUNTIME_ERROR A ランタイム エラーが起きた。 VFW_E_WRONG_STATE ピンは停止中。
注意
このメソッドは Receive メソッドと同様に動作するが、サンプルの配列を受け取る。基底クラスでは、このメソッドは配列でループし、各サンプルに Receive を呼び出す。フィルタがサンプルのバッチを一度に処理するより効果的に処理できるなら、この関数をオーバーライドすること。
最新のサンプルのプロパティを AM_SAMPLE2_PROPERTIES 構造体として受け取る。
構文
AM_SAMPLE2_PROPERTIES *SampleProps(void);
戻り値
m_SampleProps メンバ変数のアドレスを返す。