Input handling with SDL3 and native drivers

Prisma Engine routes all player input through a two-layer Driver-Device abstraction. InputDevice is the high-level interface your game code talks to; it delegates the actual platform API calls to a pluggable IInputDriver. SDL3 is the default cross-platform driver; Win32 (RawInput + XInput) and GameActivity are the native alternatives for Windows and Android respectively.

Driver-Device pattern

Game layer
  └── InputDevice   (action bindings, state queries, text input, cursor control)
        └── IInputDriver  (platform API)
              ├── InputDriverSDL3     — SDL3 (cross-platform, default)
              ├── InputDriverWin32    — Win32 RawInput + XInput (Windows native)
              └── GameActivity input  — Android native (via game-activity library)

InputDevice::Initialize selects the driver at startup. Pass InputDriverType::Auto to let the engine choose the best driver for the current platform, or specify one explicitly:

Prisma::Input::InputDevice inputDevice;
inputDevice.Initialize(Prisma::Input::InputDriverType::Auto);

Driver source files live in src/engine/input/drivers/.

Backend drivers

SDL3 (cross-platform)
Win32 (Windows native)
GameActivity (Android)

InputDriverSDL3 wraps SDL3’s unified event queue. It handles keyboard, mouse, and gamepad events on all three supported platforms (Windows, Linux, Android) without any extra configuration.Source: src/engine/input/drivers/InputDriverSDL3.*Enable by setting PRISMA_USE_NATIVE_INPUT=OFF, or let Auto select SDL3 on Linux:

cmake --preset engine-linux-x64-debug -DPRISMA_USE_NATIVE_INPUT=OFF

InputDriverWin32 uses the Windows Raw Input API for keyboard and mouse, and XInput for gamepads. It is selected automatically when PRISMA_USE_NATIVE_INPUT=ON (the default) on Windows.Source: src/engine/input/drivers/InputDriverWin32.*

XInput only supports up to four simultaneous gamepads. For broader gamepad support on Windows, switch to the SDL3 driver.

On Android, input events arrive through the GameActivity framework. The engine reads them from the android_app struct passed by the Android NDK. Gamepad support uses the GameActivity input buffer.The GameActivity driver is selected automatically when targeting Android.

Input types

Keyboard

using namespace Prisma::Input;

// Held state — true every frame the key is down
if (inputDevice.IsKeyDown(KeyCode::W)) { /* move forward */ }

// Single-frame edge detection
if (inputDevice.IsKeyJustPressed(KeyCode::Space)) { /* jump */ }
if (inputDevice.IsKeyJustReleased(KeyCode::Space)) { /* land */ }

KeyCode covers the full printable ASCII range plus function keys (F1–F12), arrow keys, modifiers (LeftShift, LeftCtrl, LeftAlt, etc.), and navigation keys (Escape, Tab, Backspace, Delete).

Mouse

int x, y, dx, dy;
inputDevice.GetMousePosition(x, y);
inputDevice.GetMouseDelta(dx, dy);

if (inputDevice.IsMouseButtonJustPressed(MouseButton::Left)) { /* fire */ }

int scroll = inputDevice.GetMouseWheelDelta();

Cursor control is available for first-person cameras or UI modes:

inputDevice.SetCursorLocked(true);   // confine and hide cursor
inputDevice.SetCursorVisible(false);

Gamepad

if (inputDevice.IsGamepadConnected(0)) {
    float leftX  = inputDevice.GetGamepadAxis(0, GamepadAxis::LeftX);
    float leftY  = inputDevice.GetGamepadAxis(0, GamepadAxis::LeftY);
    float trigger = inputDevice.GetGamepadAxis(0, GamepadAxis::RightTrigger);

    if (inputDevice.IsGamepadButtonDown(0, GamepadButton::South)) { /* jump */ }

    // Rumble feedback: left motor, right motor, duration in ms
    inputDevice.SetGamepadVibration(0, 0.5f, 0.25f, 200);
}

Text input

For UI text fields, enable raw character delivery instead of keycodes:

inputDevice.StartTextInput();

// Later, each frame:
const std::string& typed = inputDevice.GetTextInput();

inputDevice.StopTextInput();

Action mappings

InputDevice supports named action bindings that decouple game logic from physical keys or buttons. A binding can have a primary key, an alternate key, and a gamepad button — the action fires if any of them is active.

// Register bindings once at startup
inputDevice.AddActionMapping("Jump",   KeyCode::Space,     KeyCode::Enter);
inputDevice.AddActionMapping("Attack", KeyCode::LeftCtrl,  KeyCode::Unknown);
inputDevice.AddActionMapping("Jump",   GamepadButton::South);   // gamepad override

// Poll every frame
if (inputDevice.IsActionJustPressed("Jump"))  { /* jump */ }
if (inputDevice.IsActionPressed("Attack"))    { /* hold-to-charge */ }

InputManager and event flow

InputManager is a subsystem owned by the engine core (src/engine/input/InputManager.*). It implements ISubSystem and receives events dispatched by the engine’s main loop:

// Inside the engine event loop
inputManager.OnEvent(event);   // translates platform events to engine state
inputManager.Update(timestep); // clears just-pressed / just-released flags

Your Application subclass receives the same events via Application::OnEvent(). Query the InputManager state after OnEvent returns:

bool isForward = inputManager.IsKeyPressed(Prisma::Input::KeyCode::W);
PrismaMath::vec2 mousePos = inputManager.GetMousePosition();
PrismaMath::vec2 mouseDelta = inputManager.GetMouseDelta();

CMake configuration

Option	Default	Description
`PRISMA_USE_NATIVE_INPUT`	`ON`	Use Win32/GameActivity on Windows/Android; SDL3 on Linux

To force SDL3 input on all platforms:

cmake --preset engine-windows-x64-debug -DPRISMA_USE_NATIVE_INPUT=OFF

SDL3 input is recommended during cross-platform development and testing. Switch to the native driver (PRISMA_USE_NATIVE_INPUT=ON) for a production Windows or Android build where you need XInput rumble or GameActivity-specific features.

Get Started

Core Concepts

Engine Systems

Platform Guides

SDK & Integration

Input handling with SDL3 and native drivers

Driver-Device pattern

Backend drivers

Input types

Keyboard

Mouse

Gamepad

Text input

Action mappings

InputManager and event flow

CMake configuration

​Driver-Device pattern

​Backend drivers

​Input types

​Keyboard

​Mouse

​Gamepad

​Text input

​Action mappings

​InputManager and event flow

​CMake configuration

Driver-Device pattern

Backend drivers

Input types

Keyboard

Mouse

Gamepad

Text input

Action mappings

InputManager and event flow

CMake configuration