Microsoft DirectX 8.0 |
ストリーム内の位置にシークするメソッドと、再生レートを設定するメソッドが含まれる。
フィルタ グラフ マネージャは、個々のフィルタと同じように、このインターフェイスを公開する。アプリケーションはフィルタからではなく、フィルタ グラフ マネージャからこのインターフェイスを取得する必要がある。フィルタ グラフ マネージャは、メソッドをすべてのレンダリング フィルタに割り当てる。レンダリング フィルタは、その呼び出しをソース フィルタへのアップストリームに送る。すべてのストリームは、イベントのこのシーケンスによって同期される。
配布されたいずれかの呼び出しがエラーを返した場合、フィルタ グラフ マネージャは、配布された呼び出しの一部が成功した場合でも、最初に受け取ったエラー値を返す。この例外には、E_NOTIMPL がある。フィルタ グラフ マネージャは、配布されたすべての呼び出しが E_NOTIMPL を返さない限り、E_NOTIMPL を返さない。
グラフがどの状態 (実行中、ポーズ、停止中) にあっても、アプリケーションはグラフをシークできる。グラフが実行中の場合、フィルタ グラフ マネージャはシークコマンドを処理する前にグラフをポーズする。その後、グラフを再度実行状態にする。すべてのシーク操作は、現在の再生レートには依存しない。シーク操作によって残っているメディア データは、グラフからフラッシュされる。
このインターフェイスは、IMediaPosition インターフェイスよりも強化されている。IMediaPosition のメソッドでは、コンマ秒単位のタイム パラメータを必要とするのに対して、IMediaSeeking メソッドでは、フレーム、バイト、100 ナノ秒単位など任意のフォーマットを使用できる。また、IMediaSeeking はより高い精度を提供するために、64 ビット整数 (LONGLONG) を使用する。一方、IMediaSeeking は Automation と互換性がないので、Microsoft® Visual Basic® で書かれたアプリケーションは IMediaPosition を使用しなければならない。
タイムおよびタイムの単位を指定する IMediaSeeking のすべてのパラメータは、現在使用中のタイム フォーマットには依存しない。タイム フォーマットを設定するには、IMediaSeeking::SetTimeFormat を呼び出す。タイム フォーマットは、uuids.h で定義されているグローバルに一意の識別子 (GUID) である。詳細については、「タイム フォーマット GUID」を参照すること。
Vtable 順のメソッド
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IMediaSeeking メソッド 説明 GetCapabilities ストリームのすべてのシーク能力を取得する。 CheckCapabilities 指定したシーク能力をストリームが持っているかどうかを照会する。 IsFormatSupported 指定したタイム フォーマットをストリームがサポートしているかどうかを確認する。 QueryPreferredFormat ストリームの優先タイム フォーマットを取得する。 GetTimeFormat 現在のタイム フォーマットを取得する。 IsUsingTimeFormat 指定したタイム フォーマットが現在使用中のフォーマットかどうかを確認する。 SetTimeFormat タイム フォーマットを設定する。 GetDuration ストリームの時間幅を取得する。 GetStopPosition ストリームの時間幅に対して、再生が停止するタイムを取得する。 GetCurrentPosition ストリームの時間幅に対する現在の位置を取得する。 ConvertTimeFormat あるタイム フォーマットをほかのフォーマットに変換する。 SetPositions 現在の位置と停止位置を設定する。 GetPositions ストリームの時間幅に対する、現在の位置と停止位置を取得する。 GetAvailable シークが有効なタイムの範囲を取得する。 SetRate 再生レートを設定する。 GetRate 再生レートを取得する。 GetPreroll 開始位置の前にキューに入っているデータの量を取得する。
指定したシーク能力をストリームが持っているかどうかを照会する。
構文
HRESULT CheckCapabilities( DWORD *pCapabilities );
パラメータ
- pCapabilities
- [in, out] AM_SEEKING_SEEKING_CAPABILITIES 属性の 1 つまたは複数のビットごとの組み合わせへのポインタ。メソッドの戻り値は、どの属性が利用可能であるかを示す。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_FALSE pCapabilities のすべての能力を持ってはいない。 S_OK pCapabilities のすべての能力がある。 E_FAIL pCapabilities の能力がまったくない。 E_POINTER NULL ポインタ引数。
注意
2 〜 3 の能力だけが必要な場合、すべてのストリームのシーク能力をチェックする GetCapabilities を呼び出すよりも、このメソッドの方が効率的である。
テストする AM_SEEKING_SEEKING_CAPABILITIES 属性のビットごとの OR 組み合わせと等しい DWORD を宣言し、pCapabilities パラメータにこの値のポインタを渡す。メソッドが返ると、pCapabilities には元のビットのサブセットが入り、実際にどの能力があるかを示す。戻り値は、要求した能力がない、いくつかある、またはすべてあることを示す値を返す。
次のコード サンプルは、ストリームが順方向シーク、逆方向シーク、および絶対シークをサポートしているかどうかを調べる方法を示している。
// チェックする能力のフラグを設定する。 DWORD dwCaps = AM_SEEKING_CanSeekAbsolute | AM_SEEKING_CanSeekForwards | AM_SEEKING_CanSeekBackwards; HRESULT hr = pMediaSeeking->CheckCapabilities(&dwCaps); if(FAILED(hr)) { // ストリームではシークはできない。 } else if (hr == S_OK) { // ストリームでは、順方向シーク、逆方向シーク、および絶対シークができる。 } else if (hr == S_FALSE) // ストリームはいくつかの能力を持つ可能性がある。 { if (dwCaps & AM_SEEKING_CanSeekAbsolute) // ストリームは絶対位置へのシークができる。 if dwCaps & AM_SEEKING_CanSeekAbsolute) // ストリームは順方向へのシークができる。 if (dwCaps & AM_SEEKING_CanSeekBackwards) // ストリームは逆方向へのシークができる。 }
あるタイム フォーマットをほかのフォーマットに変換する。
構文
HRESULT ConvertTimeFormat( LONGLONG *pTarget, const GUID *pTargetFormat, LONGLONG Source, const GUID *pSourceFormat );
パラメータ
- pTarget
- [out] 変換したタイム値を受け取る変数へのポインタ。
- pTargetFormat
- [in] 目的のフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のフォーマットが使われる。
- Source
- [in] 変換されるタイム値。
- pSourceFormat
- [in] 変換するフォーマットのタイム フォーマット GUID へのポインタ。NULL の場合は、現在のタイム フォーマットが使われる。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_INVALIDARG このタイプ間の変換はサポートされていない。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
シークが有効なタイムの範囲を取得する。
構文
HRESULT GetAvailable( LONGLONG *pEarliest, LONGLONG *pLatest );
パラメータ
- pEarliest
- [out] シークが有効な、最も早いタイムを受け取る変数へのポインタ。
- pLatest
- [out] シークが有効な、最も遅いタイムを受け取る変数へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
このメソッドは、主にネットワークを越えて送られてくるような、遅延の大きなメディア ストリームでのシークを対象としている。戻り値は、容易にシーク可能な、既に到着済みのキャッシュ データを表す。返されたパラメータを超えた値をシークすると、アプリケーションがデータの到着を待つ間、遅延が発生することが想定されている。
ストリームのすべてのシーク能力を取得する。
構文
HRESULT GetCapabilities( DWORD *pCapabilities );
パラメータ
- pCapabilities
- [out] AM_SEEKING_SEEKING_CAPABILITIES フラグのビットごとの組み合わせを受け取る変数へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_POINTER NULL ポインタ引数。
注意
このメソッドは、ストリームのすべてのシーク能力に関する情報を返す。必要な AM_SEEKING_SEEKING_CAPABILITIES 値について、ビットごとの AND 操作を行い、pCapabilities を調べること。
DWORD dwCaps = 0; pMediaSeeking->GetCapabilities(&dwCaps); if (dwCaps & AM_SEEKING_CanGetCurrentPos) { // ストリームでは現在位置へのシークができる。 } if (dwCaps & AM_SEEKING_CanPlayBackwards) { // ストリームでは再生逆方向へのシークができる。 }
ストリームの合計時間幅に対する現在の位置を取得する。
構文
HRESULT GetCurrentPosition( LONGLONG *pCurrent );
パラメータ
- pCurrent
- [out] 現在位置を取得する変数へのポインタ (現在のタイム フォーマットの単位)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
このメソッドは、再生が到達した現在位置を返す。この値では、再生レートと開始タイムは無視される。たとえば、レートに 2.0 を設定し、開始タイムが 5 秒だとすると、グラフを 4 秒実行すると現在の位置は 9.0 秒となる (5 + 4 × 2.0)。戻り値は、現在のタイム フォーマットの単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。
グラフがポーズまたは停止されている場合、現在位置は再生が再開されるポイントとなる。
フィルタ グラフ マネージャは、現在のストリーム タイムから位置を計算するので、グラフのフィルタに照会することはない。ファイルの再生では、これによって再生がストリーム タイムに同期されるため、正確な結果が得られる。ファイルの書き込みでは、結果は正確にはならない。ファイルを書き込むグラフで現在の位置を取得するには、マルチプレクサ フィルタに照会すること。ただし、ライブ キャプチャでは、位置は適切なものとはならない。
ストリームの時間幅を取得する。
構文
HRESULT GetDuration( LONGLONG *pDuration );
パラメータ
- pDuration
- [out] 時間幅を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
このメソッドは、通常、再生速度での時間幅を取得する。再生レートはこの時間幅には影響を与えない。戻り値は現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。
ストリームの合計時間幅に対する、現在の位置と停止位置を取得する。
構文
HRESULT GetPositions( LONGLONG *pCurrent, LONGLONG *pStop );
パラメータ
- pCurrent
- [out] 現在位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
- pStop
- [out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
現在位置と停止位置は、両方とも元のストリームに対する値であり、再生レートには依存しない。
戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。
開始位置の前にキューに入っているデータの量を取得する。
構文
HRESULT GetPreroll( LONGLONG *pllPreroll );
パラメータ
- pllPreroll
- [out] プリロール タイムを受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
プリロールは、テープ プレーヤーのような非ランダム アクセス デバイスで、ローリングが開始される開始位置より前のタイムである。
再生レートを取得する。
構文
HRESULT GetRate( double *dRate );
パラメータ
- dRate
- [out] 再生レートを受け取る変数へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。
ストリームの時間幅に対して、再生が停止するタイムを取得する。
構文
HRESULT GetStopPosition( LONGLONG *pStop );
パラメータ
- pStop
- [out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
再生レートは、このメソッドによって返る値に影響を与えない。戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。
現在のタイム フォーマットを取得する。
構文
HRESULT GetTimeFormat( GUID *pFormat );
パラメータ
- pFormat
- [out] タイム フォーマット GUID を受け取る変数へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_POINTER NULL ポインタ引数。
指定したタイム フォーマットをストリームがサポートしているかどうかを確認する。
構文
HRESULT IsFormatSupported( const GUID *pFormat );
パラメータ
- pFormat
- [in] タイム フォーマット GUID へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_FALSE フォーマットはサポートされていない。 S_OK フォーマットはサポートされている。 E_NOTIMPL 実装されていない。 E_POINTER NULL ポインタ引数。
指定したタイム フォーマットが現在使用中のフォーマットかどうかを確認する。
構文
HRESULT IsUsingTimeFormat( const GUID *pFormat );
パラメータ
- pFormat
- [in] タイム フォーマット GUID へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_FALSE 指定したフォーマットは現在のフォーマットではない。 S_OK 指定したフォーマットは現在のフォーマットである。 E_NOTIMPL 実装されていない。 E_POINTER NULL ポインタ引数。
注意
このメソッドは GUID をコピーする必要がないため、IMediaSeeking::GetTimeFormat メソッドよりも効率的である。
ストリームの優先タイム フォーマットを取得する。
構文
HRESULT QueryPreferredFormat( GUID *pFormat );
パラメータ
- pFormat
- [out] タイム フォーマット GUID へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_NOTIMPL 実装されていない。 E_POINTER NULL ポインタ引数。
注意
返されたフォーマットが不十分な場合は、IsFormatSupported メソッドを呼び出して、ほかにサポートされているタイム フォーマットを照会すること。
現在の位置と停止位置を設定する。
構文
HRESULT SetPositions( LONGLONG *pCurrent, DWORD dwCurrentFlags, LONGLONG *pStop, DWORD dwStopFlags );
パラメータ
- pCurrent
- [in,out] 現在のタイムを指定する変数へのポインタ (現在のタイム フォーマットの単位)。
- dwCurrentFlags
- [in] フラグのビットごとの組み合わせ (「注意」を参照)。
- pStop
- [in,out] 現在のタイムを指定する変数へのポインタ (現在のタイム フォーマットの単位)。
- dwStopFlags
- [in] フラグのビットごとの組み合わせ (「注意」を参照)。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_FALSE 位置変更はない(両方のフラグがシークしないと指定)。 S_OK 成功。 E_INVALIDARG 不適切な引数。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。
注意
dwCurrentFlags パラメータと dwStopFlags パラメータには、シーク タイプを定義する。次のフラグが定義されている。
位置フラグ AM_SEEKING_NoPositioning 位置の変更はない。タイム パラメータは、NULL とすることもできる。 AM_SEEKING_AbsolutePositioning 指定した位置は絶対値である。 AM_SEEKING_RelativePositioning 指定した位置は以前の値からの相対値である。 AM_SEEKING_IncrementalPositioning 停止位置 (pStop) は現在位置 (pCurrent) からの相対値である。 修飾フラグ AM_SEEKING_SeekToKeyFrame 最も近いキーフレームをシークする。これは高速だが、精度は落ちる。 AM_SEEKING_ReturnTime 等しい基準タイムを返す。 AM_SEEKING_Segment セグメント シークを使用する。 AM_SEEKING_NoFlush フラッシュしない。 各パラメータに対して、1 つの位置フラグを使用する。1 つまたは複数の修飾子フラグを含めることもできる。
AM_SEEKING_ReturnTime フラグが指定されると、メソッドはその位置の値を基準タイムに変換し、pCurrent 変数または pStop 変数で返す。フレームのような別のタイムフォーマットを使っているときに、このフラグは有用である。
AM_SEEKING_Segment と AM_SEEKING_NoFlush フラグは、シームレス ループをサポートする。
- AM_SEEKING_Segment が存在する場合、ソースフィルタは停止位置に到達したときに、IPin::EndOfStream を呼び出す代わりに EC_END_OF_SEGMENT イベントを送る。アプリケーションはこのイベントを待って、もう 1 つのシーク コマンドを処理することができる。
- AM_SEEKING_NoFlush が存在する場合、グラフはシーク中にデータをフラッシュしない。このフラグは AM_SEEKING_Segment と共に使用する。
ループを実行するためには、グラフは GetCapabilities メソッドの AM_SEEKING_CanDoSegments を報告しなければならない。現在、この機能をサポートしているのは WAVE パーサー フィルタだけである。
再生レートを設定する。
構文
HRESULT SetRate( double dRate );
パラメータ
- dRate
- [in] 再生レート。ゼロであってはならない。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_INVALIDARG 指定されたレートは、0 または負の値であった (「注意」を参照)。 E_NOTIMPL 実装されていない。 E_POINTER NULL ポインタ引数。 VFW_E_UNSUPPORTED_AUDIO オーディオ デバイスあるいはフィルタがこのレートをサポートしていない。
注意
再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。オーディオ ストリームについては、レートを変えるとピッチも変わる。
マイナス値は逆再生を示す。大部分のフィルタは逆再生をサポートしない、代わりに dRate パラメータがマイナスだとエラーコードを返す。
アプリケーションがこのメソッドをフィルタ グラフ マネージャで呼び出すと、フィルタ グラフ マネージャは以下の事を行う :
- GetCurrentPosition メソッドを呼び出す。この呼び出しによってフィルタ グラフ マネージャが計算した現在位置を返す。
- (グラフがポーズあるいは実行中なら) フィルタ グラフを停止する。
- 現在位置を開始タイムとして、SetPositions メソッドを呼び出す。これはストリームタイムをゼロにリセットする結果となる。
- 新しいレートで、フィルタの SetRate メソッドを呼び出す。
- ポーズあるいは実行中だったなら、フィルタグラフを再開する。
ステップ 4 でエラーが起きると、フィルタ グラフ マネージャは以前のレートを再び使おうとする。
フィルタは以下のようにレート変更に対応すべきだ :
パーサー フィルタとソース フィルタ : タイム スタンプを発生させているフィルタは SetRate 呼び出しに対応しなければならない。通常これは AVI スプリッタ のようなパーサー フィルタであるが、ソース フィルタの場合もある。シークやレート変更の後、フィルタは IPin::NewSegment メソッドを新しい設定で呼び出すべきである。レート変更の後、そのタイム スタンプをそれに従って調整すべきだ。レート変更はシークに優先するので、タイム スタンプはゼロから再スタートとなる、従ってフィルタはそのレートで割った新しいタイム スタンプを計算することができる。
デコーダ フィルタ : デコーダは SetRate 呼び出しに対して、それらをアップストリームに渡す以外のことをすべきではない。そうではなく、デコーダはアップストリーム パーサーが出す NewSegment 呼び出しに対応すべきである。デコーダ フィルタが新しいセグメント情報を受け取るとき、そのフィルタはその値を保存して、NewSegment 呼び出しダウンストリームに渡す。いくつかのデコーダはその入力を補間することによって追加タイム スタンプを生成する必要がある、そうするときアカウント内にレート変更を渡すべきである。
レンダラ : ビデオ レンダラは通常レート変更を無視できる、なぜなら入ってくるフレームは既に正しいタイム スタンプを持っているからだ。オーディオ レンダラはその再生レートを変更しなければならない、なぜならオーディオ デコーダは通常レート変更変換をしないからである。
タイム フォーマットを設定する。
構文
HRESULT SetTimeFormat( const GUID *pFormat );
パラメータ
- pFormat
- [in] タイム フォーマット GUID へのポインタ。
戻り値
HRESULT 値を返す。次の可能な値がある。
S_OK 成功。 E_INVALIDARG 不適切な引数。 E_NOTIMPL メソッドはサポートされていない。 E_POINTER NULL ポインタ引数。 VFW_E_WRONG_STATE フィルタ グラフが停止していない。
注意
このメソッドは、GetPositions や SetPositions など、ほかの IMediaSeeking メソッドを使ってタイムの単位を指定する。どのフォーマットがサポートされているかを確認するには、IsFormatSupported メソッドを呼び出すこと。現在のタイム フォーマットを取得するには、GetTimeFormat メソッドを呼び出し、優先タイム フォーマットを取得するには、QueryPreferredFormat メソッドを呼び出すこと。
フィルタ グラフには、一度に 1 つのタイム フォーマットしか設定できない。