Microsoft DirectX 8.0 (C++) |
エフェクトの特性を設定する。
HRESULT SetParameters( LPCDIEFFECT peff, DWORD dwFlags );
成功すれば次の値のいずれかを返す。
DI_DOWNLOADSKIPPED |
DI_EFFECTRESTARTED |
DI_OK |
DI_TRUNCATED |
DI_TRUNCATEDANDRESTARTED |
失敗した場合は、次のいずれかのエラー値を返す。
DIERR_NOTINITIALIZED |
DIERR_INCOMPLETEEFFECT |
DIERR_INPUTLOST |
DIERR_INVALIDPARAM |
DIERR_EFFECTPLAYING |
エフェクト用の DIEFFECTINFO 構造体の dwDynamicParams メンバは、エフェクトの再生中に動的に更新できるパラメータを指定する。
IDirectInputEffect::SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていれば、IDirectInputEffect::Download メソッドを起動して、エフェクトを手動でダウンロードすることができる。
エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。
たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されていて、2 秒後に、エフェクトの方向が変更されるとする。その後、残りの 1 秒のエフェクトは、新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。
先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。
通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。
フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち同時に 2 つ以上を設定してはいけない(何も渡さなくてもよい)。
この 3 つのフラグは、次に示すように、ダウンロード処理と再生処理を制御する。
DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。
DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、IDirectInputEffect::Start メソッドが dwIterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。
DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生していないときは、パラメータは更新され、デバイスにダウンロードされる。
DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグが設定されていなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。
Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dinput.h で宣言。