IDirectInputDevice8::SetProperty メソッド

[アーティクル]
04/22/2010

IDirectInputDevice8::SetProperty メソッド

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

構文

HRESULT SetProperty(      
    REFGUID rguidProp,
    LPCDIPROPHEADER pdiph
);

パラメータ

rguidProp
C++ の場合、設定するプロパティを識別するグローバル一意識別子 (GUID) に対する参照値。C の場合、この GUID のアドレス。この識別子は、事前定義された値の 1 つでも、プロパティを識別する GUID へのポインタでもよい。以下のプロパティ値が入力デバイスに対して事前定義されている。
- DIPROP_APPDATA
  ゲーム内のアクションに関連するアプリケーション定義の値を DIPROPPOINTER として設定する。
- DIPROP_AUTOCENTER
  デバイスオブジェクトが自動センタリングを行うかどうかを指定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。
  
  dwData メンバには、次のいずれかの値を指定できる。
  
  DIPROPAUTOCENTER_OFF :ユーザーがデバイスを離しても、自動的にセンタリングを行わない。フォースフィードバックを使うアプリケーションは、エフェクトの再生前に自動センタリングを無効にする必要がある。
  
  DIPROPAUTOCENTER_ON :ユーザーがデバイスを離すと、自動的にセンタリングを行う。
  
  自動センタリング機能をサポートしていないデバイスもある。
- DIPROP_AXISMODE
  軸モードを設定する。設定値 (DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。詳細については、pdiph パラメータの説明を参照すること。
  
  この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。
- DIPROP_BUFFERSIZE
  入力バッファサイズを設定する。設定値は、割り当てられた DIPROPDWORD 構造体の dwData メンバに指定しなければならない。「注意」を参照すること。この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。
- DIPROP_CALIBRATION
  キャリブレーションを必要とする軸を操作するために Microsoft® DirectInput® が使う情報にアプリケーションがアクセスできるようにするための、事前定義されたプロパティ。このプロパティは、主にコントロールパネル型のアプリケーション用に存在する。通常のアプリケーションは、キャリブレーション情報を扱う必要はない。
  
  軸のキャリブレーションモードプロパティにアクセスするには、DIPROPHEADER 構造体の dwHow メンバに DIPH_BYID または DIPH_BYOFFSET を設定し、dwObj メンバにオブジェクト ID またはオフセットを設定する。
  
  新しいキャリブレーションデータを設定したコントロールパネルアプリケーションは、IDirectInputJoyConfig::SendNotify メソッドも呼び出して、キャリブレーションの変更を他のアプリケーションに通知しなければならない。IDirectInputJoyConfig::SendNotify の詳細については、Microsoft DirectX ® Driver Development Kit (DDK) を参照すること。
- DIPROP_CALIBRATIONMODE
  DirectInput が取得するデータが、キャリブレーション済みかキャリブレーション前かをアプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取得する。
  
  デバイス全体に対してキャリブレーションモードを設定することは、それぞれの軸に対してキャリブレーションモードを設定することと同じ意味を持つ。
  
  DIPROPDWORD 構造体の dwData メンバには次のいずれかの値を指定できる。
  
  DIPROPCALIBRATIONMODE_COOKED :DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルトモードである。
  
  DIPROPCALIBRATIONMODE_RAW :DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロールパネル型のアプリケーションでのみ使う。未加工データにはマイナス値が含まれることもある。
  
  デバイスを未加工モードに設定すると、デッドゾーン、飽和、および範囲の設定が無視される。
- DIPROP_CPOINTS
  未加工の到着データを調整するために使うキャリブレーションポイントを設定する。設定値は、割り当てられた DIPROPCPOINTS 構造体の cp 配列内の CPOINT 型として指定しなければならない。この設定値は個別のデバイスオブジェクトに適用されるので、割り当てられた DIPROPHEADER 構造体の dwHow メンバは、DIPH_BYID または DIPH_BYOFFSETT のいずれかに設定しなければならない。
- 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 パーセントに圧縮することを示す。
  
  DirectInput は、常にゲイン値を確認してからゲインプロパティを設定する。ゲインが範囲外 (0 未満または 10,000 以上) の場合、IDirectInputDevice8::SetProperty は DIERR_INVALIDPARAM を返す。それ以外の場合、成功すると、デバイスがフォースフィードバックをサポートしていない場合でも、常に DI_OK を返す。
  
  ゲイン値の設定は、ユーザー設定に応じて、すべてのフォースフィードバックエフェクトを一率に減少させたい場合に有効である。
  
  他のプロパティとは異なり、ゲインはデバイスが取得状態にある場合に設定できる。
- DIPROP_INSTANCENAME
  これは、先進のアプリケーション用に設けられたプロパティであり、これを使ってデバイスのインスタンスの登録名を変更すると、接続されている同種のデバイスを区別できる。インスタンスの登録名は、DIDEVICEINSTANCE 構造体の tszInstanceName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。
  
  この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。
  
  pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。
- DIPROP_PRODUCTNAME
  これは、先進のアプリケーション用に設けられたプロパティであり、これを使ってデバイスの製品の登録名を変更すると、接続されている同種のデバイスを区別することができる。製品の登録名は、DIDEVICEINSTANCE 構造体の tszProductName メンバ内に返される。アプリケーションは通常、登録名を変更する必要はない。
  
  この設定値はデバイス全体に適用されるので、割り当てられた DIPROPDWORD 構造体の dwHow メンバは、DIPH_DEVICE でなければならない。
  
  pdiph パラメータは、DIPROPSTRING 構造体の diph メンバへのポインタでなければならない。
  
  プロダクト名の設定は、Microsoft Windows® 98、Windows 2000、および Windows Millennium Edition (Windows Me) コンピュータで、アナログジョイスティックのユーザー定義名を変更するためだけに有効である。それ以外の場合、このプロパティを設定しようとすると、DI_OK が返る。ただし、このユーザー定義名は IDirectInputDevice8::GetProperty で使われる場所には保存されない。
- DIPROP_RANGE
  オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 構造体の lMin メンバと lMax メンバから取得される。
  
  一部のデバイスでは、これは読み取り専用プロパティである。
  
  逆の範囲は設定できない。つまり、lMax は常に lMin より大きくなければならない。
- DIPROP_SATURATION
  0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあると見なされるポイントのことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (デッドゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置になる。この設定は、デバイス全体または 1 つの特定の軸のいずれかに適用できる。
pdiph
タイプ固有のプロパティ構造体に含まれる DIPROPHEADER 構造体のアドレス。

戻り値

成功した場合は、DI_OK または DI_PROPNOEFFECT を返す。

失敗した場合は、次のいずれかのエラー値を返す。

DIERR_INVALIDPARAM	無効なパラメータが、戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準のコンポーネントオブジェクトモデル (COM) 戻り値である E_INVALIDARG に等しい。
DIERR_NOTINITIALIZED	このオブジェクトは初期化されていない。
DIERR_OBJECTNOTFOUND	要求されたオブジェクトは存在しない。
DIERR_UNSUPPORTED	呼び出した関数はこの時点ではサポートされていない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。

注意

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

参照

IDirectInputDevice8::GetProperty

次の方法で共有

IDirectInputDevice8::SetProperty メソッド

IDirectInputDevice8::SetProperty メソッド

その他のリソース