DirectInput supplies two types of data: buffered and immediate. Buffered data is a record of events that is stored until an application retrieves it. Immediate data is a snapshot of the current state of a device.
You might use immediate data in an application that is concerned only with the current state of a device: for example, a flight combat simulation that responds to the current position of the joystick and a pressed "fire" button. Buffered data might be the better choice where events are more important than states: for example, in an application that responds to movement of the mouse and button clicks.
You get immediate data with the IDirectInputDevice::GetDeviceState method. As the name implies, this method simply returns the current state of the device: for example, whether each button is up or down. The method provides no data about what has happened with the device since the last call, apart from implicit information you can derive by comparing the current state with the last one. If the user manages to press and release a button between two calls to GetDeviceState, your application won't know anything about it. On the other hand, if the user is holding a button down, GetDeviceState will continue reporting "button down" until the user releases it.
This way of reporting the device state is different from the way Windows reports events with one-time messages like WM_LBUTTONDOWN; it is more akin to the results from the Win32 GetKeyboardState function. If you are polling a device with GetDeviceState, you are responsible for determining what constitutes a button click, a double-click, a single keystroke, and so on, and for ensuring that your application doesn't keep responding to a button-down or key-down state when it's not appropriate to do so.
With buffered data, events are stored until you're ready to deal with them. Every time a button or key is pressed or an axis is moved, information about the event is placed in a DIDEVICEOBJECTDATA structure in the buffer. If the buffer overflows, new data is lost. Your application reads the buffer with a call to IDirectInputDevice::GetDeviceData. You can read any number of items at a time.
Reading an item normally deletes it from the buffer, but you also have the choice of peeking without deleting.
In order to get buffered data you must first set the buffer size with the IDirectInputDevice::SetProperty method. (See the example under Device Properties.) You set the buffer size before acquiring the device for the first time. For reasons of efficiency, the default size of the buffer is zero. You will not be able to obtain buffered data unless you change this value.
Note The size of the buffer is measured in items of data for that type of device, not in bytes or words.
You should check the value of the pdwInOut parameter after a call to the GetDeviceData method. The number of items actually retrieved from the buffer is returned in this variable.
The DIQuick application supplied with the DirectX code samples in the Platform SDK Reference lets you see both immediate and buffered data from a device. After you create the device in the application window, set its properties on the Mode page. Now, on the Data page, you see immediate data on the left and buffered data on the right.
Note For devices that do not generate interrupts, such as analog joysticks, DirectInput does not obtain any data until you call the IDirectInputDevice2::Poll method. For more information, see Polling and Events.
For examples of retrieving buffered data, see IDirectInputDevice::GetDeviceData.
See also: