IDirectSoundBuffer8::SetFX

[アーティクル]
04/22/2010

バッファのエフェクトを有効にする。

このメソッドは、CoInitialize が呼び出されていないと失敗する。CoInitialize の呼び出しは、IDirectMusicPerformance8::InitAudio を使って DirectSound を作成するアプリケーションでは、自動的に実行される。ただし、DirectSoundCreate8 を使って DirectSound を作成するアプリケーションは、CoInitialize も呼び出す必要がある。

バッファは、再生中であったりロックされていてはいけない。

構文

  HRESULT SetFX(
  DWORD 
  dwEffectsCount
  , 
  LPDSEFFECTDESC 
  pDSFXDesc
  , 
  LPDWORD 
  pdwResultCodes
   
);

パラメータ

dwEffectsCount

pDSFXDesc および pdwResultCodes の配列における要素の数。この値が 0 の場合は、pDSFXDesc と pdwResultCodes はどちらも NULL でなければならない。0 に設定すると、バッファからすべてのエフェクトが削除される。

pDSFXDesc

バッファに必要なエフェクトを指定する、サイズが dwEffectsCount の DSEFFECTDESC 構造体の配列のアドレス。dwEffectsCount が 0 の場合は、NULL でなければならない。

pdwResultCodes

サイズが dwEffectsCount である DWORD 要素の配列のアドレス。各要素は次のいずれかの値を受け取る。これらの値は、pDSFXDesc 配列の対応するエフェクトの作成を試みた結果を示す。

値	説明
DSFXR_LOCHARDWARE	エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE	エフェクトはソフトウェアでインスタンス化される。
DSFXR_UNALLOCATED	エフェクトは、ハードウェアにもソフトウェアにもまだ割り当てられていない。この値が返されるのは、そのバッファが DSBUFFERDESC の DSBCAPS_LOCDEFER フラグを使って作成されている場合である。
DSFXR_FAILED	リソースを利用できないため、エフェクトは作成されなかった。
DSFXR_PRESENT	エフェクトは利用できるが、要求された他のエフェクトの 1 つを作成できなかったために作成されなかった。要求されたエフェクトのうち 1 つでも作成できない場合、エフェクトはすべて作成されず、呼び出しは失敗する。
DSFXR_UNKNOWN	指定されたエフェクトがシステムに登録されてないため、メソッドは失敗した。

dwEffectsCount が 0 の場合はこのパラメータは NULL でなければならず、結果が必要ない場合はこのパラメータを NULL にしてもかまわない。

戻り値

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

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

リターンコード

CO_E_NOTINITIALIZED

DSERR_PRIOLEVELNEEDED

また、このメソッドは、IMediaObject::SetInputType や IMediaObject::SetOutputType などの DMO メソッドのエラー値を返す場合がある。返されるエラー値については、DirectShow のドキュメントを参照すること。

注意

メソッドが失敗した場合、pdwResultCodes における各エフェクトの値は、DSFXF_PRESENT または DSFXR_UNKNOWN になる。これらの値を調べることによって、失敗の原因となったエフェクトを特定できる。

メソッドを成功させるには、バッファが DSBCAPS_CTRLFX フラグで作成されている必要があり、また、再生中であったりロックされていてはいけない。

メソッドから DSERR_NOINTERFACE またはその他の COM エラーが返された場合は、結果コードの配列で DSFXR_PRESENT または DSFXR_UNKNOWN を調べて、エラーの発生原因となったエフェクトを確認する。メソッドから DSERR_INVALIDPARAM が返された場合は、結果コードで DSFXR_FAILED を調べて、リソースを取得できなかったエフェクトを確認する。

バッファがオーディオパスの一部である場合は、オーディオパスは非アクティブでなければならない。「IDirectMusicAudioPath8::Activate」を参照すること。

バッファにエフェクトが設定されていないと、エフェクトインターフェイスを取得することはできない。エフェクトインターフェイスを取得するには、IDirectSoundBuffer8::GetObjectInPath を使う。

要件

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

参照

次の方法で共有

IDirectSoundBuffer8::SetFX

その他のリソース