DIDEVICEOBJECTINSTANCE

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/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dinput.h.