Last updated on February 17th, 2024

In the next chapter we will see how so called events are processed to handle input of any kind (keyboard, mouse, joystick,…) Before that I’d like to introduce a simple, yet powerful way to handle keyboard input via the keyboard state.

Lets have a look at the most important function here. The keyboard state represents the state (pressed = 1 or unpressed = 0) of all the keyboard keys, hence the key states. By

function SDL_GetKeyboardState(numkeys: PInt): PUInt8

we have easy access to this array. This is a highly efficient and fast way of gathering keyboard information without the need to queue any events.

Advantages of using the keyboard state

It is very fast and efficient compared to processing keyboard events. It can (and should) be combined freely with the classical event processing of key-events or other events. You have no hassle with case-statements to care for all the keys you like to consider but rather instant access to all keys on the keyboard. The keyboard state can easily propagated through your program as it is a simple and plain pointer. – Running speed is a crucial property for many games so you should consider using keyboard states if your game relies heavily on keyboard input.

Disadvantages of using the keyboard state

The keyboard states does not consider key modifiers like the shift-key. So you know a key has been pressed but you cannot distinguish between a letter and a capital letter for example. There are no equivalent input states for other devices like mouse, joystick, joypad, and so on. Last but not least, you still need the event processing in the program loop because otherwise the state does not get updated (see below for more information on that). This also means, if the key state of a certain key changes from unpressed to pressed and back to unpressed before the event loop has been processed, the pressed key remains unnoticed.

The following code example will draw a red rectangle which can be moved by the WASD keys. Therefore we read out their key states on every cycle of the program loop.

program SDL_KeyboardState;

uses SDL2;

var
  sdlWindow1: PSDL_Window;
  sdlRenderer: PSDL_Renderer;
  sdlRectangle: TSDL_Rect;
  sdlKeyboardState: PUInt8;
  Running: Boolean = True;

begin

  //initilization of video subsystem
  if SDL_Init(SDL_INIT_VIDEO) < 0 then Halt;

  if SDL_CreateWindowAndRenderer(500, 500, SDL_WINDOW_SHOWN, @sdlWindow1, @sdlRenderer) <> 0
    then Halt;

  // prepare rectangle
  sdlRectangle.x := 250;
  sdlRectangle.y := 250;
  sdlRectangle.w := 10;
  sdlRectangle.h := 10;
  
  // get keyboard state pointer
  sdlKeyboardState := SDL_GetKeyboardState(nil);

  // program loop
  while Running = True do
  begin
    SDL_PumpEvents;
    
    // ESC pressed
    if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
      Running := False;

    // WASD keys pressed
    if sdlKeyboardState[SDL_SCANCODE_W] = 1 then
      sdlRectangle.y := sdlRectangle.y-1;
    if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
      sdlRectangle.x := sdlRectangle.x-1;
    if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
      sdlRectangle.y := sdlRectangle.y+1;
    if sdlKeyboardState[SDL_SCANCODE_D] = 1 then
      sdlRectangle.x := sdlRectangle.x+1;

    // black background
    SDL_SetRenderDrawColor(sdlRenderer, 0, 0, 0, SDL_ALPHA_OPAQUE);
    SDL_RenderClear(sdlRenderer);
    // draw red rectangle
    SDL_SetRenderDrawColor(sdlRenderer, 255, 0, 0, SDL_ALPHA_OPAQUE);
    SDL_RenderDrawRect(sdlRenderer, @sdlRectangle);

    SDL_RenderPresent(sdlRenderer);
    SDL_Delay(20);
  end;

  // clear memory
  SDL_DestroyRenderer(sdlRenderer);
  SDL_DestroyWindow (sdlWindow1);

  //closing SDL2
  SDL_Quit;

end.

To get the keyboard state, we define a unsigned 8 bit pointer variable sdlKeyboardState in the var clause. It points to the array of key states.

After setting up a SDL2 window and and preparing a SDL2 rectangle, we jump right into allocating the keyboard state pointer to the sdlKeyboardState variable by the function SDL_GetKeyboardState. The argument should be nil. It is sufficient to this once in your program code as you see in the second line:

  // get keyboard state pointer
  sdlKeyboardState := SDL_GetKeyboardState(nil);

  // program loop
  while Running = True do
  begin
    SDL_PumpEvents; 

In the program event loop we need to update the event queue by procedure SDL_PumpEvents (or SDL_PollEvent or SDL_WaitEvent; both call SDL_PumpEvent implicitly). Only calling one of these procedures in the program loop updates the keyboard state.

    // ESC pressed
    if sdlKeyboardState[SDL_SCANCODE_ESCAPE] = 1 then
      Running := False;

    // WASD keys pressed
    if sdlKeyboardState[SDL_SCANCODE_W] = 1 then
      sdlRectangle.y := sdlRectangle.y-1;
    if sdlKeyboardState[SDL_SCANCODE_A] = 1 then
      sdlRectangle.x := sdlRectangle.x-1;
    if sdlKeyboardState[SDL_SCANCODE_S] = 1 then
      sdlRectangle.y := sdlRectangle.y+1;
    if sdlKeyboardState[SDL_SCANCODE_D] = 1 then
      sdlRectangle.x := sdlRectangle.x+1;  

We now can check for the of any key in the array by sdlKeyboardState[SDL_SCANCODE_…] using its
scancode as a handle (e.g. SDL_SCANCODE_ESCAPE for the escape key) and react as desired, e.g. exit the program loop or change the x/y coordinates of the rectangle. The scancode represents the position of the related key state in the array. A detailed description of scancodes in the next chapter. A list of all the scancodes shows all possible scancodes.

← previous Chapter | next Chapter →