Device Properties

Properties of Microsoft?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. Specialized devices can have other properties as well. For a list of properties defined by DirectInput, see IDirectInputDevice8::GetProperty.

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

Before calling the IDirectInputDevice8::SetProperty or the IDirectInputDevice8::GetProperty method you must set up a property structure that consists of a DIPROPHEADER structure and one or more elements for data. There is potentially a great variety of properties for input devices, and IDirectInputDevice8::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.
• DIPROPGUIDANDPATH is a specialized property structure that enables applications to perform operations on a Human Interface Device (HID) that is not supported by DirectInput. The structure consists of a DIPROPHEADER, a globally unique identifier (GUID), and a Unicode string for the path.
• DIPROPSTRING is for Unicode string properties. The structure comprises a DIPROPHEADER and a Unicode string.

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

Before the call to IDirectInputDevice8::GetProperty or IDirectInputDevice8::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 value indicating how the object identifier should be interpreted.

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.

After setting up the property structure, pass the address of its header into IDirectInputDevice8::GetProperty or IDirectInputDevice8::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 IDirectInputDevice8::SetProperty and IDirectInputDevice8::GetProperty.

• DIPROP_BUFFERSIZE. See also Buffered and Immediate Data. The buffer size can also be set by using the IDirectInputDevice8::SetActionMap method.
• 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 code example sets the buffer size for a device to hold up to 10 data items:

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