| Platform SDK: DirectX |
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 can acquire and unacquire a device many times.
In certain cases, depending on the cooperative level, a device can be unacquired automatically whenever the application moves to the background. The mouse is automatically unacquired when the user clicks on a menu, because at this point Windows takes over the device.
You must unacquire 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:
First, DirectInput must be able to tell the application when the flow of data from the device has been interrupted by the system. For instance, if the user has switched to another application with ALT+TAB and 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 presses the SHIFT key, and while continuing to press it, 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, allows it to recover from these conditions.
Second, because your application can alter the properties of the device, without safeguards DirectInput would have to check the properties each time that you wanted to retrieve data. This would be very inefficient. Even worse, this could cause a hardware interrupt accessing a data buffer when the buffer size is being changed. Therefore, DirectInput requires your application to unacquire the device before changing 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.
Since the most common cause of losing a device is that your application moves to the background, you might want to reacquire devices whenever your application is activated. Be careful, however, about relying on a WM_ACTIVATE handler at startup time. The first WM_ACTIVATE message will probably arrive when your window is being initialized, before DirectInput has been set up. To ensure that the device is acquired at startup, call IDirectInputDevice7::Acquire as soon as the device has been initialized.
Even acquiring the device on activation of your program window might not cover all cases in which a device is unacquired, especially for devices other than the standard mouse or keyboard. Because your application might unacquire a device unexpectedly, you need a mechanism for checking the acquisition state before attempting to get data from the device. The Scrawl sample application does this in the Scrawl_OnMouseInput function, in which a DIERR_INPUTLOST error triggers a message to reacquire the mouse. (See also Tutorial 2: Using the Mouse.)
Because your application might unacquire a device unexpectedly, especially if you have set the exclusive cooperative level, ensure that the application tracks the state of acquisition. One technique is to check for the DIERR_INPUTLOST error after attempting to retrieve data. If this error is raised, you know the device has been unacquired. If your application is getting input in response to event notification, an event is signaled when acquisition is lost.
See the ScrawlB sample for more information about how to manage device acquisition in exclusive mode.
Attempting to reacquire a device that is already acquired does no harm. Redundant calls to Acquire are ignored, and the device can always be unacquired with a single call to Unacquire.
Windows does not have access to the mouse when your application is using it in exclusive mode. If you want to let Windows have the mouse, you must release it. There is an example in the Scrawl sample that responds to a click of the right button by unacquiring the mouse, putting the Windows cursor in the same spot as its own, popping up a context menu, and letting Windows handle the input until a menu choice is made.
Windows does not have access to the mouse when your application is using it in exclusive mode. If you want to let Windows have the mouse, you must release it. There is an example in the ScrawlB sample that responds to a click of the right button by unacquiring the mouse, putting the Windows cursor in the same spot as its own, popping up a context menu, and letting Windows handle the input until a menu choice is made.