Microsoft DirectX 8.0 (C++)

IDirectSoundBuffer8::AcquireResources

DSBUFFERDESC 構造体の DSBCAPS_LOCDEFER フラグを使って作成したバッファにリソースを割り当てる。

HRESULT AcquireResources(
  DWORD dwFlags,
  DWORD dwEffectsCount,
  LPDWORD pdwResultCodes
);

パラメータ

dwFlags
DSBCAPS_LOCDEFER フラグを使って作成したバッファにリソースを割り当てる方法を指定するフラグ。値のリストについては、IDirectSoundBuffer8::Play のボイス管理フラグおよびボイス割り当てフラグを参照すること。
dwEffectsCount
pdwResultFlags 配列の要素の数を指定する値。pdwResultCodes が NULL の場合は 0 を指定する。
pdwResultCodes
DWORD 変数の配列のアドレス。この配列は、バッファに関連付けられたエフェクトに関する情報を受け取る。この配列には、IDirectSoundBuffer8::SetFX によってバッファに割り当てられたエフェクトそれぞれに対して、1 つの要素が含まれなければならない。各エフェクトに対して、次のいずれかの値が返される。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_PRESENT
エフェクトは利用できるが、ほかの原因でメソッドが失敗したので、作成されていない。
DSFXR_UNKNOWN
エフェクトがシステムに登録されていないため、エフェクトは作成されていない。

結果コードが必要でない場合、このパラメータは NULL にする。

戻り値

成功した場合は、DS_OK または DS_INCOMPLETE を返す。

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

DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM

注意

通常、DSBCAPS_LOCDEFER で作成されたバッファは、IDirectSoundBuffer8::Play が呼び出されるまでリソースに割り当てられない。遅延バッファにリソースを割り当てるには、IDirectSoundBuffer8::AcquireResources を使う。これによって、アプリケーションは、エフェクトの処理に関する情報を取得して、バッファが演奏される前にエフェクト パラメータを設定できる。

メソッドが失敗した場合は、pdwResultCodes の値を調べて、失敗の原因となったエフェクトを特定する。

リソースを割り当てられた、まだ演奏されていないバッファは、Play メソッドに渡されたボイス管理フラグにより、早めに終了される候補とならない。

AcquireResources によって取得されたリソースは、再生が停止されたときに解放される。

メソッドが既に呼び出されたバッファで、繰り返しメソッドが呼び出された場合、エフェクトのステータスは返されるが、それ以上のリソースは割り当てられない。

この関数の dwEffectsCount パラメータは、IDirectSoundBuffer8::SetFX の呼び出しで渡されたパラメータと同じでなければならない。

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファのリソースを取得しようとすると、メソッドは失敗し、オペレーティング システムに応じて DSERR_CONTROLUNAVAIL または DSERR_INVALIDCALL を返す。

動作環境

  ヘッダー : dsound.h で宣言。

参照

IDirectSoundBuffer8::SetFXDSBCAPS