Microsoft DirectX 8.0

IMediaSeeking インターフェイス

ストリーム内の位置にシークするメソッドと、再生レートを設定するメソッドが含まれる。

フィルタ グラフ マネージャは、個々のフィルタと同じように、このインターフェイスを公開する。アプリケーションはフィルタからではなく、フィルタ グラフ マネージャからこのインターフェイスを取得する必要がある。フィルタ グラフ マネージャは、メソッドをすべてのレンダリング フィルタに割り当てる。レンダリング フィルタは、その呼び出しをソース フィルタへのアップストリームに送る。すべてのストリームは、イベントのこのシーケンスによって同期される。

配布されたいずれかの呼び出しがエラーを返した場合、フィルタ グラフ マネージャは、配布された呼び出しの一部が成功した場合でも、最初に受け取ったエラー値を返す。この例外には、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開始位置の前にキューに入っているデータの量を取得する。

IMediaSeeking::CheckCapabilities

IMediaSeeking インターフェイス

指定したシーク能力をストリームが持っているかどうかを照会する。

構文

HRESULT CheckCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
[in, out] AM_SEEKING_SEEKING_CAPABILITIES 属性の 1 つまたは複数のビットごとの組み合わせへのポインタ。メソッドの戻り値は、どの属性が利用可能であるかを示す。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSEpCapabilities のすべての能力を持ってはいない。
S_OKpCapabilities のすべての能力がある。
E_FAILpCapabilities の能力がまったくない。
E_POINTERNULL ポインタ引数。

注意

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)
        // ストリームは逆方向へのシークができる。
}

IMediaSeeking::ConvertTimeFormat

IMediaSeeking インターフェイス

あるタイム フォーマットをほかのフォーマットに変換する。

構文

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_POINTERNULL ポインタ引数。

IMediaSeeking::GetAvailable

IMediaSeeking インターフェイス

シークが有効なタイムの範囲を取得する。

構文

HRESULT GetAvailable(
    LONGLONG *pEarliest,
    LONGLONG *pLatest
);

パラメータ

pEarliest
[out] シークが有効な、最も早いタイムを受け取る変数へのポインタ。
pLatest
[out] シークが有効な、最も遅いタイムを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

このメソッドは、主にネットワークを越えて送られてくるような、遅延の大きなメディア ストリームでのシークを対象としている。戻り値は、容易にシーク可能な、既に到着済みのキャッシュ データを表す。返されたパラメータを超えた値をシークすると、アプリケーションがデータの到着を待つ間、遅延が発生することが想定されている。

IMediaSeeking::GetCapabilities

IMediaSeeking インターフェイス

ストリームのすべてのシーク能力を取得する。

構文

HRESULT GetCapabilities(
    DWORD *pCapabilities
);

パラメータ

pCapabilities
[out] AM_SEEKING_SEEKING_CAPABILITIES フラグのビットごとの組み合わせを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_POINTERNULL ポインタ引数。

注意

このメソッドは、ストリームのすべてのシーク能力に関する情報を返す。必要な AM_SEEKING_SEEKING_CAPABILITIES 値について、ビットごとの AND 操作を行い、pCapabilities を調べること。

DWORD dwCaps = 0;
pMediaSeeking->GetCapabilities(&dwCaps);

if (dwCaps & AM_SEEKING_CanGetCurrentPos) 
{
    // ストリームでは現在位置へのシークができる。
}
if (dwCaps & AM_SEEKING_CanPlayBackwards) 
{
    // ストリームでは再生逆方向へのシークができる。
}

IMediaSeeking::GetCurrentPosition

IMediaSeeking インターフェイス

ストリームの合計時間幅に対する現在の位置を取得する。

構文

HRESULT GetCurrentPosition(
    LONGLONG *pCurrent
);

パラメータ

pCurrent
[out] 現在位置を取得する変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

このメソッドは、再生が到達した現在位置を返す。この値では、再生レートと開始タイムは無視される。たとえば、レートに 2.0 を設定し、開始タイムが 5 秒だとすると、グラフを 4 秒実行すると現在の位置は 9.0 秒となる (5 + 4 × 2.0)。戻り値は、現在のタイム フォーマットの単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

グラフがポーズまたは停止されている場合、現在位置は再生が再開されるポイントとなる。

フィルタ グラフ マネージャは、現在のストリーム タイムから位置を計算するので、グラフのフィルタに照会することはない。ファイルの再生では、これによって再生がストリーム タイムに同期されるため、正確な結果が得られる。ファイルの書き込みでは、結果は正確にはならない。ファイルを書き込むグラフで現在の位置を取得するには、マルチプレクサ フィルタに照会すること。ただし、ライブ キャプチャでは、位置は適切なものとはならない。

IMediaSeeking::GetDuration

IMediaSeeking インターフェイス

ストリームの時間幅を取得する。

構文

HRESULT GetDuration(
    LONGLONG *pDuration
);

パラメータ

pDuration
[out] 時間幅を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

このメソッドは、通常、再生速度での時間幅を取得する。再生レートはこの時間幅には影響を与えない。戻り値は現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetPositions

IMediaSeeking インターフェイス

ストリームの合計時間幅に対する、現在の位置と停止位置を取得する。

構文

HRESULT GetPositions(
    LONGLONG *pCurrent,
    LONGLONG *pStop
);

パラメータ

pCurrent
[out] 現在位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。
pStop
[out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

現在位置と停止位置は、両方とも元のストリームに対する値であり、再生レートには依存しない。

戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetPreroll

IMediaSeeking インターフェイス

開始位置の前にキューに入っているデータの量を取得する。

構文

HRESULT GetPreroll(
    LONGLONG *pllPreroll
);

パラメータ

pllPreroll
[out] プリロール タイムを受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

プリロールは、テープ プレーヤーのような非ランダム アクセス デバイスで、ローリングが開始される開始位置より前のタイムである。

IMediaSeeking::GetRate

IMediaSeeking インターフェイス

再生レートを取得する。

構文

HRESULT GetRate(
    double *dRate
);

パラメータ

dRate
[out] 再生レートを受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。

IMediaSeeking::GetStopPosition

IMediaSeeking インターフェイス

ストリームの時間幅に対して、再生が停止するタイムを取得する。

構文

HRESULT GetStopPosition(
    LONGLONG *pStop
);

パラメータ

pStop
[out] 停止位置を受け取る変数へのポインタ (現在のタイム フォーマットの単位)。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。

注意

再生レートは、このメソッドによって返る値に影響を与えない。戻り値は、現在のタイム フォーマット単位で表される。現在のタイム フォーマットを確認するには、GetTimeFormat メソッドを呼び出すこと。

IMediaSeeking::GetTimeFormat

IMediaSeeking インターフェイス

現在のタイム フォーマットを取得する。

構文

HRESULT GetTimeFormat(
    GUID *pFormat
);

パラメータ

pFormat
[out] タイム フォーマット GUID を受け取る変数へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_POINTERNULL ポインタ引数。

IMediaSeeking::IsFormatSupported

IMediaSeeking インターフェイス

指定したタイム フォーマットをストリームがサポートしているかどうかを確認する。

構文

HRESULT IsFormatSupported(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSEフォーマットはサポートされていない。
S_OKフォーマットはサポートされている。
E_NOTIMPL実装されていない。
E_POINTERNULL ポインタ引数。

IMediaSeeking::IsUsingTimeFormat

IMediaSeeking インターフェイス

指定したタイム フォーマットが現在使用中のフォーマットかどうかを確認する。

構文

HRESULT IsUsingTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_FALSE指定したフォーマットは現在のフォーマットではない。
S_OK指定したフォーマットは現在のフォーマットである。
E_NOTIMPL実装されていない。
E_POINTERNULL ポインタ引数。

注意

このメソッドは GUID をコピーする必要がないため、IMediaSeeking::GetTimeFormat メソッドよりも効率的である。

IMediaSeeking::QueryPreferredFormat

IMediaSeeking インターフェイス

ストリームの優先タイム フォーマットを取得する。

構文

HRESULT QueryPreferredFormat(
    GUID *pFormat
);

パラメータ

pFormat
[out] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_NOTIMPL実装されていない。
E_POINTERNULL ポインタ引数。

注意

返されたフォーマットが不十分な場合は、IsFormatSupported メソッドを呼び出して、ほかにサポートされているタイム フォーマットを照会すること。

IMediaSeeking::SetPositions

IMediaSeeking インターフェイス

現在の位置と停止位置を設定する。

構文

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_POINTERNULL ポインタ引数。

注意

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 フラグは、シームレス ループをサポートする。

ループを実行するためには、グラフは GetCapabilities メソッドの AM_SEEKING_CanDoSegments を報告しなければならない。現在、この機能をサポートしているのは WAVE パーサー フィルタだけである。

IMediaSeeking::SetRate

IMediaSeeking インターフェイス

再生レートを設定する。

構文

HRESULT SetRate(
    double dRate
);

パラメータ

dRate
[in] 再生レート。ゼロであってはならない。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_INVALIDARG指定されたレートは、0 または負の値であった (「注意」を参照)。
E_NOTIMPL実装されていない。
E_POINTERNULL ポインタ引数。
VFW_E_UNSUPPORTED_AUDIOオーディオ デバイスあるいはフィルタがこのレートをサポートしていない。

注意

再生レートは、通常、速度との比率で表される。したがって、1.0 は通常の再生速度、0.5 は半分の速度、2.0 は 2 倍の速度を示す。オーディオ ストリームについては、レートを変えるとピッチも変わる。

マイナス値は逆再生を示す。大部分のフィルタは逆再生をサポートしない、代わりに dRate パラメータがマイナスだとエラーコードを返す。

アプリケーションがこのメソッドをフィルタ グラフ マネージャで呼び出すと、フィルタ グラフ マネージャは以下の事を行う :

  1. GetCurrentPosition メソッドを呼び出す。この呼び出しによってフィルタ グラフ マネージャが計算した現在位置を返す。
  2. (グラフがポーズあるいは実行中なら) フィルタ グラフを停止する。
  3. 現在位置を開始タイムとして、SetPositions メソッドを呼び出す。これはストリームタイムをゼロにリセットする結果となる。
  4. 新しいレートで、フィルタの SetRate メソッドを呼び出す。
  5. ポーズあるいは実行中だったなら、フィルタグラフを再開する。

ステップ 4 でエラーが起きると、フィルタ グラフ マネージャは以前のレートを再び使おうとする。

フィルタは以下のようにレート変更に対応すべきだ :

パーサー フィルタとソース フィルタ : タイム スタンプを発生させているフィルタは SetRate 呼び出しに対応しなければならない。通常これは AVI スプリッタ のようなパーサー フィルタであるが、ソース フィルタの場合もある。シークやレート変更の後、フィルタは IPin::NewSegment メソッドを新しい設定で呼び出すべきである。レート変更の後、そのタイム スタンプをそれに従って調整すべきだ。レート変更はシークに優先するので、タイム スタンプはゼロから再スタートとなる、従ってフィルタはそのレートで割った新しいタイム スタンプを計算することができる。

デコーダ フィルタ : デコーダは SetRate 呼び出しに対して、それらをアップストリームに渡す以外のことをすべきではない。そうではなく、デコーダはアップストリーム パーサーが出す NewSegment 呼び出しに対応すべきである。デコーダ フィルタが新しいセグメント情報を受け取るとき、そのフィルタはその値を保存して、NewSegment 呼び出しダウンストリームに渡す。いくつかのデコーダはその入力を補間することによって追加タイム スタンプを生成する必要がある、そうするときアカウント内にレート変更を渡すべきである。

レンダラ : ビデオ レンダラは通常レート変更を無視できる、なぜなら入ってくるフレームは既に正しいタイム スタンプを持っているからだ。オーディオ レンダラはその再生レートを変更しなければならない、なぜならオーディオ デコーダは通常レート変更変換をしないからである。

IMediaSeeking::SetTimeFormat

IMediaSeeking インターフェイス

タイム フォーマットを設定する。

構文

HRESULT SetTimeFormat(
    const GUID *pFormat
);

パラメータ

pFormat
[in] タイム フォーマット GUID へのポインタ。

戻り値

HRESULT 値を返す。次の可能な値がある。

S_OK成功。
E_INVALIDARG不適切な引数。
E_NOTIMPLメソッドはサポートされていない。
E_POINTERNULL ポインタ引数。
VFW_E_WRONG_STATEフィルタ グラフが停止していない。

注意

このメソッドは、GetPositionsSetPositions など、ほかの IMediaSeeking メソッドを使ってタイムの単位を指定する。どのフォーマットがサポートされているかを確認するには、IsFormatSupported メソッドを呼び出すこと。現在のタイム フォーマットを取得するには、GetTimeFormat メソッドを呼び出し、優先タイム フォーマットを取得するには、QueryPreferredFormat メソッドを呼び出すこと。

フィルタ グラフには、一度に 1 つのタイム フォーマットしか設定できない。