SDLGetKeyboardState

SDL_GetKeyboardState is a function in the SDL library that provides access to the current state of the keyboard as a read‑only array. The function returns a pointer to an internal array of Uint8 values that indicate which keys are pressed. The array is updated when SDL_PumpEvents or SDL_PollEvent is called, so the state should be refreshed once per frame if you want real‑time input.

Prototype and return value:

const Uint8* SDL_GetKeyboardState(int* numkeys);

The returned array has a length of SDL_NUM_SCANCODES. Each element is indexed by an SDL_Scancode value (for example, SDL_SCANCODE_A). A nonzero value indicates the key is currently pressed, while zero means it is released. The numkeys parameter, if non‑NULL, is set to the length of the array (typically SDL_NUM_SCANCODES).

Usage notes:

- The pointer returned by SDL_GetKeyboardState points to SDL‑owned memory; you must not free or modify it.

- To ensure the returned state reflects the latest input, call SDL_PumpEvents or process events with SDL_PollEvent before reading the array.

- This API uses scancodes (SDL_Scancode) rather than keycodes (SDL_Keycode), making it independent of the current keyboard layout. This means you check keys by their physical position rather than the character they produce.

Example usage conceptually: obtain the state array once (e.g., at startup or each frame) and query state[SDL_SCANCODE_SPACE] to test whether the space bar is pressed. SDL_GetKeyboardState is commonly used for per-frame input checks and for implementing continuous key handling.