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 may have other properties as well.

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

Before calling the IDirectInputDevice::SetProperty or IDirectInputDevice::GetProperty methods you need to 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:

• DIPROPDWORD defines a structure containing a DIPROPHEADER and a DWORD data member, for properties that require a single value, such as a buffer size.
• DIPROPRANGE is for range properties, which require two values (maximum and minimum). It consists of a DIPROPHEADER and two LONG data members.

For SetProperty, the data members of the property structure are the values 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:

• The size of the property structure
• The size of the DIPROPHEADER structure itself
• An object identifier
• A "how" code indicating the way the object identifier should be interpreted

When getting or setting properties for a whole device, the object identifier dwObj is zero and the "how" code dwHow 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 the reference for the DIPROPHEADER structure.

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

The following values are used to identify the property passed to SetProperty and GetProperty. For more information see the reference for IDirectInputDevice::GetProperty.

• DIPROP_BUFFERSIZE. See also Buffered and Immediate Data.
• DIPROP_AXISMODE. See also Relative and Absolute Axis Coordinates.
• DIPROP_CALIBRATIONMODE
• DIPROP_GRANULARITY
• DIPROP_FFGAIN
• DIPROP_FFLOAD
• DIPROP_AUTOCENTER
• DIPROP_RANGE
• DIPROP_DEADZONE
• DIPROP_SATURATION

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

The following example sets the buffer size for a device so that it will 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);