IMediaSeeking

IMediaSeeking インターフェイスは、ストリーム内の位置へのシーク、および再生レートの設定を行うためのメソッドを提供します。

GetCapabilities メソッドは、ストリームのすべてのシーク機能を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

このメソッドは、ストリームのすべてのシーク機能に関する情報を返します。pCapabilities を調べるには、関心のある各 AM_SEEKING_SEEKING_CAPABILITIES 値に対して個別にビット単位の AND 演算を実行します。

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

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

CheckCapabilities メソッドは、ストリームが指定したシーク機能を備えているかどうかを問い合わせます。

HRESULT 値を返します。とりうる値には次のものがあります。

特定のいくつかの機能だけに関心がある場合は、ストリームのすべてのシーク機能を調べる IMediaSeeking::GetCapabilities を呼び出すよりも、このメソッドを呼び出す方が効率的です。

このメソッドを呼び出すには、DWORD 変数を宣言し、テストしたい AM_SEEKING_SEEKING_CAPABILITIES フラグをビット単位の OR で結合した値を設定します。この値のアドレスを 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_CanSeekForwards)
    {
        // ストリームは前方へシークできる。
    }
    if (dwCaps & AM_SEEKING_CanSeekBackwards)
    {
        // ストリームは後方へシークできる。
    }
}

IsFormatSupported メソッドは、指定した時間形式がシーク操作でサポートされているかどうかを判定します。

HRESULT 値を返します。とりうる値には次のものがあります。

QueryPreferredFormat メソッドは、シークに推奨される時間形式を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

GetTimeFormat メソッドは、現在シーク操作に使用されている時間形式を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

IsUsingTimeFormat メソッドは、シーク操作が現在指定した時間形式を使用しているかどうかを判定します。

HRESULT 値を返します。とりうる値には次のものがあります。

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

SetTimeFormat メソッドは、以降のシーク操作に使用する時間形式を設定します。

HRESULT 値を返します。とりうる値には次のものがあります。

このメソッドは、IMediaSeeking::GetPositions や IMediaSeeking::SetPositions など、他の IMediaSeeking メソッドで使用される時間の単位を指定します。これらの他のメソッドを呼び出す際、時間値を表すパラメーターはすべて現在の時間形式の単位で与えられます。

既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。その他の時間形式には、フレーム、サンプル、バイトがあります。特定の形式がサポートされているかどうかを判定するには、IMediaSeeking::IsFormatSupported メソッドを呼び出します。ある形式がサポートされている場合、SetTimeFormat を呼び出すことでその形式に切り替えることができます。同時にアクティブにできる時間形式は 1 つだけです。

GetDuration メソッドは、ストリームの再生時間 (長さ) を取得します。

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは、通常の再生速度でのストリームの再生時間を取得します。再生レートを変更しても再生時間は変わりません。

再生時間は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。

ソースの形式によっては、再生時間が正確でない場合があります。たとえば、ソースに可変ビットレート (VBR) ストリームが含まれている場合、このメソッドは推定された再生時間を返すことがあります。

GetStopPosition メソッドは、ストリームの再生時間を基準として、再生が停止する時刻を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

再生レートは、このメソッドが返す値に影響しません。

返される値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。

GetCurrentPosition メソッドは、ストリーム全体の再生時間を基準として、現在位置を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

このメソッドは、再生が到達した現在位置を返します。この値には、再生レートと開始時刻に対する調整が含まれます。たとえば、開始時刻が 5 秒、再生レートが 2.0 で、グラフを 4 秒間実行した場合、現在位置は 5 + (4 x 2.0) = 13.0 秒になります。

返される値は現在の時間形式の単位で表されます。現在の時間形式を確認するには、GetTimeFormat メソッドを呼び出します。

グラフが一時停止または停止している場合、現在位置は再生が再開される時点を表します。

Filter Graph Manager は、現在のストリーム時刻から位置を計算します。グラフ内のフィルターに問い合わせは行いません。ファイル再生の場合、再生はストリーム時刻に同期されるため、正確な結果が得られます。ファイル書き込みの場合、結果は正確ではありません。ファイル書き込みグラフで現在位置を取得するには、マルチプレクサーフィルターに問い合わせます。(ただし、ライブキャプチャでは位置は意味を持ちません。)

返される値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。

ConvertTimeFormat メソッドは、ある時間形式から別の時間形式へ変換します。

HRESULT 値を返します。とりうる値には次のものがあります。

SetPositions メソッドは、現在位置と停止位置を設定します。

HRESULT 値を返します。とりうる値には次のものがあります。

dwCurrentFlags パラメーターと dwStopFlags パラメーターは、シークの種類を定義します。次のフラグが定義されています。

各パラメーターには、位置指定フラグを 1 つ使用します。必要に応じて、1 つ以上の修飾フラグを含めることができます。

AM_SEEKING_ReturnTime フラグを指定すると、メソッドは位置の値をリファレンスタイムに変換し、それを pCurrent または pStop 変数に返します。このフラグは、フレームなど別の時間形式を使用している場合に便利です。

AM_SEEKING_Segment フラグと AM_SEEKING_NoFlush フラグは、シームレスなループ再生をサポートします。

• AM_SEEKING_Segment フラグが指定されている場合、ソースフィルターは停止位置に到達したときに IPin::EndOfStream を呼び出す代わりに EC_END_OF_SEGMENT イベントを送信します。アプリケーションはこのイベントを待機し、その後別のシークコマンドを発行できます。
• AM_SEEKING_NoFlush フラグが指定されている場合、グラフはシーク中にデータをフラッシュしません。このフラグは AM_SEEKING_Segment と併用します。

入力される pCurrent と pStop の値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。AM_SEEKING_ReturnTime フラグが指定されている場合、メソッドは出力される値を REFERENCE_TIME 単位に変換します。

フィルター開発者向け

DWORD dwCurrentPos = dwCurrentFlags & AM_SEEKING_PositioningBitsMask
if (dwCurrentPos == AM_SEEKING_AbsolutePositioning)
{ 
    // 新しい位置を pCurrent に設定する。
    m_rtStart = *pCurrent;
}
else if (dwCurrentPos == AM_SEEKING_RelativePositioning)
{
    // 現在位置を pCurrent の分だけ加算する。
    m_rtStart += *pCurrent;
}

GetPositions メソッドは、ストリーム全体の再生時間を基準として、現在位置と停止位置を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

現在位置と停止位置はどちらも元のストリームを基準としており、再生レートには依存しません。

返される値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。

GetAvailable メソッドは、シークが効率的に行える時間の範囲を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

このメソッドは主に、ネットワーク経由で送信されるストリームなど、過度な遅延が発生する可能性のあるメディアストリームでのシークを対象としています。返される値は、すでに到着していて容易にシークできるキャッシュ済みデータを示します。これらの返されたパラメーターを超える値へシークすると、データの到着を待つ間、アプリケーションに遅延が発生すると想定されます。

すべての時間値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。

SetRate メソッドは、再生レートを設定します。

HRESULT 値を返します。とりうる値には次のものがあります。

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

負の値は逆方向再生を表します。ほとんどのフィルターは逆方向再生をサポートしておらず、dRate パラメーターが負の場合はエラーコードを返します。

アプリケーションが Filter Graph Manager に対してこのメソッドを呼び出すと、Filter Graph Manager は次の処理を行います。

1. IMediaSeeking::GetCurrentPosition メソッドを呼び出します。この呼び出しは、Filter Graph Manager が計算した現在位置を返します。
2. フィルターグラフを停止します (グラフが一時停止中または実行中の場合)。
3. 現在位置を開始時刻として、フィルターに対して IMediaSeeking::SetPositions メソッドを呼び出します。これにより、ストリーム時刻がゼロにリセットされます。
4. 新しいレートを指定して、フィルターに対して SetRate メソッドを呼び出します。
5. フィルターグラフが一時停止中または実行中だった場合は、再開します。

フィルターは、レート変更に対して次のように応答する必要があります。

パーサーフィルターおよびソースフィルター: タイムスタンプを生成するフィルターが SetRate 呼び出しに応答します。これは通常、AVI Splitter Filter などのパーサーフィルターですが、ソースフィルターの場合もあります。シークまたはレート変更が行われた後、フィルターは新しい設定で IPin::NewSegment メソッドを呼び出す必要があります。レート変更後は、それに応じてタイムスタンプを調整する必要があります。レート変更の前にはシークが行われ、タイムスタンプはゼロから再開されるため、フィルターは単純にレートで除算することで新しいタイムスタンプを計算できます。

デコーダーフィルター: デコーダーは、SetRate 呼び出しに対して上流へ渡す以外の処理を行うべきではありません。代わりに、上流のパーサーが発行する NewSegment 呼び出しに応答する必要があります。デコーダーフィルターは、新しいセグメント情報を受け取ると、その値を保存し、NewSegment 呼び出しを下流へ渡す必要があります。一部のデコーダーは、入力を補間して追加のタイムスタンプを生成する必要があります。その際にはレート変更を考慮する必要があります。

レンダラー: ビデオレンダラーは通常、入力されるフレームがすでに正しいタイムスタンプを持っているため、レート変更を無視できます。オーディオレンダラーは再生レートを変更する必要があります。オーディオデコーダーは通常、レート変更に伴う変換を行わないためです。

GetRate メソッドは、再生レートを取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

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

GetPreroll メソッドは、開始位置より前にキューへ入れられるデータの量を取得します。

HRESULT 値を返します。とりうる値には次のものがあります。

プリロールとは、テーププレーヤーなどの非ランダムアクセスデバイスが再生を開始すべき、開始位置より前の時間のことです。

返される値は現在の時間形式で表されます。既定の時間形式は REFERENCE_TIME 単位 (100 ナノ秒) です。時間形式を変更するには、IMediaSeeking::SetTimeFormat メソッドを使用します。