IDirectSoundBuffer8::Play

  • [アーティクル]

Playメソッドは、サウンド バッファーを再生カーソルの位置から再生します。

HRESULT 
Play(
  DWORD dwReserved1,
  DWORD dwPriority,
  DWORD dwFlags
);

パラメータ

  • dwReserved1
    予約済みです。0 を指定します。
  • dwPriority
    サウンドの優先度です。この優先度は、ハードウェア ミキシング リソースを割り当てるときにボイス管理が使用します。最も低い優先度は 0、最も高い優先度は 0xFFFFFFFF です。バッファーが DSBCAPS_LOCDEFER フラグを指定して作成されていない場合、この値は 0 でなければなりません。
  • dwFlags
    バッファーの再生方法を指定するフラグです。次のフラグが定義されています。 ループ フラグ ボイス割り当てフラグ ボイス割り当てフラグは、DSBCAPS_LOCDEFER フラグを指定して作成されたバッファーのみに有効です。以下のフラグのいずれかを使用すると、ハードウェアまたはソフトウェアでサウンド処理を強制的に行うことができます。DBSPLAY_LOCHARDWARE と DBSPLAY_LOCSOFTWARE のどちらも設定されていない場合は、メソッドが呼び出されたときのリソースの利用可能性に応じて、ソフトウェアまたはハードウェアでサウンドが再生されます。「解説」を参照してください。 ボイス管理フラグ ボイス管理フラグは、DSBCAPS_LOCDEFER フラグを指定して作成されたバッファーのみに有効であり、ハードウェアで再生するサウンドに使用されます。これらのフラグを使用すると、既に使用中のハードウェア リソースを現在のサウンドに渡すことができます。DSBCAPS_LOCDEFER フラグを指定して作成されたバッファーのみが、早期終了の候補となります。「解説」を参照してください。

戻り値

成功した場合は、DS_OK を返します。失敗した場合は、次のいずれかのエラー値を返します。

リターン コード
DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

解説　

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 宣言

ライブラリ: Dsound3d.dll 内容

関連項目

IDirectSoundBuffer8