DIOBJECTDATAFORMAT Structure

Describes a device object's data format for use with the IDirectInputDevice8::SetDataFormat method.

Syntax

typedef struct DIOBJECTDATAFORMAT {
    CONST GUID * pguid;
    DWORD dwOfs;
    DWORD dwType;
    DWORD dwFlags;
} DIOBJECTDATAFORMAT, *LPDIOBJECTDATAFORMAT;

Members

• pguid
  Unique identifier for the axis, button, or other input source. When requesting a data format, making this member NULL indicates that any type of object is permissible.
• dwOfs
  Offset within the data packet where the data for the input source is stored. This value must be a multiple of 4 for DWORD size data, such as axes. It can be byte-aligned for buttons.
• dwType
  Device type that describes the object. It is a combination of the following flags describing the object type (axis, button, and so forth) and containing the object-instance number in the middle 16 bits. When requesting a data format, the instance portion must be set to DIDFT_ANYINSTANCE to indicate that any instance is permissible, or to DIDFT_MAKEINSTANCE(n) to restrict the request to instance n. See the examples under Remarks.
  • DIDFT_ABSAXIS
    The object selected by the IDirectInputDevice8::SetDataFormat method must be an absolute axis.
  • DIDFT_AXIS
    The object selected by the IDirectInputDevice8::SetDataFormat method must be an absolute or relative axis.
  • DIDFT_BUTTON
    The object selected by the IDirectInputDevice8::SetDataFormat method must be a push button or a toggle button.
  • DIDFT_FFACTUATOR
    The object selected by the IDirectInputDevice8::SetDataFormat method must contain a force-feedback actuator; in other words, it must be possible to apply forces to the object.
  • DIDFT_FFEFFECTTRIGGER
    The object selected by the IDirectInputDevice8::SetDataFormat method must be a valid force-feedback effect trigger.
  • DIDFT_POV
    The object selected by the IDirectInputDevice8::SetDataFormat method must be a point-of-view controller.
  • DIDFT_PSHBUTTON
    The object selected by the IDirectInputDevice8::SetDataFormat method must be a push button.
  • DIDFT_RELAXIS
    The object selected by IDirectInputDevice8::SetDataFormat must be a relative axis.
  • DIDFT_TGLBUTTON
    The object selected by IDirectInputDevice8::SetDataFormat must be a toggle button.
  • DIDFT_VENDORDEFINED
    The object selected by IDirectInputDevice8::SetDataFormat must be of a type defined by the manufacturer.
• dwFlags
  Zero or more of the following values:
  • DIDOI_ASPECTACCEL
    The object selected by IDirectInputDevice8::SetDataFormat must report acceleration information.
  • DIDOI_ASPECTFORCE
    The object selected by IDirectInputDevice8::SetDataFormat must report force information.
  • DIDOI_ASPECTPOSITION
    The object selected by IDirectInputDevice8::SetDataFormat must report position information.
  • DIDOI_ASPECTVELOCITY
    The object selected by IDirectInputDevice8::SetDataFormat must report velocity information.

Remarks

A data format is made up of several DIOBJECTDATAFORMAT structures, one for each object (axis, button, and so on). An array of these structures is contained in the DIDATAFORMAT structure that is passed to IDirectInputDevice8::SetDataFormat. An application typically does not need to create an array of DIOBJECTDATAFORMAT structures; rather, it can use one of the predefined data formats, c_dfDIMouse, c_dfDIMouse2, c_dfDIKeyboard, c_dfDIJoystick, or c_dfDIJoystick2, which have predefined settings for DIOBJECTDATAFORMAT.

The following object data format specifies that DirectInput should choose the first available axis and report its value in the DWORD at offset 4 in the device data.

DIOBJECTDATAFORMAT dfAnyAxis = { 
    0,                              // Wildcard 
    4,                              // Offset 
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // Any axis is okay. 
    0,                              // Ignore aspect 
}; 

The following object data format specifies that the x-axis of the device should be stored in the DWORD at offset 12 in the device data. If the device has more than one x-axis, the first available one should be selected.

DIOBJECTDATAFORMAT dfAnyXAxis = { 
    &GUID_XAxis,                    // Must be an x-axis 
    12,                             // Offset 
    DIDFT_AXIS | DIDFT_ANYINSTANCE, // Any x-axis is okay. 
    0,                              // Ignore aspect 
}; 

The following object data format specifies that DirectInput should choose the first available button and report its value in the high bit of the byte at offset 16 in the device data.

DIOBJECTDATAFORMAT dfAnyButton = { 
    0,                                // Wildcard 
    16,                               // Offset 
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, // Any button is okay. 
    0,                                // Ignore aspect 
}; 

The following object data format specifies that button 0 of the device should be reported as the high bit of the byte stored at offset 18 in the device data.

If the device does not have a button 0, the attempt to set this data format fails.

DIOBJECTDATAFORMAT dfButton0 = { 
    0,                                    // Wildcard 
    18,                                   // Offset 
    DIDFT_BUTTON | DIDFT_MAKEINSTANCE(0), // Button zero 
    0,                                    // Ignore aspect 
};