Home > Articles

  • Print
  • + Share This
This chapter is from the book

The T3DLIB2 DirectX Input System

Writing a simple set of wrapper functions around DirectInput is almost a no-brainer. Well, it takes some brains, but for the most part it's fairly easy. All we need to do is create an API with a very simple interface and few parameters. The interface should support the following minimal functionality:

  • Initialize the DirectInput system

  • Set up and acquire the keyboard, mouse, and joystick—or any subset

  • Read data from any of the input devices

  • Shut down, unacquire, and release everything

I have created such an API, and it's available in T3DLIB2.CPP|H on the CD. The API does everything you need to initialize DirectInput and read any device. Before reviewing the functions, take a look at Figure 3.11—it depicts the relationship between each device and the data flow.

Figure 3.11Figure 3.11 The DirectInput software system.

Here are the globals for the library:

LPDIRECTINPUT8  lpdi;  // dinput object
LPDIRECTINPUTDEVICE8 lpdikey; // dinput keyboard
LPDIRECTINPUTDEVICE8 lpdimouse; // dinput mouse
LPDIRECTINPUTDEVICE8 lpdijoy; // dinput joystick
GUID joystickGUID; // guid for main joystick
char joyname[80]; // name of joystick

// all input is stored in these records
UCHAR keyboard_state[256]; // contains keyboard state table
DIMOUSESTATE mouse_state; // contains state of mouse
DIJOYSTATE joy_state;  // contains state of joystick
int joystick_found;  // tracks if stick is plugged in

Input from the keyboard is placed in keyboard_state[], the mouse data is stored in mouse_state, and the joystick data is stored in joy_state by the input system. The structure of each of these records is the standard DirectInput device state structures (except for the keyboard; it's just a Boolean array of BYTES) as shown in the following:

// for the mouse data
typedef struct DIMOUSESTATE {
 LONG lX; // x-axis
 LONG lY; // y-axis
 LONG lZ; // z-axis
 BYTE rgbButtons[4]; // state of the buttons

// for the joystick data
typedef struct DIJOYSTATE {
 LONG lX; // x-axis
 LONG lY; // y-axis
 LONG lZ; // z-axis
 LONG lRx; // rotation about x-axis
 LONG lRy; // rotation about y-axis
 LONG lRz; // rotation about z-axis
 LONG rglSlider[2]; // u,v slider positions
 DWORD rgdwPOV[4]; // point of view hat state
 BYTE rgbButtons[32]; // state of buttons 0..31

In general, the mouse and joystick are roughly equivalent as far as the x,y position goes; that is, you access them via the fields lX, lY, and the buttons are BOOLEANs in rgbButtons[]. Let's get to the functions. The variable joystick_found is a BOOLEAN that is set when you request joystick access. If a joystick is found, it is TRUE, otherwise, it's FALSE. With it, you can conditional block out code that uses the joystick. So without further ado, here is the new API:

Function Prototype:

int DInput_Init(void);


DInput_Init() initializes the DirectInput input system. It creates the main COM object and returns TRUE if successful and FALSE otherwise. And of course, the global lpdi will be valid. The function does not create any devices, though. Here's an example of initializing the input system:


if (!DInput_Init())
 { /* error */ }

Function Prototype:

void DInput_Shutdown(void);


DInput_Shutdown() releases all the COM objects and any resources allocated during the call to DInput_Init(). Normally, you would call DInput_Shutdown() at the very end of your application after you have released all the input devices themselves—which we'll get to shortly. Anyway, here's an example of shutting down the input system:



Function Prototype:



DInput_Init_Keyboard() initializes and acquires the keyboard. This should always work and return TRUE, unless another DirectX application has taken over in a really uncooperative way. Here's an example:


if (!DInput_Init_Keyboard())
 { /* error */ }

Function Prototype:

int DInput_Init_Mouse(void);


DInput_Init_Mouse() initializes and acquires the mouse. The function takes no parameters and returns TRUE if successful and FALSE otherwise. But it should always work, unless a mouse isn't plugged in or there's another DirectX application that has totally taken over! If everything goes well, lpdimouse becomes the valid interface pointer. Here's an example:


if (!DInput_Init_Mouse()) { /* error */ }

Function Prototype:

int DInput_Init_Joystick(int min_x=-256, // min x range
    int max_x=256, // max x range
    int min_y=-256, // min y range
    int max_y=256, // max y range
    int dead_zone=10); // dead zone in percent


DInput_Init_Joystick() initializes the joystick device for use. The function takes five parameters that define the x-y range of motion of the data sent back from the joystick and the dead zone with a percentage. If you want to use the defaults of -256 to 256 and 10% dead zone for each axis, you don't need to send parameters because they have default values (C++ thing). If the call returns back a TRUE, a joystick was found and it has been set up, initialized, and acquired. After the call, the interface pointer lpdijoy will be valid if you need it for anything. In addition, the string joyname[] will contain the "friendly" name of the joystick device, such as "Microsoft Sidewinder Pro," and so on.

Here's an example of initializing the joystick and setting its x-y ranges to -1024 to 1024 with a 5% dead zone:


if (!DInput_Init_Joystick(-1024, 1024, -1024, 1024, 5))
 { /* error */ }

Function Prototype(s):

void DInput_Release_Joystick(void);
void DInput_Release_Mouse(void);
void DInput_Release_Keyboard(void);


DInput_Release_Joystick(), DInput_Release_Mouse(), and DInput_Release_Keyboard() release each of the respective input devices when you are done with them. The functions can be called even if you haven't initialized the respective device, so you can just call them all at the end of your application if you want. Here's a complete example of starting up the DirectInput system, initializing all the devices and then releasing them and shutting down:


// initialize the DirectInput system

// initialize all input devices and acquire them

// input loop ....do work here
// now done...

// first release all devices, order is unimportant

// shutdown DirectInput

Function Prototype:

int DInput_Read_Keyboard(void);


DInput_Read_Keyboard() scans the keyboard state and places the data in keyboard_state[], which is an array of 256 BYTEs. This is the standard DirectInput keyboard state array, so you must use the DirectInput key constants DIK_* if you want to make sense of it. If a key is pressed, the array value will be 0x80. Here's an example of testing whether the right and left keys are down using the manifest constants in DirectInput—which you can look up in the SDK or the abridged Table 3.2 following.


// read the keyboard
if (!DInput_Read_Keyboard())
 { /* error */ }

// now test the state data
if (keyboard_state[DIK_RIGHT])
 { /* move ship right */ }
if (keyboard_state[DIK_LEFT])
 { /* move ship left */ }

Table 3.2 The DirectInput Keyboard State Constants




The Esc key


Main keyboard 0–9


Minus key


Equals key


Backspace key


Tab key


Letters A–Z


Left bracket


Right bracket


Return/Enter on main keyboard


Left control


Left shift


Right shift


Left Alt




Function keys 1–15


Numeric keypad keys 0–9


+ on numeric keypad


Enter on numeric keypad


Right control


Right Alt


Home on arrow keypad


UpArrow on arrow keypad


PgUp on arrow keypad


LeftArrow on arrow keypad


RightArrow on arrow keypad


End on arrow keypad


DownArrow on arrow keypad


PgDn on arrow keypad


Insert on arrow keypad


Delete on arrow keypad

(Note: bolded entries simply mean to follow the sequence. For example, DIK_0-9 means that there are constants DIK_0, DIK_1, DIK_2, and so forth.)

Function Prototype:

int DInput_Read_Mouse(void);


DInput_Read_Mouse() reads the relative mouse state and stores the result in mouse_state, which is a DIMOUSESTATE structure. The data is in relative delta mode. In most cases, you'll only need to look at mouse_state.lX, mouse_state.lY, and rgbButtons[0..2], which are BOOLEANs for the three mouse buttons. Here's an example of reading the mouse and using it to move a cursor around and draw:


// read the mouse
if (!DInput_Read_Mouse())
 { /* error */ }

// move cursor

// test if left button is down
if (mouse_state.rgbButtons[0])

Function Prototype:

int DInput_Read_Joystick(void);


DInput_Read_Joystick() polls the joystick and then reads the data into joy_state, which is a DIJOYSTATE structure. Of course, if there isn't a joystick plugged in, the function returns FALSE and joy_state will be invalid, but you get the idea. If successful, joy_state contains the state information of the joystick. The data returned will be in the range you previously set for each axis, and the button values are BOOLEANs in rgbButtons[]. As an example, here's how you would use the joystick to move a ship right and left and the first button to fire:


// read the joystick data
if (!DInput_Read_Joystick())
 { /* error */ }

// move the ship

// test for trigger
if (joy_state.rgbButtons[0])
 { // fire weapon // }

Of course, your joystick might have a lot of buttons and multiple axes. In this case, you can use the other fields of joy_state as defined in the DIJOYSTATE DirectInput structure.


Even though we are using the IDIRECTINPUTDEVICE8 interface, we don't need to use the DIJOYSTATE2 structure. This is only for force feedback devices.

At this point, we are ready to take a look at one of the subsystems that most game programmers hate to deal with—sound and music! But under DirectX, along with my wrapper functions, making sound effects and playing music is so easy it's actually fun!

  • + Share This
  • 🔖 Save To Your Account