Platform SDK: DirectX

IDirectInputDevice7::SetProperty

IDirectInputDevice7::SetProperty メソッドは、デバイスの動作を定義するプロパティを設定する。これらのプロパティには、入力バッファ サイズや軸モードなどがある。

HRESULT SetProperty(
  REFGUID rguidProp,     
  LPCDIPROPHEADER pdiph  
);

パラメータ

rguidProp
設定対象のプロパティの識別子。この識別子は、事前定義された値の 1 つでも、またはプロパティを識別する GUID へのポインタでもよい。以下のプロパティ値が入力デバイスに対して事前定義されている。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、次のいずれか 1 つの値を取ることができる。

DIPROPAUTOCENTER_OFF:ユーザーがデバイスを離しても、自動的にセンタリングを行わない。フォース フィードバックを使用するアプリケーションは、エフェクトの再生前に自動センタリングのスプリングを無効にする必要がある。

DIPROPAUTOCENTER_ON:ユーザーがデバイスを離すと、自動的にセンタリングを行う。たとえば、このモードのジョイスティックは、自動センタリングのスプリングが有効になる。

フォース フィードバック エフェクトを使用すると、自動センタリングのスプリングに影響する場合がある。一部のデバイスでは、フォース フィードバック エフェクトを再生するときに、自動センタリング スプリングを無効にする。

自動センタリング機能をサポートしていないデバイスもある。

DIPROP_AXISMODE
軸モードを設定する。設定値 (DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細は pdiph パラメータの説明を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

DIPROP_BUFFERSIZE
入力バッファ サイズを設定する。設定値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細は pdiph パラメータの説明を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

DIPROP_CALIBRATIONMODE
DirectInput が取得するデータが、キャリブレーション済みかキャリブレーション前かを、アプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取得する。

デバイス全体に対してキャリブレーション モードを設定することは、それぞれの軸に対してキャリブレーション モードを設定することと同じ意味を持つ。

DIPROPDWORD 構造体の dwData メンバは次のいずれか 1 つの値を取ることができる。

DIPROPCALIBRATIONMODE_COOKED:DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルト モードである。

DIPROPCALIBRATIONMODE_RAW:DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。

デバイスを未加工モードに設定すると、無効ゾーン、飽和値、および範囲の設定が無視される。

DIPROP_DEADZONE
0 〜 10,000 の範囲でジョイスティックの無効ゾーンの値を設定する。ここで、0 は無効ゾーンが存在しないこと、5,000 は無効ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸が無効ゾーン内にあると、軸の範囲の中心にあるものと報告される。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

DIPROP_FFGAIN
デバイスのゲインを設定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。

dwData メンバは、デバイス上に作成されたすべてのエフェクトに適用されるゲイン値を格納する。値は、0 〜 10,000 の整数である。デバイスに対するエフェクトのマグニチュードは、この値で調整される。たとえば、10,000 は、すべてのエフェクト マグニチュードをそのまま適用することを示す。9,000 は、すべてのエフェクト マグニチュードをその名目マグニチュードの 90 パーセントに圧縮することを示す。

ゲイン値の設定は、ユーザーの好みに応じて、すべてのフォース フィードバック エフェクトを一率に減少したい場合に有効である。

ほかのプロパティとは異なり、ゲインはデバイスが取得状態にある場合に設定できる。

DIPROP_INSTANCENAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスのインスタンスの登録名を変更すると、接続されている同種のデバイスを区別することができる。インスタンスの登録名は、DIDEVICEINSTANCE 構造体の tszInstanceName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_PRODUCTNAME
これは、詳細設定の可能なアプリケーション用に設けられたプロパティであり、これを使ってデバイスの製品の登録名を変更すると、接続されている同種のデバイスを区別することができる。製品の登録名は、DIDEVICEINSTANCE 構造体の tszProductName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない

pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。

DIPROP_RANGE
オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 構造体の lMin メンバと lMax メンバから取得される。

一部のデバイスでは、これは読み取り専用プロパティである。

範囲の大小を逆にはできない。lMax は、lMin より大きな値でなければならない。

DIPROP_SATURATION
0 〜 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあるとみなされる点のことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (無効ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

pdiph
タイプ固有のプロパティ構造体に含まれる DIPROPHEADER 構造体のアドレス。

戻り値

成功すれば DI_OK または DI_PROPNOEFFECT

失敗すれば次のエラー値のいずれかを返す。

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

バッファ サイズは、IDirectInputDevice7::GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPDWORD 構造体の dwData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

動作環境

  Windows NT/2000 :Windows 2000 が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dinput.h で宣言。
  インポート ライブラリ : dinput.lib を使用。

参照

IDirectInputDevice7::GetProperty