Microsoft DirectX 8.0 |
変換フィルタを実装する基底クラス。
宣言 : Transfrm.h
このクラスは 1 つの入力ピント 1 つの出力ピンを持つ変換フィルタを実装するために設計されている。入力ピント出力ピンに別のアロケータを使用する。替わってデータを処理するフィルタを作成するには、CTransInPlaceFilter クラスを使用すること。
このフィルタは入力ピンに CTransformInputPin クラスを使い、出力ピンに CTransformOutputPin クラスを使う。通常、これらのピン クラスをオーバーライドする必要はない。大部分のピン メソッドは CTransformFilter クラスに対応するメソッドを呼び出すので、必要ならそのフィルタ メソッドをオーバーライドできる。フィルタは GetPin メソッド内で両方のピンを作成する。ピン クラスをオーバーライドするなら、GetPin をオーバーライドしてカスタム ピンを作成しなければならない。
デフォルトでは、入力ピンは接続プロセス中にメディア タイプを提案しない。それゆえ、入力ピン接続はアップストリーム フィルタ (利用可能であると仮定) が提案したメディア タイプを使って作成される。フィルタを登録するとき入力メディア タイプを登録するべきである、そうすればフィルタ マッパーはそれを見つけることができる。詳細については、「DirectShow オブジェクトの登録方法」を参照すること。
出力ピンはフィルタの GetMediaType メソッドを通してメディア タイプを提案する。出力ピンはそのフィルタの入力ピンが接続されるまで、接続を拒否する。
このクラスは出力データをキューに入れない。各出力サンプルは IMemInputPin::Receive 内部から出力される。
このクラスを使うには、新しいクラスを CTransformFilter から派生し、以下のメソッドを実装する :
フィルタの要求によって、他のメソッドを同様にオーバーライドする必要がある場合もある。
Protected メンバ変数 | |
---|---|
m_bEOSDelivered | フィルタがエンドオブストリーム (EOS) 通知を送ったかどうかを示すフラグ。 |
m_bSampleSkipped | 最新のサンプルが落とされたかどうかを示すフラグ。 |
m_bQualityChanged | 品質が変更されたかどうかを示すフラグ。 |
m_csFilter | フィルタ状態を保護するクリティカル セクション。 |
m_csReceive | ストリーミング状態を保護するクリティカル セクション。 |
m_pInput | 入力ピンへのポインタ。 |
m_pOutput | 出力ピンへのポインタ。 |
Public メソッド | |
CTransformFilter | コンストラクタ メソッド。 |
~CTransformFilter | デストラクタ メソッド。 |
GetPinCount | フィルタ上のピンの数を取得する。仮想。 |
GetPin | ピンを取得する。仮想。 |
Transform | 入力サンプルを変換して出力サンプルを作成する。 仮想。 |
StartStreaming | フィルタがポーズ状態にスイッチしたとき呼び出される。仮想。 |
StopStreaming | フィルタが停止状態にスイッチしたとき呼び出される。仮想。 |
AlterQuality | 品質変更が要求されたことをフィルタに通知する。仮想。 |
SetMediaType | メディア タイプがフィルタのピンの 1 つにセットされたとき呼び出される。仮想。 |
CheckConnect | ピン接続が適切かどうかを確認する。 仮想。 |
BreakConnect | ピン接続を解除する。仮想。 |
CompleteConnect | ピン接続を完了する。仮想。 |
Receive | メディア サンプルを取得し、それを処理し、ダウンストリーム フィルタに出力サンプルを出力する。仮想。 |
InitializeOutputSample | 新しい出力サンプルを取得し、それを初期化する。 |
EndOfStream | 入力ピンから追加のデータは来ないことをフィルタに通知する。仮想。 |
BeginFlush | フラッシュ処理を開始する。仮想。 |
EndFlush | フラッシュ処理を終了する。仮想。 |
NewSegment | この呼出し語に受け取ったメディア サンプルがセグメントとしてグループ化されていることをフィルタに通知する。仮想。 |
Pure Virtual メソッド | |
CheckInputType | 指定されたメディア タイプが入力として許容されるかどうかチェックする。 |
CheckTransform | 入力メディア タイプが出力メディア タイプと互換性があるかどうかチェックする。 |
DecideBufferSize | 出力ピンのバッファ要求を設定する。 |
GetMediaType | 出力ピンの優先メディア タイプを取得する。 |
IMediaFilter メソッド | |
Stop | フィルタを停止する。 |
Pause | フィルタをポーズする。 |
IBaseFilter メソッド | |
FindPin | 指定した ID でピンを取得する。 |
フィルタがエンドオブストリーム (EOS) 通知を送ったかどうかを示すフラグ。
構文
BOOL m_bEOSDelivered;
注意
入力接続を持っていないとき、フィルタがポーズなら、フィルタはエンドオブストリーム (EOS) 通知をダウンストリームに送り、このフラグを TRUE に設定する。エンドオブストリーム (EOS) 通知によってダウンストリーム フィルタはサンプルを待たなくなる。フィルタの EndOfStream メソッドはこのフラグを セットしない ことに注意。
最新のサンプルが落とされたかどうかを示すフラグ。もし Receive がサンプルを落としたなら、それはこの値を TRUE に設定する。
構文
BOOL m_bSampleSkipped;
品質が変更されたかどうかを示すフラグ。フィルタがサンプルを落とすと、最初に EC_QUALITY_CHANGE イベントをフィルタ グラフ マネージャに送り、このフラグを TRUE に設定する。たとえサンプルのドロップが続いても、フィルタが停止し再スタートするまで、このイベントは再送信されない。
構文
BOOL m_bQualityChanged;
フィルタ状態を保護するクリティカル セクション。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。
構文
CCritSec m_csFilter;
ストリーミング状態を保護するクリティカル セクション。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。
構文
CCritSec m_csReceive;
入力ピンへのポインタ。
構文
CTransformInputPin *m_pInput;
出力ピンへのポインタ。
構文
CTransformOutputPin *m_pOutput;
品質変更が要求されたことをフィルタに通知する。
構文
virtual HRESULT AlterQuality( Quality q );
パラメータ
- q
- 品質管理メッセージが入る Quality 構造体。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_FALSE 品質メッセージを処理できなかった。メッセージはアップストリームに渡されるべきだ。 S_OK 品質メッセージを処理した。これ以上の作業は不要である。 基底クラスは S_FALSE を返す。
注意
フィルタが品質コントロールを処理できるなら、このメソッドをオーバーライドすること。詳細については、「品質コントロールの管理」を参照すること。
フラッシュ処理を開始する。
構文
virtual HRESULT BeginFlush(void);
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
フラッシュ処理開始時に入力ピンの CTransformInputPin::BeginFlush メソッドはこのメソッドを呼び出す。このメソッドは BeginFlush 呼び出しをダウンストリームに渡す。
派生クラスがサンプルの出力にワーカー スレッドを使っているなら、フラッシュ処理中にキューに入っているデータを破棄すべきである。それは BeginFlush メソッド内か、EndFlush メソッド内で行うことができる。しかし、 BeginFlush への呼び出しはストリーミング スレッドとは同期していないことに注意。もし BeginFlush メソッドがキューに入っているデータを破棄するなら、フィルタは BeginFlush 呼び出しと EndFlush 呼び出しの間にデータの処理をしない事に注意しなければならない。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。
ピン接続を解除する。
構文
virtual HRESULT BreakConnect( PIN_DIRECTION dir );
パラメータ
- dir
- PIN_DIRECTION 列挙型のメンバ、(入力ピンあるいは出力ピンの)ピン接続が離れたかどうかを示す。
戻り値
S_OK を返す。
注意
CTransformInputPin::BreakConnect と CTransformOutputPin::BreakConnect メソッドはピン接続を解除するときこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。CheckConnect メソッドをオーバーライドするなら、このメソッドをオーバーライドして CheckConnect メソッドで取得したインターフェイスのポインタを含むリソースをリリ−スする。
ピン接続が適切かどうかを確認する。
構文
virtual HRESULT CheckConnect( PIN_DIRECTION dir, IPin *pPin );
パラメータ
- dir
- PIN_DIRECTION 列挙型のメンバ、フィルタのどのピンが接続を作成するかを示す。
- pPin
- この接続を試みている相手の IPin インターフェイスへのポインタ。
戻り値
S_OK を返す。
注意
CTransformInputPin::CheckConnect と CTransformOutputPin::CheckConnect メソッドはピン接続プロセス中にこのメソッドを呼び出す。このメソッドは基底クラスでは何もしない。派生クラスはそれをオーバーライドできる。たとえば、派生クラスは個別のインターフェイスで別のピンをクエリする場合がある。
指定されたメディア タイプが入力として許容されるかどうかチェックする。
構文
virtual HRESULT CheckInputType( const CMediaType *mtIn ) PURE;
パラメータ
- mtIn
- メディア タイプを指定する CMediaType オブジェクトへのポインタ。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK メディア タイプは許容された。 VFW_E_TYPE_NOT_ACCEPTED メディア タイプは許容されない。
注意
派生クラスはこのメソッドを実装しなければならない。提案された入力フォーマットが許容可能であれば S_OK が返る、そうでなければエラーコードが返る。
このメソッドは (必要だとしても) 入力フォーマットが出力フォーマットと互換性があるかを検証しない。入力ピンは CheckTransform メソッドを呼び出してそれを検証する。
入力メディア タイプが出力メディア タイプと互換性があるかどうかチェックする。
構文
virtual HRESULT CheckTransform( const CMediaType *mtIn, const CMediaType *mtOut ) PURE;
パラメータ
- mtIn
- 入力タイプを指定する CMediaType オブジェクトへのポインタ。
- mtOut
- 出力タイプを指定する CMediaType オブジェクトへのポインタ。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK メディア タイプは互換性がある。 VFW_E_TYPE_NOT_ACCEPTED メディア タイプは互換性がない。
注意
派生クラスはこのメソッドを実装しなければならない。提案された入力フォーマットが許容可能であれば S_OK が返る、そうでなければエラーコードが返る。
ピン接続を完了する。
構文
virtual HRESULT CompleteConnect( PIN_DIRECTION direction, IPin *pReceivePin );
パラメータ
- direction
- PIN_DIRECTION 列挙型のメンバ、フィルタのどのピンが接続を作成するかを示す。
- pReceivePin
- この接続を試みている相手の IPin インターフェイスへのポインタ。
戻り値
S_OK を返す。
注意
CTransformInputPin::CompleteConnect と CTransformOutputPin::CompleteConnect メソッドはピン接続プロセス中にこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
コンストラクタ メソッド。
構文
CTransformFilter( TCHAR *pObjectName, LPUNKNOWN lpUnk, CLSID clsid );
パラメータ
- pObjectName
- フィルタのデバッグ名が入る文字列。詳細については、「CBaseObject」を参照すること。
- lpUnk
- このオブジェクトの所有者へのポインタ。オブジェクトが集成されているなら、集成オブジェクトの IUnknown インターフェイスへのポインタを渡し、このパラメータを NULL にする。
- clsid
- フィルタのクラス ID。
注意
コンストラクタはフィルタのピンを作成しない。それは GetPin メソッドを最初に呼び出す間に行われる。コンストラクタは m_pInput と m_pOutput メンバ変数を NULL に初期化する。
デストラクタ メソッド。
構文
~CTransformFilter(void);
出力ピンのバッファ要求を設定する。
構文
virtual HRESULT DecideBufferSize( IMemAllocator *pAlloc, ALLOCATOR_PROPERTIES *ppropInputRequest ) PURE;
パラメータ
- pAlloc
- 出力ピンのアロケータの IMemAllocator インターフェイスへのポインタ。
- ppropInputRequest
- ダウンストリーム入力ピンからのバッファ要求が入る ALLOCATOR_PROPERTIES 構造体へのポインタ。
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
出力ピンの CTransformOutputPin::DecideBufferSize メソッドはこのメソッドを呼び出す。派生クラスはこのメソッドを実装しなければならない。詳細については、「CBaseOutputPin::DecideBufferSize」を参照すること。
フラッシュ処理を終了する。
構文
virtual HRESULT EndFlush(void);
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
フラッシュ処理の終りに、入力ピンの CTransformInputPin::EndFlush メソッドはコンメソッドを呼び出す。このメソッドは EndFlush 呼び出しをダウンストリームに渡す。
派生クラスがワーカースレッドを使ってサンプルを出力するなら、EndFlush 呼び出しをダウンストリームに送る前にキュー内のデータを破棄しなければならない。詳細については、「フィルタ開発者が使用するデータ フロー」を参照すること。
入力ピンから追加のデータは来ないことをフィルタに通知する。
構文
virtual HRESULT EndOfStream(void);
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
入力ピンの CTransformInputPin::EndOfStream メソッドはこのメソッドを呼び出す。このメソッドはエンドオブストリーム (EOS) 通知をダウンストリームに出力する。派生クラスがワーカースレッドを使ってメディア サンプルを出力するなら、このメソッドをオーバーライドしてエンドオブストリーム (EOS) 通知をキューに入れるべきである。
指定した ID でピンを取得する。IBaseFilter::FindPin メソッドの実装。
構文
HRESULT FindPin( LPCWSTR Id, IPin **ppPin );
パラメータ
- Id
- ピン ID が入るワイド文字列。
- ppPin
- ピンの IPin インターフェイスへのポインタを受け取る変数のアドレス。メソッドが失敗すると、*ppPin は NULL にセットされる。
戻り値
以下の表に示される HRESULT 値の 1 つを返す。
S_OK 成功。 E_OUTOFMEMORY メモリ不足。 E_POINTER NULL ポインタ引数。 VFW_E_NOT_FOUND この ID でピンを見つけられなかった。
注意
入力ピンの ID は In であり、出力ピンの ID は Out である。
出力ピンの優先メディア タイプを取得する。
構文
virtual HRESULT GetMediaType( int iPosition, CMediaType *pMediaType ) PURE;
パラメータ
- iPosition
- ゼロから始まるインデックス値
- pMediaType
- メディア タイプを受け取る CMediaType オブジェクトへのポインタ。
戻り値
HRESULT 値を返す。 以下の表に示されるいずれかの値。
S_OK 成功。 VFW_S_NO_MORE_ITEMS インデックスが許容幅を超えた。 E_INVALIDARG インデックスがゼロより小さい。
注意
出力ピンの CTransformOutputPin::GetMediaType メソッドはこのメソッドを呼び出す。派生クラスはこのメソッドを実装しなければならない。 詳細については、「CBasePin::GetMediaType を参照すること。
ピンを取得する。
構文
virtual CBasePin *GetPin( int n );
パラメータ
- n
- 指定されたピンの数、ゼロから始まるインデックス。このフィルタでは、ピン 0 は入力ピンで、ピン 1 は出力ピン。
戻り値
ピンを実装する CBasePin オブジェクトへのポインタを返す、メソッドが失敗すると NULL を返す。
注意
このメソッドは純粋仮想 CBaseFilter::GetPin メソッドを実装する。初めてメソッドが呼び出されると、両方のピンを作成する。
このメソッドは返ったピンの参照カウントをインクリメントしないので、返ったピンは未処理の参照カウントを持たない。呼び出し元がピンへの参照を保持する必要があるなら、そのピンで IUnknown::AddRef を呼び出すべきである。
フィルタがデフォルトCTransformInputPin ピンと CTransformOutputPin ピンを使うなら、このメソッドをオーバーライドする必要はない。しかしフィルタがクラスを拡張したピンを使うなら。このメソッドをオーバーライドしてそのタイプのピンを作成しなければならない。
フィルタ上のピンの数を取得する。
構文
virtual int GetPinCount(void);
戻り値
2 を返す。
注意
このメソッドは CBaseFilter::GetPinCount メソッドをオーバーライドする。実際にはこのクラスは入力ピン 1 つと出力ピン 1 つをサポートする。
新しい出力サンプルを取得し、それを初期化する。
構文
HRESULT InitializeOutputSample( IMediaSample *pSample, IMediaSample **ppOutSample );
パラメータ
- pSample
- 入力サンプルの IMediaSample インターフェイスへのポインタ。
- ppOutSample
- 出力サンプルの IMediaSample インターフェイスへのポインタを受け取る変数のアドレス。
戻り値
S_OK を返す、あるいは別の HRESULT 値を返す。
注意
このメソッドは新しいサンプルを出力ピンのアロケータから取得する、次に入力サンプルから出力サンプルにサンプル プロパティをコピーする。
この呼出し語に受け取ったメディア サンプルがセグメントとしてグループ化されていることをフィルタに通知する。
構文
virtual HRESULT NewSegment( REFERENCE_TIME tStart, REFERENCE_TIME tStop, double dRate );
パラメータ
- tStart
- セグメントの開始タイム、オリジナル ソースからの相対値。
- tStop
- セグメントのストップ タイム、オリジナル ソースからの相対値。
- dRate
- セグメントが処理されるべきレート。
戻り値
S_OK を返す。
注意
入力ピンの CTransformInputPin::NewSegment メソッドはこのメソッドを呼び出す。このメソッドは NewSegment 呼び出しをダウンストリームの入力ピンに出力する。
フィルタをポーズする。IMediaFilter::Pause を実装。
構文
HRESULT Pause(void);
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
このメソッドは StartStreaming メソッドを呼び出す。StartStreaming メソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
メディア サンプルを取得し、それを処理し、ダウンストリーム フィルタに出力サンプルを出力する。
構文
HRESULT Receive( IMediaSample *pSample );
パラメータ
- pSample
- 入力サンプルの IMediaSample インターフェイスへのポインタ。
戻り値
HRESULT 値を返す。
注意
フィルタの入力ピンはサンプルを取得したときこのメソッドを呼び出す。このメソッドは InitializeOutputSample メソッドを呼び出す、それは新しい出力サンプルを準備する。次にそれは Transform メソッドを呼び出す、これは派生クラスが実装しなければならない。Transform メソッドは入力データを処理し、出力データを作成する。
Transform メソッドが S_FALSE を返すと、Receive メソッドはこのサンプルをドロップする。最初のドロップ サンプルで、フィルタは EC_QUALITY_CHANGE イベントをフィルタ グラフ マネージャに送る。一方、Transform が S_OK を返すなら、フィルタは出力サンプルを出力する。そのために、IMemInputPin::Receive メソッドをダウンストリーム入力ピンで呼び出す。
メディア タイプがフィルタのピンの 1 つにセットされたとき呼び出される。
構文
virtual HRESULT SetMediaType( PIN_DIRECTION direction, const CMediaType *pmt );
パラメータ
- direction
- PIN_DIRECTION 列挙型のメンバ、フィルタのピン(入力ピンあるいは出力ピン)を指定する。
- pmt
- メディア タイプを指定する CMediaType オブジェクトへのポインタ。
戻り値
S_OK を返す。
注意
CTransformInputPin::SetMediaType メソッドと CTransformOutputPin::SetMediaType メソッドはピンのメディアタイプを設定するときこのメソッドを呼び出す。このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
フィルタがポーズ状態にスイッチしたとき呼び出される。
構文
virtual HRESULT StartStreaming(void);
戻り値
S_OK を返す。
注意
このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
フィルタを停止する。IMediaFilter::Stop メソッドの実装。
構文
HRESULT Stop(void);
戻り値
S_OK を返す、あるいは他の HRESULT 値を返す。
注意
このメソッドは両方のアロケータをデコミットにした後で、StopStreaming メソッドを呼び出す。StopStreaming メソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
フィルタが停止状態にスイッチしたとき呼び出される。
構文
virtual HRESULT StopStreaming(void);
戻り値
S_OK を返す。
注意
このメソッドは基底クラスでは何もしないが、派生クラスはそれをオーバーライドできる。
入力サンプルを変換して出力サンプルを作成する。
構文
virtual HRESULT Transform( IMediaSample *pIn, IMediaSample *pOut )
パラメータ
- pIn
- 入力サンプルの IMediaSample インターフェイスへのポインタ。
- pOut
- 出力サンプルの IMediaSample インターフェイスへのポインタ。
戻り値
基底クラスは E_UNEXPECTED を返す。
派生クラスは成功失敗を示す HRESULT 値を返すべきである。 以下の表に示されるいずれかの値。
S_FALSE このサンプルを出力しない。 S_OK 成功。
注意
出力データを作成するにはこのメソッドをオーバーライドすること。入力データを pIn パラメータで指定されたサンプルから読み込み。新しいデータを pOut パラメータで指定されたサンプルに書き込む。
フィルタがこのメソッドを呼び出す前に、それは入力サンプルから出力サンプルにプロパティをコピーする。Transform メソッドは 2 つのサンプル間で異なるプロパティをセットすべきである、それには IMediaSample メソッドを使うか、あるいは (もし利用可能なら) IMediaSample2 インターフェイスを使う。
フィルタがこのサンプルを出力するべきではないなら (たとえば、品質管理をコントロールするため)、このメソッドは S_FALSE を返すべきである。