Introduction to DirectInput

DirectInput is an API for input devices including the mouse, keyboard, joystick, and other game controllers, as well as for force-feedback (input/output) devices.

This topic provides a brief overview of the capabilities of DirectInput and how to set it up in an application. For a more comprehensive view of how DirectInput works, see Understanding DirectInput. For a step-by-step guide to using the DirectInput API, see Using DirectInput.

The Power of DirectInput

DirectInput enables an application to retrieve data from input devices even when the application is in the background. It also provides full support for any type of input device, as well as for force feedback.

Through action mapping, applications can retrieve input data without needing to know what kind of device is being used to generate it.

The extended services and improved performance of DirectInput make it a valuable tool for games, simulations, and other real-time interactive applications running under Windows.

DirectInput does not provide any advantages for applications that use the keyboard for text entry or the mouse for navigation. For more information, see Interaction with Windows.

Getting Started with DirectInput

This topic is an overview of what is involved in setting up and using DirectInput in a simple application.

For details and examples of these steps, see Using DirectInput.

Note

To understand DirectInput, it is essential to understand the following terms:

DirectInput object

The root DirectInput interface.

Device

A keyboard, mouse, joystick, or other input device.

DirectInputDevice object

Code representing a keyboard, mouse, joystick, or other input device.

Device object

Code representing a key, button, trigger, and so on found on a DirectInput device object. Also called device object instance.

The following steps represent a simple implementation of DirectInput in which the application takes responsibility for ascertaining what device object (button, axis, and so on) generated each item of data.

1. Create the DirectInput object.

   You use methods of this object to enumerate devices and create DirectInput device objects.

2. Enumerate devices.

   This is not an essential step if you intend to use only the system mouse or keyboard. To ascertain what other input devices are available on the user's system, have DirectInput enumerate them. Each time DirectInput finds a device that matches the criteria you set, it gives you the opportunity to examine the device's capabilities. It also retrieves a unique identifier that you can use to create a DirectInput device object representing the device.

3. Create a DirectInputDevice object for each device you want to use.

   To do this, you need the unique identifier retrieved during enumeration. For the system mouse or keyboard, you can use a standard globally unique identifier (GUID).

4. Set up the device.

   For each device, first set the cooperative level, which determines the way the device is shared with other applications or the system. You must also set the data format used for identifying device objects, such as buttons and axes, within data packets. If you intend to retrieve buffered data-that is, events rather than states-you also need to set a buffer size. Optionally, at this stage you can retrieve information about the device and tailor the application's behavior accordingly. You can also set properties such as the range of values returned by joystick axes.

5. Acquire the device.

   At this stage you tell DirectInput that you are ready to receive data from the device.

6. Retrieve data.

   At regular intervals, typically on each pass through the message loop or rendering loop, get either the current state of each device or a record of events that have taken place since the last retrieval. If you prefer, you can have DirectInput notify you whenever an event occurs.

7. Act on the data.

   The application can respond either to the state of buttons and axes or to events such as a key being pressed or released.

8. Close DirectInput.

   Before exiting, your application should unacquire all devices and release them, then release the DirectInput object.

This is not the only approach to implementing DirectInput. To take advantage of the great variety of input devices available now and later, and to simplify configuration for the user, you can use action mapping.

By setting an action map for a device, you let DirectInput decide which device object to use for each application action. For example, instead of specifying that the throttle in your racing game must always be controlled by the y-axis, you can create an action called AXIS_THROTTLE and have DirectInput assign that action to the most appropriate axis available on the device. When you retrieve events, you identify them by their associated actions rather than by the device objects that generated them.