DIDATAFORMAT

Describes a device's data format. This structure is used with the IDirectInputDevice8::SetDataFormat method.

typedef struct DIDATAFORMAT { 
    DWORD dwSize; 
    DWORD dwObjSize; 
    DWORD dwFlags; 
    DWORD dwDataSize; 
    DWORD dwNumObjs; 
    LPDIOBJECTDATAFORMAT rgodf; 
} DIDATAFORMAT, *LPDIDATAFORMAT;
 
typedef const DIDATAFORMAT *LPCDIDATAFORMAT;

Members

dwSize

Size of this structure, in bytes.

dwObjSize

Size of the DIOBJECTDATAFORMAT structure, in bytes.

dwFlags

Flags describing other attributes of the data format. This value can be one of the following:

DIDF_ABSAXIS

The axes are in absolute mode. Setting this flag in the data format is equivalent to manually setting the axis mode property, using the IDirectInputDevice8::SetProperty method. This cannot be combined with DIDF_RELAXIS flag.

DIDF_RELAXIS

The axes are in relative mode. Setting this flag in the data format is equivalent to manually setting the axis mode property using the IDirectInputDevice8::SetProperty method. This cannot be combined with the DIDF_ABSAXIS flag.

dwDataSize

Size of a data packet returned by the device, in bytes. This value must be a multiple of 4 and must exceed the largest offset value for an object's data within the data packet.

dwNumObjs

Number of objects in the rgodf array.

rgodf

Address to an array of DIOBJECTDATAFORMAT structures. Each structure describes how one object's data should be reported in the device data. Typical errors include placing two pieces of information in the same location and placing one piece of information in more than one location.

Remarks

Applications do not typically need to create a DIDATAFORMAT structure. An application can use one of the predefined global data format variables, c_dfDIMouse, c_dfDIMouse2, c_dfDIKeyboard, c_dfDIJoystick, or c_dfDIJoystick2.

Applications that need to create a DIDATAFORMAT structure must first call IDirectInput8::EnumObjects to determine the available objects for the current device. This is because the IDirectInput8::SetDataFormat method will return DIERR_INVALIDPARAM if an an object is described in the DIDATAFORMAT structure but does not exist on the current device.

The following code example sets a data format for a device that has an X-axis and a Y-axis:

// Suppose an application uses the following 
// structure to read device data. 
 
typedef struct MYDATA { 
    LONG  lX;                   // X-axis goes here. 
    LONG  lY;                   // Y-axis goes here. 
    BYTE  bButtonA;             // One button goes here. 
    BYTE  bButtonB;             // Another button goes here. 
    BYTE  bPadding[2];          // Must be DWORD multiple in size. 
} MYDATA; 
 
// Then, it can use the following data format. 
 
DIOBJECTDATAFORMAT rgodf[ ] = { 
  { &GUID_XAxis, FIELD_OFFSET(MYDATA, lX),
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, }, 
  { &GUID_YAxis, FIELD_OFFSET(MYDATA, lY), 
    DIDFT_AXIS | DIDFT_ANYINSTANCE, 0, }, 
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonA),
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, }, 
  { &GUID_Button, FIELD_OFFSET(MYDATA, bButtonB), 
    DIDFT_BUTTON | DIDFT_ANYINSTANCE, 0, }, 
}; 
#define numObjects (sizeof(rgodf) / sizeof(rgodf[0])) 
 
DIDATAFORMAT df = { 
    sizeof(DIDATAFORMAT),       // Size of this structure 
    sizeof(DIOBJECTDATAFORMAT), // Size of object data format 
    DIDF_ABSAXIS,               // Absolute axis coordinates 
    sizeof(MYDATA),             // Size of device data 
    numObjects,                 // Number of objects 
    rgodf,                      // And here they are 
}; 

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.

See Also

DIACTIONFORMAT