| Microsoft DirectX 8.1 (Visual Basic) |
Acquiring a Microsoft® 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 unacquire a device many times.
In certain cases, depending on the cooperative level, a device is unacquired automatically whenever the application moves to the background. The mouse is automatically unacquired when the user clicks a menu, because at this point Microsoft Windows® assumes control of 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 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. Or 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.
Second, because your application can alter the properties of the device, without safeguards DirectInput would have to check the properties each time you wanted to retrieve data. This would be very inefficient. Even worse, a potential disaster could happen such as a hardware interrupt accessing a data buffer just as you were changing the buffer size. 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.
Because your application might unacquire a device unexpectedly, especially if you have set the exclusive cooperative level, you must 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 Windows to acquire the mouse, you must release it. The ScrawlB sample responds to a right-click button by unacquiring the mouse, putting the Windows cursor in the same spot as its own, displaying a shortcut menu, and letting Windows handle the input until a menu choice is made.