Microsoft DirectX 8.0 (C++)

IDirectInputEffect::SetParameters

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

HRESULT SetParameters(
  LPCDIEFFECT peff,  
  DWORD dwFlags      
);

パラメータ

peff
エフェクトの情報を格納する DIEFFECT 構造体。dwFlags パラメータの対応ビットによって指定されている任意のメンバと同様、このメソッドを呼び出す前にアプリケーションによって dwSize メンバが設定されていなければならない。
dwFlags
エフェクトの情報のどの部分を設定するかを指定し、パラメータのダウンロード処理の方法を指定するフラグ。ゼロ、または次のフラグを取ることができる。
DIEP_AXES
cAxes および rgdwAxes メンバがデータを格納する。
DIEP_DIRECTION
cAxes および rglDirection メンバがデータを格納する。dwFlags メンバが (DIEFF_CARTESIAN または DIEFF_POLAR を使用して) 値を解釈すべき座標系を指定する。
DIEP_DURATION
dwDuration メンバがデータを格納する。
DIEP_ENVELOPE
lpEnvelope メンバは、データを格納する DIENVELOPE 構造体を指す。エフェクトから既存のエンベロープを切り離すには、このフラグを渡し、lpEnvelope メンバ を NULL に設定する。
DIEP_GAIN
dwGain メンバがデータを格納する。
DIEP_NODOWNLOAD
パラメータの更新後、通常は自動実行される IDirectInputEffect::Download を抑制する。「注意」を参照すること。
DIEP_NORESTART
エフェクトの停止や再開を抑制してパラメータを変更する。「注意」を参照すること。
DIEP_SAMPLEPERIOD
dwSamplePeriod メンバがデータを格納する。
DIEP_START
パラメータの更新後、エフェクトを開始 (エフェクトが再生中であれば、再開) させる。デフォルトでは、エフェクトの再生状態は変更されない。
DIEP_STARTDELAY
dwStartDelay メンバがデータを格納する。
DIEP_TRIGGERBUTTON
dwTriggerButton メンバがデータを格納する。
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval メンバがデータを格納する。
DIEP_TYPESPECIFICPARAMS
DIEFFECT 構造体の lpvTypeSpecificParams および cbTypeSpecificParams メンバがエフェクトのタイプ固有データのアドレスとサイズを格納する。

戻り値

成功すれば次の値のいずれかを返す。

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 で宣言。