次の方法で共有

IDirectInputEffect::SetParameters

  • [アーティクル]

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

HRESULT 
SetParameters(
  LPCDIEFFECT peff,
  DWORD dwFlags
);

パラメータ

  • peff
    エフェクト情報を格納する DIEFFECT 構造体。このメソッドを呼び出す前に、アプリケーションは dwSize メンバーにデータを格納し、さらに dwFlags パラメーターの対応するビットによって指定されたメンバーにもデータを格納する必要があります。
  • dwFlags
    エフェクト情報のどの部分を設定し、パラメーターのダウンロードをどのように処理するか指定するフラグ。値は 0、または次のいずれかの定数 (複数可) を指定します。
    • 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 です。メソッドが失敗した場合は、戻り値は IERR_NOTINITIALIZED、DIERR_INCOMPLETEEFFECT、DIERR_INPUTLOST、DIERR_INVALIDPARAM、または DIERR_EFFECTPLAYING、DI_DOWNLOADSKIPPED、DI_EFFECTRESTARTED です。

解説　

エフェクトに対する DIEffectInfo 構造体の dwDynamicParams メンバーは、エフェクトの再生中に動的に更新できるパラメーターを指定します。

非同期 IDirectInputEffect::SetParameters メソッドはエフェクトを自動的にダウンロードしますが、DIEP_NODOWNLOAD フラグを設定することによってこの動作を抑止できます。自動ダウンロードを抑止した場合は、IDirectInputEffect::Download メソッドを呼び出してエフェクトを手動でダウンロードできます。

エフェクトの再生中にパラメーターが変更されると、新しいパラメーターはエフェクトの開始時のパラメーターであった場合と同様に作用します。

たとえば、3 秒の期間を指定して周期的なエフェクトが開始されたとします。2 秒後に、エフェクトの方向が変更されました。この場合、エフェクトは新しい方向であと 1 秒継続します。エフェクトのエンベロープ、フェーズ、振幅などのパラメーターは、方向が変更されなかった場合と同様に引き続き使用されます。

同じ状況で、2 秒後にエフェクトの期間が 1.5 秒に変更された場合、エフェクトは停止します。

通常、再生中のエフェクトのパラメーターをドライバーが更新できなければ、ドライバーはエフェクトを停止し、パラメーターを更新してから、エフェクトを再開することが可能です。DIEP_NORESTART フラグを渡すと、この動作が抑止されます。再生中のエフェクトのパラメーターをドライバーが更新できない場合は、エラー コード DIERR_EFFECTPLAYING が返され、パラメーターは更新されません。

DIEP_NODOWNLOAD、DIEP_START、および DIEP_NORESTART の各フラグは、複数設定することはできません。(フラグを 1 つも渡さなくても構いません。)

これら 3 つのフラグは、ダウンロードと再生の動作を次のように制御します。

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

DIEP_START フラグを設定すると、エフェクト パラメーターが更新されてデバイスにダウンロードされ、エフェクトは IDirectInputEffect::Start メソッドが呼び出されて dwIterations パラメーターが 1 に設定され、フラグが設定されていない場合とまったく同様の状態で開始されます。(更新と DIEP_START を組み合わせると、 IDirectInputEffect::Start を別途呼び出す場合よりも処理が少し高速になります。これは、デバイスに送信する必要のある情報が少なくなるからです。)

DIEP_NODOWNLOAD または DIEP_START のどちらも設定せず、エフェクトが再生されていない場合は、パラメーターが更新されてデバイスにダウンロードされます。

DIEP_NODOWNLOAD または DIEP_START のどちらも設定せず、エフェクトが再生中の場合は、デバイスが即時更新をサポートしていればパラメーターが更新されます。そうでなければ、動作は DIEP_NORESTART フラグの状態によって異なります。このフラグが設定されている場合は、エラー コード DIERR_EFFECTPLAYING が返されます。このフラグがクリアされている場合は、エフェクトは停止し、パラメーターが更新されてから、エフェクトが再開されます。

要件

ヘッダー: Dinput.h 宣言