DIDEVICEOBJECTINSTANCE Structure

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

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.