Microsoft DirectX 8.0 (Visual Basic)

DirectInputEffect.SetParameters

エフェクトの特性を設定する。

object.SetParameters(effectinfo As DIEFFECT, _
    flags As CONST_DIEPFLAGS)

指定項目

object
DirectInputEffect オブジェクトを指定する。
effectinfo
エフェクト パラメータを格納する DIEFFECT 型。
flags
エフェクト情報のどの部分を設定するか、パラメータのダウンロードをどのように処理するかを指定する、CONST_DIEPFLAGS 列挙からのフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

どのパラメータがエフェクトの再生中に動的に更新できるかを判定するには、DirectInputEnumEffects.GetDynamicParams メソッドを使用する。

DirectInputEffect.SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていた場合、DirectInputEffect.Download を呼び出してエフェクトを手動でダウンロードできる。

エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。

たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されているとする。2 秒後に、エフェクトの方向が変更される。その後、エフェクトは残りの 1 秒間は新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。

先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。

通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。

フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち同時に 2 つ以上を設定してはいけない(何も渡さなくてもよい)。

この 3 つのフラグは、次に示すように、ダウンロード処理と再生処理を制御する。

DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。

DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、DirectInputEffect.Start メソッドが iterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトを再生していないときは、パラメータは更新され、デバイスにダウンロードされる。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグがなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。