DIDEVICEOBJECTINSTANCE Structure

  • Article

Describes a device object instance. This structure is used with the IDirectInputDevice8::EnumObjects method to provide the DIEnumDeviceObjectsCallback callback function with information about a particular object associated with a device, such as an axis or button. It is also used with the IDirectInputDevice8::GetObjectInfo method to retrieve information about a device object.

Syntax

typedef struct DIDEVICEOBJECTINSTANCE {
    DWORD dwSize;
    GUID guidType;
    DWORD dwOfs;
    DWORD dwType;
    DWORD dwFlags;
    TCHAR tszName[MAX_PATH];
    DWORD dwFFMaxForce;
    DWORD dwFFForceResolution;
    WORD wCollectionNumber;
    WORD wDesignatorIndex;
    WORD wUsagePage;
    WORD wUsage;
    DWORD dwDimension;
    WORD wExponent;
    WORD wReportId;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE;

Members

  • dwSize
    Size of the structure, in bytes. During enumeration, the application can inspect this value to determine how many members of the structure are valid. When the structure is passed to the IDirectInputDevice8::GetObjectInfo method, this member must be initialized to sizeof(DIDEVICEOBJECTINSTANCE).
  • guidType
    Unique identifier that indicates the object type. This member is optional. If present, it can be one of the following values:
    • GUID_XAxis
      The horizontal axis. For example, it can represent the left-right motion of a mouse.
    • GUID_YAxis
      The vertical axis. For example, it can represent the forward-backward motion of a mouse.
    • GUID_ZAxis
      The z-axis. For example, it can represent the rotation of a mouse wheel or the movement of a joystick throttle control.
    • GUID_RxAxis
      Rotation around the x-axis.
    • GUID_RyAxis
      Rotation around the y-axis.
    • GUID_RzAxis
      Rotation around the z-axis (often a rudder control).
    • GUID_Slider
      A slider axis.
    • GUID_Button
      A mouse button.
    • GUID_Key
      A keyboard key.
    • GUID_POV
      A point-of-view indicator.
    • GUID_Unknown
      Unknown.
  • dwOfs
    Offset in the native data format of the device. The native data format corresponds to the raw device data. The dwOfs member does not correspond to the device constant, such as DIJOFS_BUTTON0, for this object.
  • dwType
    Device type that describes the object. It is a combination of DIDFT_* flags that describe the object type (axis, button, and so on) and contains the object instance number in the middle 16 bits. Use the DIDFT_GETINSTANCE macro to extract the object instance number. For the DIDFT_* flags, see IDirectInputDevice8::EnumObjects.
  • dwFlags
    Flags describing other attributes of the data format. This value can be one of the following:
    • DIDOI_ASPECTACCEL
      The object reports acceleration information.
    • DIDOI_ASPECTFORCE
      The object reports force information.
    • DIDOI_ASPECTMASK
      The bits that are used to report aspect information. An object can represent at most one aspect.
    • DIDOI_ASPECTPOSITION
      The object reports position information.
    • DIDOI_ASPECTVELOCITY
      The object reports velocity information.
    • DIDOI_FFACTUATOR
      The object can have force-feedback effects applied to it.
    • DIDOI_FFEFFECTTRIGGER
      The object can trigger playback of force-feedback effects.
    • DIDOI_GUIDISUSAGE
      The pguid member of the DIOBJECTDATAFORMAT structure contains the desired usage page and usage in a packed DWORD. See DIMAKEUSAGEDWORD.
    • DIDOI_POLLED
      The object does not return data until the IDirectInputDevice8 Interface method is called.
  • tszName
    Name of the object; for example, "X-Axis" or "Right Shift."
  • dwFFMaxForce
    The magnitude of the maximum force that can be created by the actuator associated with this object. Force is expressed in newtons and measured in relation to where the hand would be during normal operation of the device.
  • dwFFForceResolution
    The force resolution of the actuator associated with this object. The returned value represents the number of gradations, or subdivisions, of the maximum force that can be expressed by the force-feedback system from 0 (no force) to maximum force.
  • wCollectionNumber
    The Human Interface Device (human interface device) link collection to which the object belongs.
  • wDesignatorIndex
    An index that refers to a designator in the HID physical descriptor. This number can be passed to functions in the HID parsing library (Hidpi.h) to obtain additional information about the device object.
  • wUsagePage
    The Human Interface Device (HID) usage page associated with the object, if known. HIDs always report a usage page. Non-HID devices can optionally report a usage page; if they do not, the value of this member is 0.
  • wUsage
    The HID usage associated with the object, if known. HIDs always report a usage. Non-HIDs can optionally report a usage; if they do not, the value of this member is 0.
  • dwDimension
    A Human Interface Device (HID) code for the dimensional units in which the object's value is reported, if known, or 0 if not known.
  • wExponent
    The exponent to associate with the dimension, if known. Dimensional units are always integral, so an exponent might be needed to convert them to nonintegral types.
  • wReportId
    Reserved.

Remarks

Note

The value in dwOfs is the offset within the raw data returned by the device, regardless of whether the data format has been set for the device.

Applications can use the wUsagePage and wUsage members to obtain additional information about how the object was designed to be used. For example, if wUsagePage has the value 0x02 (vehicle controls) and wUsage has the value 0xB9 (elevator trim), the object was designed to be the elevator trim control on a flight stick. A flight simulator application can use this information to provide more reasonable defaults for objects on the device. HID usage codes are determined by the USB standards committee.