Platform SDK: DirectX

IDirectSoundBuffer::Play

IDirectSoundBuffer::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
ハードウェア バッファのみでボイスを再生する。ハードウェアに利用可能なボイスがなく、ボイス管理フラグも設定されていない場合、IDirectSoundBuffer::Play に対する呼び出しは失敗する。このフラグを DSBPLAY_LOCSOFTWARE と組み合わせることはできない。
DSBPLAY_LOCSOFTWARE
ソフトウェア バッファのみでボイスを再生する。このフラグを DSBPLAY_LOCHARDWARE やボイス管理フラグのどれかと組み合わせることはできない。
ボイス管理フラグ
ボイス管理フラグは、バッファが DSBCAPS_LOCDEFER フラグで作成されたときにのみ有効であり、ハードウェアで再生するサウンドに使われる。これらのフラグは、使用中のハードウェア リソースに現在のサウンドが受け渡されるようにする。DSBCAPS_LOCDEFER フラグで作成されたバッファのみが、早めに終了される候補となる。「注意」を参照すること。
DSBPLAY_TERMINATEBY_TIME
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、再生の残り時間が最も少ないバッファである。
DSBPLAY_TERMINATEBY_DISTANCE
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、DSBCAPS_MUTE3DATMAXDISTANCE フラグがセットされ、最大距離を超えているものの中から選択される。このようなバッファがない場合、メソッドは失敗する。
DSBPLAY_TERMINATEBY_PRIORITY
ハードウェアに利用可能なボイスがない場合は、新しいバッファ用の空きを確保するために現在再生中のバッファを停止する。早めに終了されるバッファは、IDirectSoundBuffer::Play に渡される dwPriority パラメータで設定された優先度が最も低いバッファである。

戻り値

成功すれば DS_OK、失敗すれば次のエラー値のいずれかを返す。

DSERR_BUFFERLOST
DSERR_HWUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

IDirectSound::SetCooperativeLevel を呼び出していない場合でも、メソッドは DS_OK を返す。ただし、協調レベルが設定されるまでサウンドは出力されない。

このメソッドが指定したバッファが既に再生中だった場合、メソッドの呼び出しは成功し、バッファは再生を続ける。ただし最新の呼び出しで定義したフラグは、以前の呼び出しで定義されていたフラグを置き換える。

このメソッドがプライマリ バッファで呼び出された場合は、サウンド デバイスでバッファの再生が開始される。アプリケーションが 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 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 新しいサウンドをソフトウェアで再生する。

動作環境

  Windows NT/2000 : Service Pack 3 を適用した Windows NT バージョン 4.0 以降が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dsound.h で宣言。
  インポート ライブラリ : dsound.lib を使用。

参照

IDirectSoundBufferIDirectSound::SetCooperativeLevel