DIOBJECTDATAFORMAT

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

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

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 SetDataFormat method must be an absolute axis.

DIDFT_AXIS

The object selected by the SetDataFormat method must be an absolute or relative axis.

DIDFT_BUTTON

The object selected by the SetDataFormat method must be a push button or a toggle button.

DIDFT_FFACTUATOR

The object selected by the 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 SetDataFormat method must be a valid force-feedback effect trigger.

DIDFT_POV

The object selected by the SetDataFormat method must be a point-of-view controller.

DIDFT_PSHBUTTON

The object selected by the SetDataFormat method must be a push button.

DIDFT_RELAXIS

The object selected by SetDataFormat must be a relative axis.

DIDFT_TGLBUTTON

The object selected by SetDataFormat must be a toggle button.

DIDFT_VENDORDEFINED

The object selected by SetDataFormat must be of a type defined by the manufacturer.

dwFlags

Zero or more of the following values:

DIDOI_ASPECTACCEL

The object selected by SetDataFormat must report acceleration information.

DIDOI_ASPECTFORCE

The object selected by SetDataFormat must report force information.

DIDOI_ASPECTPOSITION

The object selected by SetDataFormat must report position information.

DIDOI_ASPECTVELOCITY

The object selected by 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 Microsoft® 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 
}; 

Requirements

  Windows NT/2000/XP: Requires Windows 2000.
  Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
  Header: Declared in Dinput.h.