Platform SDK: DirectX |
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.
The DirectInput QuickTest application supplied with the DirectX SDK 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 tabbed page. On the Data tabbed page, you then see immediate data on the left and buffered data on the right.
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:
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.
See also: