DIDEVICEOBJECTINSTANCE
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.
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.
