Getting Keyboard Input

DirectX offers a class dedicated to providing access to user input. This class is called Directlnput. Like all other aspects of DirectX, use of Directlnput is centered on a Device object. The Directlnput device is quite flexible in terms of what it interfaces with. When we create a Directlnput device, we must specify what the device will do. C# has an enumeration called Microsoft.DirectX.DirectInput.SystemGuid that is used to specify the device. Luckily, in C#, if we specify that we are using Microsoft.DirectX.DirectInput , we can refer to the enumeration by just SystemGuid . To create a device capable of communicating with the keyboard, we would use the following line:

 Device KeyboardDev = new Device( SystemGuid.Keyboard ); 

Once we have created the keyboard device, we must configure the way we need it to operate . This includes telling it how it will cooperate with other applications on the computer as well as what data we want it to provide to us. The first is accomplished by a member function called SetCooperativeLevel . This method takes two arguments: a handle to the main window of our application, and a permissions mask that defines how the device will cooperate with the rest of the computer. The window handle must be provided by the application that is using the game engine. It creates the window, so we know that it can provide the handle. The permissions mask is up to us. It is a combination from the enumeration in Table 2 “1.

MICROSOFT.DIRECTX.DIRECTINPUT.COOPERATIVELEVELFLAGS

Background

Exclusive

Foreground

NonExclusive

NoWindowsKey

The Background/Foreground pair is mutually exclusive, as is the Exclusive/ NonExclusive pair. The Foreground option specifies that we want data only when our application has the focus (i.e., it is the active application). The Background option means we want every keystroke, all the time. If we specify Exclusive, we are saying that we want priority. It is still possible to lose access to the keyboard if another application gets the focus and wants Exclusive access as well, but that is about the only time this loss can occur. The NoWindowsKey value specifies that we want to ignore the Windows logo key if it exists on the keyboard. If our game is running full screen, then it is important to include the NoWindowsKey flag because that key will cause our application to lose the focus. A typical call to this method would look like this:

 KeyboardDev.SetCooperativeLevel(m_form, CooperativeLevelFlags..NoWindowsKey   CooperativeLevelFlags.NonExclusive  CooperativeLevelFlags.Foreground); 

The next thing to do is specify the data we will be getting back from the device. Again, we will pass an enumeration value to the method. For the keyboard, the call will be

 KeyboardDev.SetDataFormat(DeviceDataFormat.Keyboard); 

The DeviceDataFormat enumeration is used by all of the devices created by Directlnput. The keyboard format indicates that we want keyboard information, in this case a reference to the KeyboardState class. This class holds the information about which keys are currently pressed.

The configuration of the keyboard device is now complete. The only thing left to do before we can start getting data from the keyboard is to acquire the device. The Acquire method activates the device as we have configured it. To get the key data requires two steps. First we call the Poll method of the device that causes the device to get the data from the hardware. Now that the device has the data, we simply have to ask for a copy. The following statements copy the byte array from the device into a local copy that we can manipulate:

 private KeyboardState m_keydata        = null;  m_keydata = KeyboardDev.GetCurrentKeyboardState(); 

To check the current state of a given button, we index into the byte array and check to see if the most significant bit is set. For example, to check to see if the A key is pressed, we would use the following:

 if ( m_keydata[Key.A] ) 

When our program is exiting, there is one more piece of business to attend to. We must detach our keyboard device from the hardware. This is accomplished by calling the Unacquire method. The common method for doing this is to place the code within a Dispose method of the class implementing the device. Since C# doesn t treat destructors the same way C++ does, the Dispose method is used to explicitly perform cleanup when we are done with a class. In C# object destructors are called when the garbage collection system determines that it is time to reclaim a particular piece of memory. Since we have no control over when this might be, it is preferable to use Dispose from the IDisposable interface.