This chapter is from the book
This chapter is from the book
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.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
} DIMOUSESTATE, *LPDIMOUSESTATE;
// 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
} DIJOYSTATE, *LPDIJOYSTATE;
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);
Purpose:
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:
Example:
if (!DInput_Init())
{ /* error */ }
Function Prototype:
void DInput_Shutdown(void);
Purpose:
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:
Example:
DInput_Shutdown();
Function Prototype:
DInput_Init_Keyboard(void);
Purpose:
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:
Example:
if (!DInput_Init_Keyboard())
{ /* error */ }
Function Prototype:
int DInput_Init_Mouse(void);
Purpose:
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:
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
Purpose:
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:
Example:
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);
Purpose:
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:
Example:
// initialize the DirectInput system DInput_Init(); // initialize all input devices and acquire them DInput_Init_Joystick(); DInput_Init_Mouse(); DInput_Init_Keyboard(); // input loop ....do work here // now done... // first release all devices, order is unimportant DInput_Release_Joystick(); DInput_Release_Mouse(); DInput_Release_Keyboard(); // shutdown DirectInput DInput_Shutdown();
Function Prototype:
int DInput_Read_Keyboard(void);
Purpose:
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.
Example:
// read the keyboard
if (!DInput_Read_Keyboard())
{ /* error */ }
// now test the state data
if (keyboard_state[DIK_RIGHT])
{ /* move ship right */ }
else
if (keyboard_state[DIK_LEFT])
{ /* move ship left */ }
Table 3.2 The DirectInput Keyboard State Constants
|
Symbol |
Meaning |
|
DIK_ESCAPE |
The Esc key |
|
DIK_0-9 |
Main keyboard 0–9 |
|
DIK_MINUS |
Minus key |
|
DIK_EQUALS |
Equals key |
|
DIK_BACK |
Backspace key |
|
DIK_TAB |
Tab key |
|
DIK_A-Z |
Letters A–Z |
|
DIK_LBRACKET |
Left bracket |
|
DIK_RBRACKET |
Right bracket |
|
DIK_RETURN |
Return/Enter on main keyboard |
|
DIK_LCONTROL |
Left control |
|
DIK_LSHIFT |
Left shift |
|
DIK_RSHIFT |
Right shift |
|
DIK_LMENU |
Left Alt |
|
DIK_SPACE |
Spacebar |
|
DIK_F1-15 |
Function keys 1–15 |
|
DIK_NUMPAD0-9 |
Numeric keypad keys 0–9 |
|
DIK_ADD |
+ on numeric keypad |
|
DIK_NUMPADENTER |
Enter on numeric keypad |
|
DIK_RCONTROL |
Right control |
|
DIK_RMENU |
Right Alt |
|
DIK_HOME |
Home on arrow keypad |
|
DIK_UP |
UpArrow on arrow keypad |
|
DIK_PRIOR |
PgUp on arrow keypad |
|
DIK_LEFT |
LeftArrow on arrow keypad |
|
DIK_RIGHT |
RightArrow on arrow keypad |
|
DIK_END |
End on arrow keypad |
|
DIK_DOWN |
DownArrow on arrow keypad |
|
DIK_NEXT |
PgDn on arrow keypad |
|
DIK_INSERT |
Insert on arrow keypad |
|
DIK_DELETE |
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);
Purpose:
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:
Example:
// read the mouse
if (!DInput_Read_Mouse())
{ /* error */ }
// move cursor
cx+=mouse_state.lX;
cy+=mouse_state.lY;
// test if left button is down
if (mouse_state.rgbButtons[0])
Draw_Pixel(cx,cy,col,buffer,pitch);
Function Prototype:
int DInput_Read_Joystick(void);
Purpose:
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:
Example:
// read the joystick data
if (!DInput_Read_Joystick())
{ /* error */ }
// move the ship
ship_x+=joy_state.lX;
ship_y+=joy_state.lY;
// 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.
NOTE
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!