Microsoft DirectX 8.0 |
IStreamSample インターフェイスは、ストリーム サンプルの動作を制御するものである。サンプルを作成したメディア ストリームを取得し、サンプルの開始タイムと終了タイムを設定または取得し、サンプルの完了状態を確認し、サンプル自体に開発者が指定した関数を実行することができる。
新しいメディア タイプのメディア ストリームを実装するときには、このインターフェイスを実装する。このインターフェイスは、メディア ストリームが作成したサンプル オブジェクト上で公開される。
IMediaStream が作成したデータ サンプルまたはその派生インターフェイスを制御するには、このインターフェイスを使用する。
IUnknown メソッド 説明 QueryInterface サポートされているインターフェイスへのポインタを取得する。 AddRef 参照カウントをインクリメントする。 Release 参照カウントをデクリメントする。 IStreamSample メソッド 説明 GetMediaStream 現在のサンプルを作成したメディア ストリーム オブジェクトへのポインタを取得する。 GetSampleTimes 現在のサンプルの開始タイムと終了タイムを取得する。 SetSampleTimes 現在のサンプルの開始タイムと終了タイムを設定する。 Update 現在のサンプルを同期または非同期に更新する。 CompletionStatus 現在のサンプルに行われた最後の非同期更新の状態を取得する。更新が完了していない場合には強制終了できる。
現在のサンプルに行われた最後の非同期更新の状態を取得する。更新が完了していない場合には強制終了できる。
構文
HRESULT CompletionStatus(
DWORD dwFlags,
DWORD dwMilliseconds
);
パラメータ
- dwFlags
- [in] 更新を強制終了するかどうかを指定する値。この値は、以下のフラグを 1 つ以上組み合わせたものである。
COMPSTAT_NOUPDATEOK (0x01) サンプル更新が完了していない場合も含め、更新をできる限り早く強制終了する。サンプルが更新中で、COMPSTAT_WAIT フラグが設定されていない場合、メソッドは MS_S_PENDING を返す。サンプルが更新待ちの場合、メソッドはサンプルをキューから削除し、MS_S_NOTUPDATED を返す。 COMPSTAT_WAIT (0x02) サンプル更新の終了を待ったうえで、メソッドから戻る。 COMPSTAT_ABORT (0x04) サンプルが現在更新中の場合も含め、更新を強制終了する。この方法では、サンプル データの状態が不定になる。更新を確実にキャンセルするには、COMPSTAT_WAITFORCOMPLETION フラグと組み合わせる。 - dwMilliseconds
- [in] dwFlags パラメータが COMPSTAT_WAIT の場合、この値は更新完了を待つ待機時間 (ミリ秒単位) となる。サンプル更新が完了するまで待ってからメソッドが戻るようにするには、INFINITE を指定する。
戻り値
次のいずれかの値を返す。
E_ABORT 更新が中止された。 MS_S_ENDOFSTREAM ストリームの終端に達したため、サンプルが更新されなかった。 MS_S_NOUPDATE 更新が強制終了され、サンプルがストリームによって更新されなかった。 MS_S_PENDING 非同期更新が保留されている。 S_OK 成功。
現在のサンプルを作成したメディア ストリーム オブジェクトへのポインタを取得する。
構文
HRESULT GetMediaStream(
IMediaStream **ppMediaStream
);
パラメータ
- ppMediaStream
- [in] IMediaStream インターフェイスへのポインタのアドレス。このポインタに、現在のサンプルを作成したメディア ストリームのアドレスを受け取る。
戻り値
成功した場合は、S_OK を返す。ppMediaStream が無効な場合は、E_POINTER を返す。
注意
成功した場合、このメソッドは ppMediaStream で指定されたメディア ストリームの参照カウントをインクリメントする。
現在のサンプルの開始タイムと終了タイムを取得する。サンプルが更新中の場合、このメソッドは更新完了後の時間を返す。
構文
HRESULT GetSampleTimes(
STREAM_TIME *pStartTime,
STREAM_TIME *pEndTime,
STREAM_TIME *pCurrentTime
);
パラメータ
- pStartTime
- [out] サンプルの開始タイムが格納される STREAM_TIME 値へのポインタ。
- pEndTime
- [out] サンプルの終了タイムが格納される STREAM_TIME 値へのポインタ。
- pCurrentTime
- [out] メディア ストリームの現在のメディア タイムが格納される STREAM_TIME 値へのポインタ。
戻り値
成功した場合は、S_OK を返す。パラメータの 1 つが無効な場合は、E_POINTER を返す。
注意
ストリームにクロックがある場合、開始タイムと終了タイムはストリームの現在時間に対する相対時間となる。ストリームにクロックがない場合、開始タイムと終了タイムはメディアに対する相対時間であり、現在時間は 0 となる。
pCurrentTime パラメータを使用すると、メディア ストリームの現在時間を簡単に追跡できるため、IMultiMediaStream::GetTime を呼び出さないで済む。ただし、ストリームにクロックがない場合、GetTime は S_FALSE を返すが、このメソッドは S_OK を返す。pCurrentTime に割り当てられる値は、次のコードで生成される値と同じである。
pSample->GetMediaStream(&pMediaStream); pMediaStream->GetMultiMediaStream(&pMultiMediaStream); pMediaStream->Release(); pMultiMediaStream->GetTime(&pCurrentTime); pMultiMediaStream->Release();
現在のサンプルの開始タイムと終了タイムを設定する。このメソッドは、サンプルを更新する前に呼び出すことができる。
構文
HRESULT SetSampleTimes(
const STREAM_TIME *pStartTime,
const STREAM_TIME *pEndTime
);
パラメータ
- pStartTime
- [in] サンプルの新しい開始タイムが格納された STREAM_TIME 値へのポインタ。
- pEndTime
- [in] サンプルの新しい終了タイムが格納された STREAM_TIME 値へのポインタ。
戻り値
成功した場合は、S_OK を返す。パラメータの 1 つが NULL の場合は、E_POINTER を返す。
注意
ストリームにクロックがある場合、開始タイムと終了タイムはストリームの現在時間に対する相対で指定する。ストリームにクロックがない場合、開始タイムと終了タイムはメディアに対する相対で指定する。
このメソッドは、書き込み可能なストリームにのみ適用される。
現在のサンプルを同期または非同期に更新する。
構文
HRESULT Update(
DWORD dwFlags,
HANDLE hEvent,
PAPCFUNC pfnAPC,
DWORD dwAPCData
);
パラメータ
- dwFlags
- [in] 更新が同期か非同期かを指定するフラグ。SSUPDATE_ASYNC フラグは、非同期の更新を示し、hEvent と pfnAPC の両方が NULL の場合に設定することができる。IStreamSample::CompletionStatus メソッドを呼び出すまでサンプルを連続的に更新するには、SSUPDATE_CONTINUOUS を指定する。
- hEvent
- [in] 更新完了時にこのメソッドが発行するイベントへのハンドル。
- pfnAPC
- [in] 更新完了時にこのメソッドが呼び出す Win32 非同期プロシージャ呼び出し (APC) 関数へのポインタ。
- dwAPCData
- [in] pfnAPC パラメータで指定された関数にこのメソッドが渡す値。
戻り値
次のいずれかの値を返す。
E_ABORT 更新が中止された。 E_INVALIDARG パラメータの 1 つが無効。 E_POINTER パラメータの 1 つが無効。 MS_E_BUSY このサンプルには既に保留中の更新がある。 MS_S_ENDOFSTREAM ストリーム終端に達した。サンプルは更新されない。 MS_S_PENDING 非同期更新が保留されている。 S_OK 成功。
注意
このメソッドを使用すると、サンプルの同期更新または非同期更新を実行できる。hEvent と pfnAPC の両方が NULL の場合、SSUPDATE_ASYNC フラグと SSUPDATE_CONTINUOUS フラグのどちらかを指定しない限り、更新は同期となる。同期更新から戻ったときには、関数の結果に I/O の完了状態が格納されている。
hEvent と pfnAPC の両方に値を指定することはできない。指定した場合、メソッドは失敗する。
非同期更新は、更新から戻る前に完了する可能性がある。この場合、戻り値は S_OK になる。イベントを指定した場合、更新から S_OK が返されると、このメソッドは終了時にイベントを設定する。APC 関数を指定した場合、更新から S_OK が返されたときには、APC がキューに入れられることも、関数が呼び出されることもない。
戻る前に完了しない非同期更新は、値 MS_S_PENDING を返す。
アプリケーションが複数のストリームを作成する場合、それぞれのストリームで非同期更新を実行しなければならない。WaitForMultipleObjects を呼び出し、それぞれのストリームの更新が完了するのを待ってから、次の更新を行う。このようにしないと、アプリケーションがブロックする可能性がある。