IDirectSoundBuffer8::SetFX
SetFX メソッドはバッファーのエフェクトを有効にします。
このメソッドが成功するには、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 配列の対応するエフェクトの作成を試みた結果を示します。注 dwEffectsCount が 0 の場合、このパラメーターは NULL でなければなりません。また、結果が不要な場合は NULL にすることができます。
値 説明 DSFXR_LOCHARDWARE エフェクトはハードウェアでインスタンス化されます。 DSFXR_LOCSOFTWARE エフェクトはソフトウェアでインスタンス化されます。 DSFXR_UNALLOCATED エフェクトは、ハードウェアにもソフトウェアにもまだ割り当てられていません。この値が返されるのは、そのバッファーが DSBUFFERDESC の DSBCAPS_LOCDEFER フラグを指定して作成されている場合です。 DSFXR_FAILED リソースを利用できなかったため、エフェクトは作成されていません。 DSFXR_PRESENT エフェクトは利用可能ですが、要求された他のエフェクトのいずれかを作成できなかったため、作成されませんでした。要求されたエフェクトのうち 1 つでも作成できない場合、エフェクトはすべて作成されず、呼び出しは失敗します。 DSFXR_UNKNOWN エフェクトがシステムに登録されてないため、メソッドは失敗しました。
戻り値
成功した場合は、DS_OK または DS_INCOMPLETE を返します。失敗した場合は、以下の表に示すエラー値のいずれかが戻り値となります。
リターン コード |
---|
CO_E_NOTINITIALIZED |
DSERR_CONTROLUNAVAIL |
DSERR_GENERIC |
DSERR_INVALIDPARAM |
DSERR_INVALIDCALL |
DSERR_NOINTERFACE |
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 を調べて、リソースを取得できなかったエフェクトを確認します。
バッファーにエフェクトが設定されていないと、エフェクト インターフェイスを取得することはできません。エフェクト インターフェイスを取得するには、GetObjectInPath を使用します。
要件
ヘッダー: DSound.h 宣言
ライブラリ: Dsound3d.dll 内容