As for the piano, the faster her fingers flew over it, the more he marveled. She struck the keys with aplomb and ran from one end of the keyboard to the other without a stop.

--- G. Flaubert

In this tutorial we will set up a basic input handler system to acquire input from keyboard devices.

## Digital Input

In theory, checking whether a key is pressed or not, sounds absolutely easy. Even though Microsoft provides function to get the keyboard state or to query the state of a single key, there are, unfortunately, a few things to consider.

### KeyCodes

Windows stores the state of each keyboard key in an array of 256 bytes. It would obviously be quite difficult to remember which index corresponds to which key, therefor so-called key codes, such as VK_ESCAPE, for the, surprise, escape key, were introduced.

### Quick Fingers

Now polling whether a key is pressed or not should be easy:

if(isKeyDown(VK_SPACE))
// fire missile


Everything seems straight forward, yes? Going back to the by now famous example of the student trying to walk across his University campus without bumping into evil professors of mathematics, we could imagine him wanting to shoot $\varepsilon$-balls (obviously with $\varepsilon > 0$) at the professors to hold their advance for a moment. Now just imagine pressing the space button to throw such an $\varepsilon$-ball, what will happen? If the game is running at $60$fps, the space button would have to be pressed and released within 16ms, which is quite difficult actually, for the action to be detected within a single frame, else, the student might throw several $\varepsilon$-balls on consecutive frames with a single "click". Similarly holding the space bar will result in the student throwing a single $\varepsilon$-ball per frame.

A quite simply but very effective method to solve this problem is to store the state of the keyboard during the previous and the current frame, using two arrays of 256 bytes storing whether a key is down or not, leaving us with four possible states for each key:

Previous Frame Current Frame State
false false Still Released
false true Just Pressed
true false Just Released
true true Still Pressed

Remember the problem of the player desiring to charge his weapon from the previous tutorial? Well, now he can easily do so. Charging the missile would begin once the space key is Just Pressed, and charging continues as long as the space key is Still Pressed, and the devastating missile will be fired upon the player's enemies once the state of the space bar is Just Released. Nice and easy!

To implement this system, a simple enum is enough:

enum KeyState { StillReleased, JustPressed, StillPressed, JustReleased };		// enumeration of all possible key states


With those little difficulties out of the way, it is time to work on the actual input handler.

# The Input Handler

There are four main goals for the input handler:

• It must perform quickly, as input lag is definitely a bad thing.
• It must be easy for new systems to get user input.
• It must be very flexible and capable of handling a wide variety of game situations.
• It must be highly configurable, i.e. players should easily be able to define their own key maps.

Thankfully it is relatively easy to reach those goals with minimal effort. As learned from the previous tutorial and the above example, the input handler will basically be divided into two parts:

1. Raw input gathering from the operating system.
2. Input mapping and dispatching.

During the first part, the input data is gathered from the operating system, either directly, for the keyboard and mouse, or via DirectInput, for Joysticks and Gamepads.

During the second part, the input is mapped to actual game actions, i.e. an input mapper would link space bar is pressed to the correct game command fire missile. That command is then dispatched to the game.

We will build the input handler with those goals in mind.

## Configurability

The first thing to tackle is the configurability. To do so, we first introduce a structure called BindInfo:

// structure to combine key codes and key states
// each game command can have several bindings (chord), i.e. toggle show FPS = 'shift'+'control'+'FPS'
struct BindInfo
{
private:
unsigned int keyCode;		// the actual key code
KeyState keyState;			// the state the above specified key has to be in for the "binding" to become active

public:
// constructors and destructor
BindInfo();
BindInfo(const unsigned int keyCode, const KeyState keyState);
~BindInfo() {};

friend struct GameCommand;
friend class InputHandler;
};


As you can see, this structure simply links a keyboard key to one of the four possible states a key can be in, i.e. a bind info could be that the escape key was just pressed.

Now an event can be mapped to one or multiple key bindings, for example, the event quit game could be mapped to the key VK_ESCAPE with the state JustPressed, or the event toggle fps information could be mapped to the chord of three keys: hold 'control' + 'shift' and press 'F'. To do so, we introduct the GameCommand structure:

// structure to map a single game command to a chord of key strokes (see above)
struct GameCommand
{
private:
std::wstring name;						// human readable name
std::vector<BindInfo> chord;			// the chord mapped to this command, i.e. "shift"+"control"+"F"

public:
// constructors and destructor
GameCommand();
GameCommand(const std::wstring& name, const unsigned int keyCode, const KeyState keyState);
GameCommand(const std::wstring& name, const BindInfo& bi);
GameCommand(const std::wstring& name, const std::vector<BindInfo>& chord);
~GameCommand() {};

friend class InputHandler;
};


This simple structure stores a string defining the name of the command and a vector of key bindings as described above. I am sure you can see how it is not difficult anymore, from here, to change the keys a command is mapped to. We will come back to this in a later tutorial. For now we focus on implementing the input handler class.

## Input Mapping

Mapping keys to events is the job of the input handler class. A game must define all possible game actions, for example in an enumeration:

enum GameCommands { Quit, showFPS };


The input handler then links those events to the above mentioned commands:

std::unordered_map<GameCommands, GameCommand*> keyMap;


Here is the C++-code for the above examples:

void GameInput::setDefaultKeyMap()
{
keyMap.clear();

// define chord for "toggle FPS"
std::vector<input::BindInfo> bi;
bi.push_back(input::BindInfo(VK_SHIFT, input::KeyState::StillPressed));
bi.push_back(input::BindInfo(VK_CONTROL, input::KeyState::StillPressed));
bi.push_back(input::BindInfo('F', input::KeyState::JustPressed));

keyMap[input::GameCommands::Quit] = new input::GameCommand(L"Quit", VK_ESCAPE, input::KeyState::JustPressed);
keyMap[input::GameCommands::showFPS] = new input::GameCommand(L"showFPS", bi);
}


## The Keyboard

With a configurable input handler in place, it is time to learn how to actually acquire keyboard input.

To store the keyboard state from the previous and the current frame, the input handler classes receives two arrays with 256 bytes and a method to fill those arrays with the data of each key:

std::array<BYTE, 256> keyboardStateCurrent;							// the state of the keyboard in the current frame
std::array<BYTE, 256> keyboardStatePrevious;						// the state of the keyboard in the previous frame

util::Expected<void> getKeyboardState();							 // gets the keyboard state, uses GetAsyncKeyState to read the state of all 256 keys


Filling those arrays is done using the GetAsyncKeyState that Microsoft provides us:

SHORT WINAPI GetAsyncKeyState(
_In_ int vKey
);


If the function succeeds, the return value specifies whether the key is currently up or down. If the most significant bit is set, the key is down. We can check for the most significant bit as follows:

inline const bool isPressed(int keyCode) const { return (GetAsyncKeyState(keyCode) & 0x8000) ? 1 : 0; };	// returns true iff the key is down


And the method to actually fill the arrays is now absolutely easy:

void getKeyboardState();							 // gets the keyboard state, uses GetAsyncKeyState to read the state of all 256 keys

void InputHandler::getKeyboardState()
{
// store the old keyboard state
keyboardStatePrevious = keyboardStateCurrent;

// read the current keyboard state
for (int i = 0; i < 256; i++)
keyboardStateCurrent[i] = isPressed(i);
}


We simply store the state from the previous frame and then read the state for the current frame using the isPressed method on each key on the keyboard as defined above.

## Polling

Polling is done, as explained in the previous tutorial, in the main game loop. All we have to do is to acquire the state of the keyboard and to check for active key bindings. To do so, the input handles receives a second unordered map:

std::unordered_map<GameCommands, GameCommand*> activeKeyMap;		// list of all active key maps; game acts on each command in this list


The reasoning behind this is quite simple: after each poll, the input handler runs through the map of all possible key bindings and if it finds an active binding, it copies the address of the active command into the newly introduced map of active commands. The game can then act on those commands later on.

To evaluate which key mappings are active, we make use of the table of possible key states defined at the start of this tutorial as follows:

const KeyState getKeyboardKeyState(const unsigned int keyCode) const;// gets the state of the specified key, depending on its state in the previous and the current frame

const KeyState InputHandler::getKeyboardKeyState(const unsigned int keyCode) const
{
if (keyboardStatePrevious[keyCode] == 1)
if (keyboardStateCurrent[keyCode] == 1)
return KeyState::StillPressed;
else
return KeyState::JustReleased;
else
if (keyboardStateCurrent[keyCode] == 1)
return KeyState::JustPressed;
else
return KeyState::StillReleased;
}


The update method now simply runs through the map of all possible key bindings and check whether their conditions are fulfilled:

void update();														// update the active key map

void InputHandler::update()
{
// clear out any active bindings from the last frame
bool isActive = false;
activeKeyMap.clear();

// loop through the map of all possible actions and find the active key bindings
for (auto x : keyMap)
{
// test chord
isActive = true;
for(auto y : x.second->chord)
{
if (getKeyboardKeyState(y.keyCode) != y.keyState)
{
isActive = false;
break;
}
}
if(isActive)
activeKeyMap.insert(std::pair<GameCommands, GameCommand*>(x.first, x.second));
}

// delegate to the UI

// delegate to the game
}


Note that for a chord to be active, the state of each mapped key must fit the specified key state.

Here is an example of how to use the input handler to acquire input and to react on it:

void DirectXGame::acquireInput()
{
inputHandler->acquireInput();

// act on user input
for (auto x : inputHandler->activeKeyMap)
{
switch (x.first)
{
case input::GameCommands::Quit:
PostMessage(appWindow->getMainWindowHandle(), WM_CLOSE, 0, 0);
break;

case input::GameCommands::showFPS:
showFPS = !showFPS;
break;
}
}
}


#pragma once

/****************************************************************************************
* Author:	Gilles Bellot
* Date:		31/05/2018 - Lenningen - Luxembourg
*
* Desc:		Event based input handler
*
* History:	- 05/06/2018: added keyboard support
****************************************************************************************/

// INCLUDES /////////////////////////////////////////////////////////////////////////////

// Windows and COM
#include <Windows.h>

// c++ containers
#include <unordered_map>
#include <array>
#include <vector>

// c++ strings
#include <iostream>

// bell0bytes utilities
#include "expected.h"

// CLASSES //////////////////////////////////////////////////////////////////////////////
namespace input
{
// enumerate all game commands
enum Events : int;																// enumeration of all standard application events
enum GameCommands : int;														// enumeration of all possible game commands
enum KeyState { StillReleased, JustPressed, StillPressed, JustReleased };		// enumeration of all possible key states

// structure to combine key codes and key states
// each game command can have several bindings (chord), i.e. toggle show FPS = 'shift'+'control'+'FPS'
struct BindInfo
{
private:
unsigned int keyCode;		// the actual key code
KeyState keyState;			// the state the above specified key has to be in for the "binding" to become active

public:
// constructors and destructor
BindInfo();
BindInfo(const unsigned int keyCode, const KeyState keyState);
~BindInfo() {};

friend struct GameCommand;
friend class InputHandler;
};

// structure to map a single game command to a chord of key strokes (see above)
struct GameCommand
{
private:
std::wstring name;						// human readable name
std::vector<BindInfo> chord;			// the chord mapped to this command, i.e. "shift"+"control"+"F"

public:
// constructors and destructor
GameCommand();
GameCommand(const std::wstring& name, const unsigned int keyCode, const KeyState keyState);
GameCommand(const std::wstring& name, const BindInfo& bi);
GameCommand(const std::wstring& name, const std::vector<BindInfo>& chord);
~GameCommand() {};

friend class InputHandler;
};

// the main input handler class
class InputHandler
{
private:
/////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////// KEYBOARD /////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////
std::array<BYTE, 256> keyboardStateCurrent;					// the state of the keyboard in the current frame
std::array<BYTE, 256> keyboardStatePrevious;				// the state of the keyboard in the previous frame

void getKeyboardState();									// gets the keyboard state, uses GetAsyncKeyState to read the state of all 256 keys
const KeyState getKeyboardKeyState(const unsigned int keyCode) const;// gets the state of the specified key, depending on its state in the previous and the current frame

inline const bool isPressed(int keyCode) const { return (GetAsyncKeyState(keyCode) & 0x8000) ? 1 : 0; };	// returns true iff the key is down

// polling
void update();												// update the active key map
protected:
std::unordered_map<GameCommands, GameCommand*> keyMap;		// list of all possible game commands mapped to the appropriate command structure

// constructor and destructor
InputHandler();
~InputHandler();

// initialization
virtual void setDefaultKeyMap() = 0;						// set up default controls

public:
std::unordered_map<GameCommands, GameCommand*> activeKeyMap;// list of all active key maps; game acts on each command in this list

// acquire input
void acquireInput();
};
}


#include "inputHandler.h"
#include "serviceLocator.h"

namespace input
{
/////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////// Constructor //////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////
BindInfo::BindInfo() : keyCode(0), keyState(KeyState::JustReleased) {};
BindInfo::BindInfo(const unsigned int keyCode, const KeyState keyState) : keyCode(keyCode), keyState(keyState) {};

GameCommand::GameCommand() : name(L""), chord(0) {};
GameCommand::GameCommand(const std::wstring& name, const unsigned int keyCode, const KeyState keyState) : name(name)
{
chord.push_back(BindInfo(keyCode, keyState));
}
GameCommand::GameCommand(const std::wstring& name, const BindInfo& bi) : name(name)
{
chord.push_back(bi);
};
GameCommand::GameCommand(const std::wstring& name, const std::vector<BindInfo>& chord) : name(name), chord(chord) {};

InputHandler::InputHandler()
{
keyboardStateCurrent.fill(0);
keyboardStateCurrent.fill(0);

util::ServiceLocator::getFileLogger()->print<util::SeverityType::info>("The input handler was successfully initialized.");
};

InputHandler::~InputHandler()
{
// clear key map
for (auto x : keyMap)
delete x.second;
keyMap.clear();

// clear active key map
for (auto x : activeKeyMap)
delete x.second;
activeKeyMap.clear();

util::ServiceLocator::getFileLogger()->print<util::SeverityType::info>("The input handler was shutdown successfully.");
}

/////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// Polling ///////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////
void InputHandler::acquireInput()
{
// get keyboard state
getKeyboardState();

// update the key maps
update();
}

/////////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////// Update ////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////
void InputHandler::update()
{
// clear out any active bindings from the last frame
bool isActive = false;
activeKeyMap.clear();

// loop through the map of all possible actions and find the active key bindings
for (auto x : keyMap)
{
// test chord
isActive = true;
for(auto y : x.second->chord)
{
if (getKeyboardKeyState(y.keyCode) != y.keyState)
{
isActive = false;
break;
}
}
if(isActive)
activeKeyMap.insert(std::pair<GameCommands, GameCommand*>(x.first, x.second));
}

// delegate to the UI

// delegate to the game
}

/////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////// KEYBOARD /////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////////////////
void InputHandler::getKeyboardState()
{
// store the old keyboard state
keyboardStatePrevious = keyboardStateCurrent;

// read the current keyboard state
for (int i = 0; i < 256; i++)
keyboardStateCurrent[i] = isPressed(i);
}

const KeyState InputHandler::getKeyboardKeyState(const unsigned int keyCode) const
{
if (keyboardStatePrevious[keyCode] == 1)
if (keyboardStateCurrent[keyCode] == 1)
return KeyState::StillPressed;
else
return KeyState::JustReleased;
else
if (keyboardStateCurrent[keyCode] == 1)
return KeyState::JustPressed;
else
return KeyState::StillReleased;
}
}


You can download the source code for this tutorial here. Please note that in the mean time, I have made a few changes to the framework for the previous tutorials, but basically this new code is what we had before, plus our new input handler in place.

To quit the application, simply press escape, to toggle the FPS information, hold 'control'+'shift' and press 'F'.

In the next tutorial we will add mouse support to the input handler class.

# References

(in alphabetic order)

• Game Programming Algorithms, by Sanjay Madhav
• Game Programming Patterns, by Robert Nystrom
• Microsoft Developer Network (MSDN)
• Tricks of the Windows Game Programming Gurus, by André LaMothe
• Wikipedia

• Roccat