The semantics of version numbers are left to the manufacturer of the device. The only guarantee is that newer versions have larger numbers.

Applications do not typically need to create a structure. An application can use one of the predefined global data format variables, c_dfDIMouse, c_dfDIMouse2, c_dfDIKeyboard, c_dfDIJoystick, or c_dfDIJoystick2.

Applications that need to create a structure must first call to determine the available objects for the current device. This is because the method will return if an object is described in the structure but does not exist on the current device.

The following code example sets a data format for a device that has an X-axis and a Y-axis:

 // Suppose an application uses the following 	
            // structure to read device data.  typedef struct MYDATA {  LONG  lX;                   // X-axis goes here.  LONG  lY;                   // Y-axis goes here.  BYTE  bButtonA;             // One button goes here.  BYTE  bButtonB;             // Another button goes here.  BYTE  bPadding[2];          // Must be DWORD multiple in size. 	
            } MYDATA;  // Then, it can use the following data format.  DIOBJECTDATAFORMAT rgodf[ ] = {  { &, FIELD_OFFSET(MYDATA, lX),  | , 0, },  { &, FIELD_OFFSET(MYDATA, lY),   | , 0, },  { &, FIELD_OFFSET(MYDATA, bButtonA),  | , 0, },  { &, FIELD_OFFSET(MYDATA, bButtonB),   | , 0, }, 	
            }; 	
            #define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))   df = {  sizeof(),       // Size of this structure  sizeof(DIOBJECTDATAFORMAT), // Size of object data format  ,               // Absolute axis coordinates  sizeof(MYDATA),             // Size of device data  numObjects,                 // Number of objects  rgodf,                      // And here they are 	
            }; 

The interface is obtained by using the method. For an example, see Creating a DirectInput Device.

supersedes the IDirectInputDevice, IDirectInputDevice2, and IDirectInputDevice7 interfaces used in previous versions of Microsoft DirectX, but does not inherit from them. Methods that share names with those from older interfaces perform similar services, but may not have exactly the same functionality or behavior. You cannot obtain the earlier interfaces by using QueryInterface.

The LPDIRECTINPUTDEVICE8 type is defined as a reference to the interface:

 typedef struct     *LPDIRECTINPUTDEVICE8;	
            

For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).

The number of objects returned in the structure is the maximum number of objects that could be enumerated. However, all of these objects are not necessarily returned during a call to .

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).

For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).

The number of objects returned in the structure is the maximum number of objects that could be enumerated. However, all of these objects are not necessarily returned during a call to .

The and flags in the dwFlags parameter restrict enumeration to objects that meet all the criteria defined by the included flags. For all the other flags, an object is enumerated if it meets the criterion defined by any included flag in this category. For example, ( | ) restricts enumeration to force-feedback trigger objects, and ( | | ) restricts enumeration to buttons of any kind that can be used as effect triggers.

Applications should not rely on this method to determine whether certain keyboard keys or indicator lights are present, as these objects might be enumerated even though they are not present. Although the basic set of available objects can be determined from the device subtype, there is no reliable way of determining whether extra objects such as the menu key are available.

The buffer size determines the amount of data that the buffer can hold between calls to the method before data is lost. This value may be set to 0 to indicate that the application does not read buffered data from the device. If the buffer size in the dwData member of the structure is too large for the device to support it, then the largest possible buffer size is set.

Before a device can be acquired, a data format must be set by using the method or method. If the data format has not been set, Interface returns .

Devices must be acquired before calling the or methods for that device.

Device acquisition does not use a reference count. Therefore, if an application calls the Interface method twice, then calls the Interface method once, the device is unacquired.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

Before device data can be obtained, set the cooperative level by using the method, then set the data format by using , and acquire the device by using the Interface method.

The five predefined data formats require corresponding device state structures according to the following table:

For example, if you passed the c_dfDIMouse format to the method, you must pass a DIMOUSESTATE structure to the method.

In the debug version of DirectInput, if a call is made to and the device has been unacquired, then random bytes will be sent to the device data buffer. To make sure you are not using random device data, always check for the DIERR_UNACQUIRED return code.

Before device data can be obtained, you must set the data format and the buffer size by using the and methods, or by using the method. You must also acquire the device by using the Interface method.

The maximum number of events that the buffer will hold is one less than the buffer size set with the method.

The following code example reads up to ten buffered data elements, removing them from the device buffer as they are read.

  rgdod[10]; 	
            DWORD dwItems = 10; 	
            hres = idirectinputdevice9_GetDeviceData(  sizeof(),  rgdod,  &dwItems,  0); 	
            if (SUCCEEDED(hres)) {  // dwItems = Number of elements read (could be zero). if (hres == ) {  // Buffer had overflowed.  } 	
            } 	
            

Your application can flush the buffer and retrieve the number of flushed items by specifying null for the rgdod parameter and a reference to a variable containing INFINITE for the pdwInOut parameter. The following code example illustrates how this can be done.

 dwItems = INFINITE; 	
            hres = idirectinputdevice9_GetDeviceData(  pdid,  sizeof(),  null,  &dwItems,  0); 	
            if (SUCCEEDED(hres)) {  // Buffer successfully flushed.  // dwItems = Number of elements flushed.  if (hres == ) {  // Buffer had overflowed.  } 	
            }	
            

Your application can query for the number of elements in the device buffer by setting the rgdod parameter to null, setting pdwInOut to INFINITE and setting dwFlags to DIGDD_PEEK. The following code example illustrates how this can be done.

 dwItems = INFINITE; 	
            hres = idirectinputdevice9_GetDeviceData(  pdid,  sizeof(),  null,  &dwItems,  DIGDD_PEEK); 	
            if (SUCCEEDED(hres)) {  // dwItems = Number of elements in buffer.  if (hres == ) {  // Buffer overflow occurred; not all data  //   was successfully captured.  } 	
            } 	
            

To query about whether a buffer overflow has occurred, set the rgdod parameter to null and the pdwInOut parameter to 0. The following code example illustrates how this can be done.

 dwItems = 0; 	
            hres = idirectinputdevice9_GetDeviceData(  pdid,  sizeof(),  null,  &dwItems,  0); 	
            if (hres == ) {  // Buffer overflow occurred. 	
            } 	
            

The data format must be set before the device can be acquired by using the Interface method. It is necessary to set the data format only once. The data format cannot be changed while the device is acquired.

If the application is using action mapping, the data format is set instead by the call to .

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEOBJECTINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEOBJECTINSTANCE_DX3).

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).

If this method fails, the underlying object should be considered to be in an indeterminate state and must be reinitialized before use.

If the return value is , the effect was created, and the parameters of the effect were updated, but the effect was not necessarily downloaded. For it to be downloaded, the device must be acquired in exclusive mode.

If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.

An application can use the dwEffType member of the DIEffectInfo structure to obtain general information about the effect, such as its type and which envelope and condition parameters are supported by the effect.

To exploit an effect to its fullest, contact the device manufacturer to obtain information about the semantics of the effect and its effect-specific parameters.

The device must be acquired at the exclusive cooperative level for this method to succeed.

The and flags may not always be reported correctly because there is no mechanism for the drivers to report that they support these flags.

The device must be acquired at the exclusive cooperative level for this method to succeed.

The results are unpredictable if you create or destroy an effect while an enumeration is in progress. However, the callback function can safely release the effect passed to it.

Other device-specific error codes are also possible. Ask the hardware manufacturer for details.

Because each driver implements different escapes, it is the application's responsibility to ensure that it is sending the escape to the correct driver by comparing the value of the guidFFDriver member of the structure against the value the application is expecting.

Before a device data can be polled, the data format must be set by using the or method, and the device must be acquired by using the Interface method.

Applications should not use . Force Feedback is the recommended way to send data to a device. If you want to send other data to a device, such as changing LED or internal device states, the HID application programming interface (API) is the recommended way.

If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.

The method returns if no mappings were created for the device. For example, a keyboard or mouse will not provide mappings for genre-specific actions.

If is returned, one or more of the mappings was not valid. The dwHow member of the structure is set to DIAH_ERROR. The application can iterate through the action map to find and correct errors.

If DIEFF_MAPFILEFAIL is returned, an error has occurred either reading the vendor supplied file for the device or reading or writing the user configuration file for the device.

> is returned if the mappings were not configurable. For example, the buttons on a voice controller cannot be reconfigured because each button causes a specific hardware action to occur. > overrides other success codes, so a check of the return codes will not reveal if any actions have been mapped.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

This method provides the mechanism to change action-to-control mapping from the device defaults. An application must use this method to map its in-game actions to virtual controls.

The user name passed to this method binds a set of action mappings for a device to a specific user. Settings are automatically saved to disk when they differ from the currently applied map. Applications that accept input from multiple users should be very careful when applying action maps to the system mouse or keyboard, as the action maps for each user may conflict.

The method can be called only when the device is not acquired.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

The buffer at lprgImageInfoArray must be large enough to hold all required image information structures. Applications can query for the required size by calling the method with the dwBufferSize member set to zero. After the call, dwBufferUsed contains the amount of memory, in bytes, that was modified.

The following device types and subtypes are defined for use in the dwDevType member.

• First-person action game device. The following subtypes are defined.

  • Device that does not provide the minimum number of device objects for action mapping.

  • Device designed for first-person shooter games.

  • Device with six degrees of freedom; that is, three lateral axes and three rotational axes.

  • Unknown subtype.

• Device that does not fall into another category.

• Input device used to control another type of device from within the context of the application. The following subtypes are defined.

  • Control used to make communications selections.

  • Device that must use its default configuration and cannot be remapped.

  • Unknown subtype.

• Device for steering. The following subtypes are defined.

  • Steering device that reports acceleration and brake pedal values from a single axis.

  • Steering device that reports acceleration and brake pedal values from separate axes.

  • Hand-held steering device.

  • Steering device that does not provide the minimum number of device objects for action mapping.

  • Steering device that reports acceleration, brake, and clutch pedal values from separate axes.

• Controller for flight simulation. The following subtypes are defined.

  • Flight controller that does not provide the minimum number of device objects for action mapping.

  • Flight device based on a remote control for model aircraft.

  • Joystick.

  • Yoke.

• Gamepad. The following subtypes are defined.

  • Gamepad that does not provide the minimum number of device objects for action mapping.

  • Standard gamepad that provides the minimum number of device objects for action mapping.

  • Gamepad that can report x-axis and y-axis data based on the attitude of the controller.

• Joystick. The following subtypes are defined.

  • Joystick that does not provide the minimum number of device objects for action mapping.

  • Standard joystick that provides the minimum number of device objects for action mapping.

• Keyboard or keyboard-like device. The following subtypes are defined.

  • Subtype could not be determined.

  • IBM PC/XT 83-key keyboard.

  • Olivetti 102-key keyboard.

  • IBM PC/AT 84-key keyboard.

  • IBM PC Enhanced 101/102-key or Microsoft Natural keyboard.

  • Nokia 1050 keyboard.

  • Nokia 9140 keyboard.

  • Japanese NEC PC98 keyboard.

  • Japanese NEC PC98 laptop keyboard.

  • Japanese NEC PC98 106-key keyboard.

  • Japanese 106-key keyboard.

  • Japanese AX keyboard.

  • Japanese J3100 keyboard.

• A mouse or mouse-like device (such as a trackball). The following subtypes are defined.

  • Mouse that returns absolute axis data.

  • Fingerstick.

  • Touchpad.

  • Trackball.

  • Traditional mouse.

  • Subtype could not be determined.

• Remote-control device. The following subtype is defined.

  • Subtype could not be determined.

• Screen reference. The following subtypes are defined.

  • Unknown subtype.

  • Light gun.

  • Light pen.

  • Touch screen.

• Specialized device with functionality unsuitable for the main control of an application, such as pedals used with a wheel. The following subtypes are defined.

  • Secondary handheld controller.

  • Device whose primary function is to report acceleration and brake pedal values from a single axis.

  • Device whose primary function is to report acceleration and brake pedal values from separate axes.

  • Device that tracks hand movement.

  • Device that tracks head movement.

  • Device with rudder pedals.

  • Device that reports gear selection from an axis.

  • Device that reports gear selection from button states.

  • Device whose primary function is to report at least two throttle values. It may have other controls.

  • Device whose primary function is to report acceleration, brake, and clutch pedal values from separate axes.

  • Device whose primary function is to report a single throttle value. It may have other controls.

  • Unknown subtype.

Versions of DirectInput earlier than DirectX 8.0 have a somewhat different scheme of device types and subtypes. See the DIDEVTYPExxx defines in Dinput.h.

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.

supersedes the IDirectInput, IDirectInput2, and IDirectInput7 interfaces used in earlier versions of Microsoft DirectX.

is an interface to a new class of object, represented by the class identifier CLSID_DirectInput8, and cannot be obtained by calling QueryInterface on an interface to objects of class CLSID_DirectInput. Instead, obtain the interface by using the DirectInput8Create function.

The LPDIRECTINPUT8 type is defined as a reference to the interface:

 typedef struct     *LPDIRECTINPUT8;	
            

Calling this method with pUnkOuter = null is equivalent to creating the object by CoCreateInstance (&CLSID_DirectInputDevice, null, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice) and then initializing it with Initialize.

Calling this method with pUnkOuter != null is equivalent to creating the object by CoCreateInstance (&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInputDevice). The aggregated object must be initialized manually.

All installed devices can be enumerated, even if they are not present. For example, a flight stick might be installed on the system but not currently plugged into the computer. Set the dwFlags parameter to indicate whether only attached or all installed devices should be enumerated. If the flag is not present, all installed devices are enumerated.

A preferred device type can be passed as a dwDevType filter so that only the devices of that type are enumerated.

On Microsoft Windows XP, DirectInput enumerates only one mouse and one keyboard device, referred to as the system mouse and the system keyboard. These devices represent the combined output of all mice and keyboards respectively on a system. For information about how to read from multiple mice or keyboards individually on Windows XP, see the WM_INPUT documentation.

The keyboard and mouse are enumerated last.

Use the DIDFT_GETTYPE macro to extract the effect type from the dwEffType flags.

A "joystick type" describes how DirectInput should communicate with the device and how it should report device data. For example, "A Frobozz Industries SuperStick 5X is a three-axis, five-button joystick with the third axis reported as the first bit on the second port."

DirectInput comes with the following predefined joystick types, all with axes in their default locations:

• Two-axis, two-button joystick.

• Two-button game pad.

• Two-button flight yoke.

• Two-button flight yoke with throttle.

• Three-axis, two-button joystick.

• Three-axis, four-button joystick.

• Four-button game pad.

• Four-button flight yoke.

• Four-button flight yoke with throttle.

If the joystick type has the JOY_HWS_ISGAMEPORTDRIVER flag set in the dwFlags member of the JOYHWSETTINGS structure, then the wszCallout member of the DIJOYTYPEINFO structure contains the name of a driver that can be used as a global driver. The joystick type should be shown on the list of global drivers and not shown on the list of joystick types that can be assigned.

New in DirectX 8.0

The dwFlags2 member was added to the DIJOYCONFIG structure. This member carries information that controls how DirectInput enumerates the device to applications. The dwFlags2 member carries device type and subtype override flags in the low word, and device enumeration "hiding" flags in the high word. The device type and subtype override flags control how DirectInput portrays your device to applications that use DirectInput. These are the same flags that applications receive from DirectInput during device enumeration. For example, if your device is described in its firmware as a telephony device, it would not normally be enumerated to games because telephony devices aren't considered relevant to games. However, if you used and DI8DEVTYPEDEVICECONTROL_COMMSSELECTION to describe this device, DirectInput overrides the data it retrieves from the firmware and enumerates the device to games.

The high word of dwFlags2 can be set to contain flags that scope how DirectInput enumerates the device to DirectInput applications. For example, some devices declare multiple top-level HID collections. Such a device might declare that it can act as a keyboard, a mouse, and a joystick all in one. Generally, one or more of these top-level collections is merely a phantom device, which shouldn't be enumerated to games. For this device, the high word of dwFlags2 could be set to a combination of the JOYTYPE_HIDEACTIVE, JOYTYPE_MOUSEHIDE, and JOYTYPE_KEYBHIDE flags. The JOYTYPE_HIDEACTIVE flag indicates that DirectInput should not enumerate the device by all its types. The JOYTYPE_MOUSEHIDE and JOYTYPE_KEYBHIDE flags also present in the high word indicate to DirectInput that enumeration of the phantom mouse and keyboard on the device should be suppressed. Note that applications can include the (described in the Microsoft Windows SDK documentation) flag to enumerate devices, even if they are hidden.

The following alternate names are available:

For information about Japanese keyboards, see DirectInput and Japanese Keyboards.

The data at a given offset is associated with a keyboard key. Typically, these values are used in the dwOfs member of the , DIOBJECTDATAFORMAT or structures, or as indices when accessing data within the array using array notation.

The data at a given offset is associated with a device object (button or axis). Typically, these values are used in the dwOfs member of the , DIOBJECTDATAFORMAT or structures.

The DirectInput object created by this function is implemented in Dinput8.dll. Versions of interfaces earlier than DirectX 8.0 cannot be obtained in this implementation.

To create a DirectX 8.x interface with the latest DirectX SDK without using CoCreateInstance:

1. Set "#define 0x0800" before the include statement for Dinput8.h.

2. Call DirectInput8Create instead of DirectInputCreateEx.

3. Link to the Dinput8.lib library instead of Dinput.lib.

To create a DirectX 8.x interface with the DirectX 8.x SDK without using CoCreateInstance:

1. Call DirectInput8Create instead of DirectInputCreateEx.

2. Link to the Dinput8.lib library instead of Dinput.lib.

To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK without using CoCreateInstance:

1. Set "#define 0x0700" before the include statement for dinput.h.

2. Call DirectInputCreateEx instead of DirectInput8Create.

3. Link to the Dinput.lib library instead of Dinput8.lib.

To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:

1. Call CoInitializeEx.

2. Call CoCreateInstance using CLISID_DirectInput.

3. Use IDirectInput7::Initialize to initialize the DirectInput object.

To create a DirectX 8.x or DirectX 9.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:

1. Call CoInitializeEx.

2. Call CoCreateInstance using CLISID_DirectInput8.

3. Use to initialize the DirectInput object.

Calling the function with pUnkOuter = null is equivalent to creating the object through CoCreateInstance( &CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput8W, lplpDirectInput), then initializing it with .

Calling the function with pUnkOuter != null is equivalent to creating the object through CoCreateInstance( &CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput). The aggregated object must be initialized manually.