An application retrieves immediate data by calling the IDirectInputDevice7::GetDeviceState method. As the name implies, this method 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. If the user has pressed and released a button between two calls to GetDeviceState, your application does not know anything about it. On the other hand, if the user is holding a button down, GetDeviceState continues reporting button down until the user releases it.

This way of reporting the device state is different from the way that Windows reports events with one-time messages such as WM_LBUTTONDOWN; it is more like 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 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 structure in the buffer. If the buffer overflows, new data is lost. Your application reads the buffer with a call to IDirectInputDevice7::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.

To get buffered data, you must first set the buffer size with the IDirectInputDevice7::SetProperty method. (See the example in 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 or WORDs.

Check the value of the pdwInOut parameter after a call to the GetDeviceData method. The number of items retrieved from the buffer is returned in this variable.

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

For examples of retrieving buffered data, see IDirectInputDevice7::GetDeviceData.

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

• DirectInputDevice.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 DirectInputDevice.SetCommonDataFormat.)
• DirectInputDevice.GetDeviceStateMouse. For devices that retrieve data in a DIMOUSESTATE type.
• DirectInputDevice.GetDeviceStateJoystick. For devices that retrieve data in a DIJOYSTATE type.
• DirectInputDevice.GetDeviceStateJoystick2. For devices that retrieve data in a DIJOYSTATE2 type.
• DirectInputDevice.GetDeviceState. For devices that use custom data formats, as set by using DirectInputDevice.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. If the user has pressed and released a button between two calls to the method, your application does not know anything about it. On the other hand, if the user is holding a button down, the method continues reporting button down until the user releases it.

This way of reporting the device state is different from the way Visual Basic reports events with one-time events like 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 DirectInputDevice.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 DirectInputDevice.SetProperty 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 or WORDs.

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 DirectInputDevice.Poll method. For more information, see Polling and Events.