The DIDEVICEOBJECTINSTANCE structure contains information about a device object instance. This structure is used with the IDirectInputDevice::EnumObjects method to provide the DIEnumDeviceObjectsProc callback function with information about a particular object associated with a device, like an axis or button. It is also used with the IDirectInputDevice::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 wReserved;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE;
typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;
Members
dwSize
Size of the structure, in bytes. During enumeration, the application may inspect this value to determine how many members of the structure are valid. When the structure is passed to the IDirectInputDevice::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 may represent the left-right motion of a mouse.
GUID_YAxis
The vertical axis. For example, it may represent the forward-backward motion of a mouse.
GUID_ZAxis
The z-axis. For example, it may represent rotation of the wheel on a mouse, or movement of a throttle control on a joystick.
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 button on a mouse.
GUID_Key
A key on a keyboard.
GUID_POV
A point-of-view indicator or "hat".
GUID_Unknown
Unknown.
Other object types may be defined in the future.
dwOfs
Offset within the data format at which data is reported for this object. This value can be used to identify the object in method calls and structures that accept the DIPH_BYOFFSET flag.
dwType
Device type that describes the object. It is a combination of DIDFT_* flags that describe the object type (axis, button, and so forth) 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 IDirectInputDevice::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_POLLED
The object does not return data until the IDirectInputDevice2::Poll method is called.
tszName[MAX_PATH]
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 HID 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 HID usage page associated with the object, if known. Human Interface Devices will always report a usage page. Non-HID devices may optionally report a usage page; if they do not, then the value of this member will be zero.
wUsage
The HID usage associated with the object, if known. Human Interface Devices will always report a usage. Non-HID devices may optionally report a usage; if they do not, then the value of this member will be zero.
dwDimension
The dimensional units in which the object's value is reported, if known, or zero if not known. Applications can use this field to distinguish between, for example, the position and velocity of a control.
wExponent
The exponent to associate with the dimension, if known.
wReserved
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), then the object was designed to be the elevator trim control on a flightstick. 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.
QuickInfo
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 OSR2 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in dinput.h.