Acquiring Devices

Acquiring a DirectInput device means giving your application access to it. As long as a device is acquired, DirectInput is making its data available to your application. If the device is not acquired, you can manipulate its characteristics but not obtain any data.

Acquisition is not permanent. Your application might acquire and release a device many times.

In certain cases, depending on the cooperative level, a device is released automatically whenever the application moves to the background. The mouse is automatically released when the user clicks a menu, because at this point, Windows assumes control of the device.

You must release a device before changing its properties. The only exception is that you can change the gain for a force-feedback device while it is in an acquired state.

The acquisition mechanism is needed for two reasons:

  1. DirectInput must be able to tell the application when the flow of data from the device has been interrupted by the system. For example, if the user has switched to another application with ALT+TAB and has used the input device in that application, your application needs to know that the input no longer belongs to it and that the state of the buffers might have changed.

    Consider an application with the DISCL_FOREGROUND cooperative level. The user holds down the SHIFT key and switches to another application. Then the user releases the key and switches back to the first application. As far as the first application is concerned, the SHIFT key is still down. The acquisition mechanism, by telling the application that input was lost, enables it to recover from these conditions.

  2. Your application can alter the properties of the device, and without safeguards, DirectInput would need to check the properties each time you wanted to retrieve data. This would be very inefficient and could allow for disaster; for example, a hardware interrupt accessing a data buffer just as you were changing the buffer size.

    Therefore, DirectInput requires that your application release the device before changing its properties. When you reacquire it, DirectInput checks the properties and decides on the optimal way of transferring data from the device to the application. This is done only once, so the data retrieval methods can be very fast.

Windows does not have access to the mouse when your application is using it in exclusive mode. If you want Windows to acquire the mouse, you must release it.