Platform SDK: DirectX

Device Properties

Properties of DirectInput devices include the size of the data buffer, the range and granularity of values returned from an axis, whether axis data is relative or absolute, and the dead zone and saturation values for a joystick axis, which affect the relationship between the physical position of the stick and the reported data. Specialized devices can have other properties, as well.

With one exception—the gain property of a force-feedback device—properties can be changed only when the device is in an unacquired state.

[C++]

Before calling the IDirectInputDevice7::SetProperty or the IDirectInputDevice7::GetProperty method, set up a property structure, which consists of a DIPROPHEADER structure and one or more elements for data. There are potentially a great variety of properties for input devices, and SetProperty must be able to work with all sorts of structures defining those properties. The purpose of the DIPROPHEADER structure is to define the size of the property structure and how the data is to be interpreted.

DirectInput includes the following predefined property structures:

For SetProperty, the data members of the property structure are the values that you want to set. For GetProperty, the current value is returned in these members.

Before the call to GetProperty or SetProperty, the DIPROPHEADER structure must be initialized with the following:

When getting or setting properties for a whole device, the object identifier dwObj is 0, and the dwHow member is DIPH_DEVICE. If you want to get or set properties for a device object (for example, a particular axis), the combination of dwObj and dwHow values identifies the object. For details, see DIPROPHEADER structure.

After setting up the property structure, pass the address of its header into GetProperty or SetProperty, along with an identifier for the property that you want to obtain or change.

The following values are used to identify the property passed to SetProperty and GetProperty. For more information, see IDirectInputDevice7::GetProperty.

For more information about the last three properties, see also Interpreting Joystick Axis Data.

The following code example sets the buffer size for a device to hold 10 data items:

DIPROPDWORD  dipdw; 
HRESULT      hres; 
dipdw.diph.dwSize = sizeof(DIPROPDWORD); 
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER); 
dipdw.diph.dwObj = 0; 
dipdw.diph.dwHow = DIPH_DEVICE; 
dipdw.dwData = 10; 
hres = lpdiDevice->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph); 
[Visual Basic]

The DirectInputDevice.SetProperty or DirectInputDevice.GetProperty methods take two parameters: a GUID alias in string form that identifies the property being set, and data of type Any. The data is passed in one of the following types:

For SetProperty, the data members of the property types are the values that you want to set. For GetProperty, the current value is returned in these members.

In addition to the actual property data, both these types contain three other members: lHow, lObj, and lSize.

The values in lHow and lObj work together, with lHow signifying the system that is used to identify the device object whose property is being set or retrieved, and lObj identifying the device object.

If lHow is DIPH_BYID, the device object is described by a unique numerical identifier in lObj. This ID can be extracted from the value returned by DirectInputDeviceObjectInstance.GetType after device objects have been enumerated.

For most applications, it is simpler to identify the device object by its offset within the data structure established by DirectInputDevice.SetCommonDataFormat or DirectInputDevice.SetDataFormat. In this case, lHow is DIPH_BYOFFSET, and lObj is the offset, in bytes. For the keyboard, mouse, and any game controller whose data can be returned in a DIJOYSTATE type, the device object can be identified by a predefined constant. See CONST_DIKEYFLAGS, CONST_DIMOUSEOFS, and CONST_DIJOYSTICKOFS.

The lHow member can also contain DIPH_DEVICE, which means that the property belongs to the entire device, rather than a single device object. Buffer size is an example of such a property. When lHow is DIPH_DEVICE, lObj is 0.

Finally, the lSize member of the property type must be initialized to the size of the type. This step is necessary because GetProperty or SetProperty do not know what type is being passed.

The following strings are used to identify the property passed to SetProperty and GetProperty. For more information, see DirectInputDevice.GetProperty.

For more information about dead zone, range, and saturation, see also Interpreting Joystick Axis Data.

The following code example sets the buffer size for a device:

' diDev is a DirectInputDevice whose data format has been set.
 
Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = 10
diProp.lSize = Len(diProp)
Call diDev.SetProperty("DIPROP_BUFFERSIZE", diProp)