Buffered and Immediate Data

Microsoft DirectX 8.1 (Visual Basic)

Buffered and Immediate Data

Microsoft® DirectInput® supplies two types of data: buffered and immediate. Buffered data is a record of events that are stored until an application retrieves them. 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 the state of one or more buttons. 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 can also use both types of data, as you might, for example, if you wanted to get immediate data for joystick axes but buffered data for the buttons.

Note If you are using Action Mapping, you will want to retrieve buffered data because the buffered data packets contain the application-defined data associated with the input. Doing so means that you are responsible for tracking the position of absolute axes, since events but not states are reported in buffered data packets.

An application retrieves immediate data by calling one of the following methods:

DirectInputDevice8.GetDeviceStateKeyboard. For devices that retrieve data in a DIKEYBOARDSTATE type. (For this and the following three methods, the data format must have been set by using DirectInputDevice8.SetCommonDataFormat.)
DirectInputDevice8.GetDeviceStateMouse. For devices that retrieve data in a DIMOUSESTATE type.
DirectInputDevice8.GetDeviceStateMouse2. For devices that retrieve data in a DIMOUSESTATE2 type.
DirectInputDevice8.GetDeviceStateJoystick. For devices that retrieve data in a DIJOYSTATE type.
DirectInputDevice8.GetDeviceStateJoystick2. For devices that retrieve data in a DIJOYSTATE2 type.
DirectInputDevice8.GetDeviceState. For devices that use custom data formats, as set by using DirectInputDevice8.SetDataFormat.

As the names imply, each of these methods 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 that you can derive by comparing the current state with the last one. For example if a user presses and releases a button between two calls to the method, your application will never be given this input. On the other hand, if the user is holding a button down, the method continues reporting that fact until the user releases it.

This way of reporting the device state is different from the way Microsoft Visual Basic® reports events with one-time events such as Click and Keydown. If you are polling a device with one of the GetDeviceState methods, 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 does not keep responding to a button-down or key-down state when it is not appropriate to do so.

With buffered data, events are stored until you are 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 type in the buffer. Your application reads the buffer with a call to DirectInputDevice8.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 retrieving without deleting by setting the DIGDD_PEEK flag.

To get buffered data, you must first set the buffer size by using the DirectInputDevice8.SetProperty or DirectInputDevice8.SetActionMap method. (See the example under Device Properties.) Set the buffer size before acquiring the device for the first time. For reasons of efficiency, the default size of the buffer is 0, and you cannot obtain buffered data unless you change this value. The size of the buffer is measured in items of data for that type of device, not in bytes.

The return value of GetDeviceData tells you the number of items retrieved from the buffer. If the buffer has overflowed, no data is returned, and GetDeviceData raises an error, which the application should trap.

Note For devices that do not generate interrupts, such as analog joysticks, DirectInput does not obtain any data until you call the DirectInputDevice8.Poll method. For more information, see Polling and Event Notification.