Understanding Keyboard State

In previous lessons, we introduced how we can detect and react to keyboard input through the event loop:

1#include <SDL.h>
2
3void HandleKeyboardEvent(SDL_KeyboardEvent& E) {
4  // ...
5}
6
7int main(int argc, char** argv) {
8  Window GameWindow;
9  SDL_Event Event;
10
11  while (true) {
12    while (SDL_PollEvent(&Event)) {
13      if (Event.type == SDL_KEYDOWN)
14        HandleKeyboardEvent(Event.key);
15    }
16  }
17
18  SDL_Quit();
19  return 0;
20}

However, there is another option. At any time within our application, we can query SDL to find out which keys are currently pressed.

Getting Keyboard State

SDL maintains an array of UInt8 values to represent the state of the user’s keyboard. This array has an integer for every key on the user’s keyboard, and we can receive a const pointer to it using the SDL_GetKeyboardState() function.

This function receives a pointer to an integer as an argument, which it updates with the size of the array:

1#include <iostream>
2#include <SDL.h>
3
Window Class|Show
4class Window {/*...*/}
23
24void HandleKeyboard() {
25  int Size;
26  SDL_GetKeyboardState(&Size);
27
28  std::cout << "Array Size: " << Size;
29}
30
31int main(int argc, char** argv) {
32  Window GameWindow;
33  SDL_Event Event;
34
35  HandleKeyboard();
36
Game Loop|Show
37  while (true) {/*...*/}
45
46  SDL_Quit();
47  return 0;
48}

1Array Size: 512

Note that the array’s size will typically be larger than the number of keys on our keyboard, meaning not every position is assigned to a key. The main reason the size is provided is to communicate the upper bound of the array, which we may need to know if we were iterating through it, for example.

If we don’t need to know the size, we can pass a nullptr:

1void HandleKeyboard() {
2  SDL_GetKeyboardState(nullptr);
3}

C-Style Arrays

The array returned by SDL_GeyKeyboardState() is an example of a C-style array. These are much more primitive than standard library containers such as a std::vector.

A C-style array is simply a pointer to the first element in the collection. Given this array is a collection of UInt8 objects in this case, the type of the array is therefore a UInt8* - a pointer to a UInt8.

This array is managed internally by SDL and not something we should change, so it is additionally marked as const:

1void HandleKeyboard() {
2  const Uint8* State {
3    SDL_GetKeyboardState(nullptr)};  
4}

C-style arrays are so primitive they don’t even keep track of their own size. That needs to be communicated separately. In the case of SDL_GetKeyboardState(), this is done by updating a variable we provide a pointer to.

We cover C-style arrays in more detail here:

C-Style Arrays

A detailed guide to working with classic C-style arrays within C++, and why we should avoid them where possible

Determining Which Keys are Held

Once we have the keyboard array from SDL_GetKeyboardState(), we can determine if a key is currently held down by investigating the corresponding entry within that array. The index we need for each key is the scan code of that key, which SDL provides variables for.

For example, to determine if the spacebar is currently held down, we would check the index represented by SDL_SCANCODE_SPACE:

1void HandleKeyboard() {
2  const Uint8* State {
3    SDL_GetKeyboardState(nullptr)};
4    
5  State[SDL_SCANCODE_SPACE];
6}

The Uint8 value at each array position is 1 if the corresponding key is pressed, and 0 otherwise. 1 is truthy, and 0 is falsy, so we can directly use these values as booleans.

Below, we check on every frame whether the spacebar is held or not:

1#include <iostream>
2#include <SDL.h>
3
Window Class|Show
4class Window {/*...*/}
23
24void HandleKeyboard() {
25  const Uint8* State {
26    SDL_GetKeyboardState(nullptr)};
27
28  if (State[SDL_SCANCODE_SPACE]) {
29    std::cout << "Space is held\n";
30  } else {
31    std::cout << "Space is not held\n";
32  }
33}
34
35int main(int argc, char** argv) {
36  Window GameWindow;
37  SDL_Event Event;
38
39  while (true) {
40    while (SDL_PollEvent(&Event)) {
41      // ...
42    }
43
44    HandleKeyboard();
45    GameWindow.RenderFrame();
46  }
47
48  SDL_Quit();
49  return 0;
50}

1Space is not held
2Space is not held
3Space is not held
4Space is held
5Space is held

All the scan codes we need to index into this array are available in the SDK_keycode header file.

Keyboard State and the Event Queue

For SDL to update its keyboard state array, we must instruct it to process its event queue. In the previous examples, and in most applications, we’ve been doing that within our application loops.

Specifically, the continuous calls to SDL_PollEvent() prompt SDL to keep its various components up to date, including the keyboard state array:

1SDL_Event Event;
2
3while (true) {
4  while (SDL_PollEvent(&Event)) {
5    // React to events
6    // ...
7  }
8
9  HandleKeyboard();
10  GameWindow.RenderFrame();
11}

Even if we don’t need to react to the events, we still need to prompt SDL to process them at the appropriate time within the application loop.

However, if we don’t need to inspect the events, we can simplify our loop by using SDL_PumpEvents() instead of SDL_PollEvent():

1SDL_Event Event; 
2
3while (true) {
4  SDL_PumpEvents(); 
5  HandleKeyboard();
6  GameWindow.RenderFrame();
7}

SDL_PumpEvents() and SDL_PollEvent() have a similar purpose, but are different in two key ways:

• SDL_PumpEvents() processes all the outstanding events on the queue, whilst SDL_PollEvent() only handles one event per invocation. As such, we can remove the inner loop - we only need to call SDL_PumpEvents() once per frame.
• SDL_PumpEvents() doesn’t give us visibility of each individual event. As such, we can remove the argument, and delete the SDL_Event variable it was based on.

Events vs Polling

We’ve now seen two different approaches we can take to handle keyboard input. These designs are typically referred to as event-driven and polling:

• Event-based designs handle input through the event loop. Our application loop detects the keyboard events we’re interested in and notifies the interested objects.
• Polling-based designs instead have those objects directly examine the keyboard state. This is referred to as polling as it generally needs to happen continuously - typically every frame

Each design has its advantages and disadvantages and, in a more complex application, both techniques tend to be used.

Event-based designs tend to be preferred for interactions that are discrete rather than continuous. Examples of discrete actions include the user pressing a key to open up a menu, or clicking on a button in the UI.

Event implementations also tend to be more performant than polling, especially when the event is infrequent. Polling every frame to detect a state that rarely happens is usually a waste of resources, and is better implemented through the event queue.

Polling designs are more appropriate for interactions that tend to be continuous. For example, movement input is often implemented by the user holding down one of several designated keys.

In that scenario, having the movement system implement frame-by-frame polling to determine which movement keys are held down is typically cleaner than reacting to keydown and keyup actions coming from the event queue.

Summary

In this lesson, we explored how to handle keyboard input in SDL2 using both event-driven and polling methods. We learned how to obtain and interpret the keyboard state array to detect key presses.

• SDL maintains an array to represent the keyboard state.
• The SDL_GetKeyboardState() function provides access to this array.
• C-style arrays are used, which are primitive and require manual size handling.
• We can check if a key is pressed by indexing the array with the key's scan code.
• The keyboard state array is updated when SDL processes its event queue.
• Event-driven and polling methods have different use cases and can be used together in complex applications.

Next Lesson

Handling Mouse Scrolling

Learn how to detect and handle mouse scroll wheel events in SDL2, including vertical and horizontal scrolling, as well as scroll wheel button events.

ContinueView Course