Microsoft DirectX 8.0 (Visual Basic) |
object.SetParameters(effectinfo As DIEFFECT, _ flags As 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 が返される。このフラグがなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。