refactor platform package to describe physical host input events

src/platform/root.zig

@@ -0,0 +1,140 @@
+const std = @import("std");
+
+pub const Key = enum {
+    unknown,
+
+    // Letters.
+    a,
+    b,
+    c,
+    d,
+    e,
+    f,
+    g,
+    h,
+    i,
+    j,
+    k,
+    l,
+    m,
+    n,
+    o,
+    p,
+    q,
+    r,
+    s,
+    t,
+    u,
+    v,
+    w,
+    x,
+    y,
+    z,
+
+    // Navigation.
+    up,
+    down,
+    left,
+    right,
+
+    // Common controls.
+    enter,
+    space,
+    escape,
+    tab,
+    backspace,
+
+    left_shift,
+    right_shift,
+    left_ctrl,
+    right_ctrl,
+    left_alt,
+    right_alt,
+
+    // Function keys.
+    f1,
+    f2,
+    f3,
+    f4,
+    f5,
+    f6,
+    f7,
+    f8,
+    f9,
+    f10,
+    f11,
+    f12,
+};
+
+pub const KeyEvent = struct {
+    key: Key,
+
+    /// True when generated by keyboard autorepeat.
+    repeat: bool = false,
+};
+
+pub const GamepadButtonEvent = struct {
+    gamepad: u8,
+    button: u8,
+};
+
+/// Normalized signed range:
+///
+/// -32768 = minimum
+///  32767 = maximum
+pub const GamepadAxisEvent = struct {
+    gamepad: u8,
+    axis: u8,
+    value: i16,
+};
+
+pub const PointerEvent = struct {
+    pointer: u8 = 0,
+
+    active: bool,
+
+    /// Normalized coordinates.
+    ///
+    /// 0     = minimum
+    /// 65535 = maximum
+    x: u16,
+    y: u16,
+
+    pressure: u16 = 0,
+};
+
+pub const Event = union(enum) {
+    quit,
+
+    key_down: KeyEvent,
+    key_up: KeyEvent,
+
+    gamepad_button_down: GamepadButtonEvent,
+    gamepad_button_up: GamepadButtonEvent,
+
+    gamepad_axis: GamepadAxisEvent,
+
+    pointer: PointerEvent,
+};
+
+/// Useful for tests or non-interactive execution.
+///
+/// Video/audio handling deliberately does not live here.
+pub const Headless = struct {
+    pub fn init() Headless {
+        return .{};
+    }
+
+    pub fn pollEvent(_: *Headless) ?Event {
+        return null;
+    }
+};
+
+test "platform: headless has no events" {
+    var platform_driver = Headless.init();
+
+    try std.testing.expectEqual(
+        @as(?Event, null),
+        platform_driver.pollEvent(),
+    );
+}