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; 
 
typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;

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.

Other object types might be defined later.

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. See Remarks.

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::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 Human Interface Device (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 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

Warning  The value in dwOfs is the offset within the raw data returned by the device, regardless of whether or not 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.

Requirements

  Windows NT/2000/XP: Requires Windows 2000.
  Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
  Header: Declared in Dinput.h.