Platform SDK: DirectX

Polling and Events

There are two ways to find out whether input data is available: polling and event notification.

Polling a device means regularly getting the current state of the device objects or checking the contents of the event buffer. Polling is typically used by real-time games that are never idle, but are constantly updating and rendering the game world.

[C++]

In a C++ application, polling would typically be done within the message loop.

Event notification is suitable for applications like the Scrawl sample that wait for input before doing anything. To use event notification, set up a thread-synchronization object with the Win32 CreateEvent function, and then associate this event with the device by passing its handle to the IDirectInputDevice7::SetEventNotification method. The event is then signaled by DirectInput whenever the state of the device changes. Your application can receive notification of the event with a Win32 function such as WaitForSingleObject, and then respond by checking the input buffer to find out what the event was. For code examples, see the Scrawl sample and IDirectInputDevice7::SetEventNotification.

Some joysticks and other game devices, or particular objects on them, do not generate hardware interrupts and do not return any data or signal any events until you call the IDirectInputDevice7::Poll method. (This behind-the-scenes polling is not to be confused with the kind of application polling just discussed. Poll does not retrieve any data, but merely makes data available.)

To find out whether it is necessary to call Poll each time that you want to retrieve data, first set the data format for the device, then call the IDirectInputDevice7::GetCapabilities method, and check for the DIDC_POLLEDDATAFORMAT flag in the DIDEVCAPS structure.

Do not confuse the DIDC_POLLEDDATAFORMAT flag with the DIDC_POLLEDDEVICE flag. The latter is set if any object on the device requires polling. You can then find out whether this is the case for a particular object by calling the IDirectInputDevice7::GetObjectInfo method and checking for the DIDOI_POLLED flag in the DIDEVICEOBJECTINSTANCE structure.

The DIDC_POLLEDDEVICE flag describes the worst case for the device, not the actual situation. For example, an HID mouse with software-controllable resolution might be marked as DIDC_POLLEDDEVICE because reading the resolution information requires polling. Polling the device under these conditions is pointless if all that you want is the standard button and axis data.

Nevertheless, it does not hurt to call the IDirectInputDevice7::Poll method for any input device. If the call is unnecessary, it has no effect and is very fast.

[Visual Basic]

In a Visual Basic application, polling would typically be done in the Sub Main procedure.

Event notification is suitable for applications such as the ScrawlB sample that wait for input before doing anything. To use event notification, implement DirectXEvent in the form or module in which you want to retrieve data. Then, create an event handle by using DirectX7.CreateEvent, and pass this handle to DirectInputDevice.SetEventNotification. Now, whenever an input event occurs on the device, the DirectXEvent.DXCallback method is called, and in your implementation of this method you can retrieve either the device state or buffered data as you would if you were doing so in Sub Main.

Some joysticks and other game devices, or particular objects on them, do not generate hardware interrupts and do not return any data or signal any events until you call the DirectInputDevice.Poll method. (This behind-the-scenes polling is not to be confused with the kind of application polling just discussed. Poll does not retrieve any data, but merely makes data available.)

To find out whether it is necessary to call Poll each time that you want to retrieve data, first set the data format for the device, then call the DirectInputDevice.GetCapabilities method, and check for the DIDC_POLLEDDATAFORMAT flag in the DIDEVCAPS type.

Do not confuse the DIDC_POLLEDDATAFORMAT flag with the DIDC_POLLEDDEVICE flag. The latter is set if any object on the device requires polling. You can then find out whether this is the case for a particular object by calling the IDirectInputDevice7::GetObjectInfo method to get a DirectInputDeviceObjectInstance object, and then checking for the DIDOI_POLLED flag in the valued returned by DirectInputDeviceObjectInstance.GetFlags.

The DIDC_POLLEDDEVICE flag describes the worst case for the device, not the actual situation. For example, an HID mouse with software-controllable resolution might be marked as DIDC_POLLEDDEVICE because reading the resolution information requires polling. Polling the device under these conditions is pointless if all that you want is the standard button and axis data.

Nevertheless, it does not hurt to call the Poll method for any input device. If the call is unnecessary, it has no effect and is very fast.