Microsoft DirectX 8.0 (C++)

IDirectSoundBuffer8::SetFX

バッファのエフェクトを有効にする。バッファは再生中であったりロッキングされていてはならない。

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

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

パラメータ

dwEffectsCount
pDSFXDesc 配列および pdwResultCodes 配列の要素数を指定する値。この値が 0 の場合、pDSFXDesc および pdwResultCodes はどちらも NULL でなければならない。0 に設定すると、バッファのすべてのエフェクトが削除される。
pDSFXDesc
サイズが dwEffectsCountDSEFFECTDESC 構造体の配列のアドレス。バッファのエフェクトを指定する。dwEffectsCount が 0 の場合は NULL でなければならない。
pdwResultCodes
サイズが dwEffectsCountDWORD 要素の配列のアドレス。各要素は次のいずれかの値を受け取る。これらの値は、pDSFXDesc 配列の対応するエフェクトを作成しようとした結果を示す。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_UNALLOCATED
ハードウェアまたはソフトウェアにまだエフェクトが設定されていない。この値が返されるのは、そのバッファが DSBUFFERDESC の DSBCAPS_LOCDEFER フラグを使って作成されている場合である。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_PRESENT
エフェクトは利用できるが、要求されたほかのエフェクトの 1 つが作成できなかったために作成できなかった。要求されたエフェクトのうち 1 つでも作成できない場合、エフェクトはすべて作成されず、呼び出しは失敗する。
DSFXR_UNKNOWN
指定されたエフェクトはシステムに登録されてない。このため、メソッドは失敗した。

このパラメータを NULL にすると、結果の値が返されない。また、dwEffectsCount が 0 の場合は、このパラメータを NULL にしなければならない。

戻り値

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

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

CO_E_NOTINITIALIZED
DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

また、このメソッドは、IMediaObject::SetInputTypeIMediaObject::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 で宣言。

参照

DSBCAPSIDirectSoundBuffer8::AcquireResources