IDirectSoundBuffer8::Play
サウンド バッファを再生カーソルの位置から再生する。
構文
HRESULT Play(
DWORD
dwReserved1
,
DWORD
dwPriority
,
DWORD
dwFlags
);
パラメータ
dwReserved1
予約済み。0 でなければならない。
dwPriority
サウンドの優先度。この優先度は、ハードウェア ミキシング リソースを割り当てる際にボイス管理が使う。最も低い優先度は 0、最も高い優先度は 0xFFFFFFFF である。バッファが DSBCAPS_LOCDEFER フラグで作成されていない場合、この値は 0 でなければならない。
dwFlags
バッファの再生方法を指定するフラグ。次のフラグが定義されている。
ループ フラグ
値 | 説明 |
DSBPLAY_LOOPING | オーディオ バッファの最後に達すると、バッファの先頭から再生を再開する。明示的に停止するまで再生が続く。プライマリ バッファを再生するときは、このフラグを設定しなければならない。 |
ボイス割り当てフラグ
ボイス割り当てフラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときのみ有効である。以下のフラグのいずれかを使えば、サウンド処理をハードウェアまたはソフトウェアで強制的に行うことができる。DBSPLAY_LOCHARDWARE と DBSPLAY_LOCSOFTWARE のどちらも設定されていない場合は、メソッドが呼び出されたときのリソースの利用可能性に基づいて、サウンドはソフトウェアまたはハードウェアで再生される。「注意」を参照すること。
値 | 説明 |
DSBPLAY_LOCHARDWARE | ハードウェア バッファのみでこのボイスを再生する。ハードウェアに利用可能なボイスがなく、ボイス管理フラグも設定されていない場合は、IDirectSoundBuffer8::Play に対する呼び出しは失敗する。このフラグを DSBPLAY_LOCSOFTWARE と組み合わせることはできない。 |
DSBPLAY_LOCSOFTWARE | ソフトウェア バッファのみでこのボイスを再生する。このフラグを DSBPLAY_LOCHARDWARE やボイス管理フラグのどれかと組み合わせることはできない。 |
ボイス管理フラグ
ボイス管理フラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときにのみ有効であり、ハードウェアで再生するサウンドに使う。これらのフラグを使うと、既に使用中のハードウェア リソースを現在のサウンドに渡すことができる。DSBCAPS_LOCDEFER フラグで作成されたバッファのみが、早めに終了される候補となる。「注意」を参照すること。
値 | 説明 |
DSBPLAY_TERMINATEBY_TIME | ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために、現在再生中の非ループ バッファが停止する。早めに終了されるバッファは、再生の残り時間が最も少ないバッファである。 |
DSBPLAY_TERMINATEBY_DISTANCE | ハードウェアに利用可能なボイスがない場合、新しいバッファに空きを確保するために、現在再生中のバッファが停止する。早めに終了されるバッファは、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定され、最大距離を超えているものの中から選択される。このようなバッファがない場合、メソッドは失敗する。 |
DSBPLAY_TERMINATEBY_PRIORITY | ハードウェアに利用可能なボイスがない場合、新しいバッファに空きを確保するために、現在再生中のバッファが停止する。早めに終了されるバッファは、バッファに対する IDirectSoundBuffer8::Play に渡された dwPriority パラメータで設定された優先度が最も低いバッファである。 |
戻り値
成功した場合は DS_OK を返す。
失敗した場合は、次のいずれかのエラー値を返す。
リターン コード |
DSERR_BUFFERLOST |
DSERR_INVALIDCALL |
DSERR_INVALIDPARAM |
DSERR_PRIOLEVELNEEDED |
注意
IDirectSound8::SetCooperativeLevel が呼び出されていない場合でも、メソッドは DS_OK を返す。ただし、協調レベルが設定されるまでサウンドは出力されない。
アプリケーションがマルチスレッド化されている場合、バッファを演奏するスレッドは、バッファの再生期間を通して存在していなければならない。WDM ドライバで作成されたバッファでは、スレッドが終了すると再生を停止する。
メソッドで指定されたバッファが既に再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし、最新の呼び出しで定義されたフラグは、以前の呼び出しで定義されていたフラグを置き換える。
このメソッドがプライマリ バッファで呼び出された場合は、サウンド デバイスでバッファの再生が開始される。アプリケーションで DSSCL_WRITEPRIMARY の協調レベルが設定されている場合は、アプリケーションによりプライマリ バッファに置かれた任意のオーディオ データがサウンド デバイスに送られる。他の協調レベルの場合は、セカンダリ バッファが再生されていないと、プライマリ バッファは無音となる。プライマリ バッファは、DSBPLAY_LOOPING フラグを設定して再生しなければならない。
DSBCAPS_LOCDEFER フラグを指定して作成されていないバッファに対してボイス割り当てフラグまたはボイス管理フラグを指定してこのメソッドを呼び出すと、この呼び出しは失敗し、DSERR_INVALIDPARAM が返される。
DSBPLAY_TERMINATEBY_TIME と DSBPLAY_TERMINATEBY_DISTANCE を組み合わせることはできないが、このどちらかと DSBPLAY_TERMINATEBY_PRIORITY を組み合わせることができる。この場合、DSBPLAY_TERMINATEBY_TIME フラグまたは DSBPLAY_TERMINATEBY_DISTANCE フラグは、優先度が等しい場合にどのバッファを終了するかを決定するために使う。
次の表は、ハードウェア ボイスの空きを利用できない場合に、ボイス割り当てフラグとボイス管理フラグの組み合わせによって決まるメソッドの動作を示している。
DSBPLAY_LOCHARDWARE を指定 | DSBPLAY_LOCHARDWARE も DSBPLAY_LOCSOFTWARE も指定しない | DSBPLAY_LOCSOFTWARE を指定 | |
DSBPLAY_TERMINATEBY_TIME | 再生の残り時間が最も少ないサウンドを終了し、解放したボイスで新しいサウンドを再生する。 | 再生の残り時間が最も少ないサウンドを終了し、解放したボイスで新しいサウンドを再生する。 | 新しいサウンドをソフトウェアで再生する。 |
DSBPLAY_TERMINATEBY_DISTANCE | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。 |
DSBPLAY_TERMINATEBY_PRIORITY | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。 |
要件
** ヘッダー:**dsound.h で宣言。
参照