Implementation Reference

Implementation details extracted from GLFW and winit for our Odin window library.

---

GLFW Implementation Details

Architecture Patterns

• Global state struct containing all library state (initialized flag, platform vtable, error handling, window/cursor/monitor linked lists)
• Window struct with linked list node (next pointer), settings/state flags, input state arrays, constraints, callbacks, and platform-specific state via macro embedding
• Monitor struct with name, physical dimensions, video modes array, gamma ramp state
• Opaque handle pattern - public API only sees pointers, never internal struct details
• Intrusive linked lists for windows, cursors, errors - next pointer embedded in each structure

Platform Abstraction

• Virtual function table - _GLFWplatform struct contains ~60 function pointers for all platform operations
• Platform state macros - GLFW_X11_WINDOW_STATE, GLFW_WIN32_WINDOW_STATE etc. embedded in window struct
• Conditional compilation - empty stub macros when platform not compiled, same binary types across platforms
• Platform ID stored in global state for runtime platform identification

Window Management

• Hints system - stateful configuration before creation (glfwWindowHint(), glfwInitHint())
• Hints persist until explicitly reset or new window created - allows adding new hints without breaking API
• Simple creation - glfwCreateWindow(width, height, title, monitor, share)
• Monitor parameter - NULL for windowed, valid monitor for fullscreen
• Share parameter - NULL or reference to existing window for OpenGL context sharing
• Constraints - min/max width/height, aspect ratio numerator/denominator

Input Handling

• Key state array - keys[GLFW_KEY_LAST + 1] stores PRESS/RELEASE/REPEAT
• Mouse state array - mouseButtons[GLFW_MOUSE_BUTTON_LAST + 1]
• Sticky input modes - persistent state capture even when callback missed
• Virtual cursor position - software-tracked cursor for disabled cursor mode
• Raw mouse motion - platform-specific unfiltered motion data
• Callback pointers - 17 callbacks stored directly in window struct (null = no-op)

Event Loop

• pollEvents() - non-blocking, processes queue
• waitEvents() - blocks until event
• waitEventsTimeout(t) - blocks with timeout
• postEmptyEvent() - force wake from wait
• Internal event functions - _glfwInputKey(), _glfwInputMouseClick() etc. called by platform code

API Design

• Error handling - thread-local storage via TLS slots, last error only (not queued)
• Input mode configuration - single function with mode enum (GLFW_CURSOR, GLFW_STICKY_KEYS, etc.)
• String hints for platform extensions (GLFW_X11_CLASS_NAME, etc.)
• Callback registration returns previous callback pointer
• User pointer on windows and monitors for application data

Platform Functions Required

• init/terminate
• Cursor: getCursorPos, setCursorPos, setCursorMode, createCursor, createStandardCursor, destroyCursor, setCursor
• Input: getScancodeName, getKeyScancode, setClipboardString, getClipboardString, rawMouseMotionSupported
• Monitor: freeMonitor, getMonitorPos, getMonitorContentScale, getMonitorWorkarea, getVideoModes, getVideoMode, getGammaRamp, setGammaRamp
• Window: createWindow, destroyWindow, setWindowTitle, setWindowIcon, get/setWindowPos, get/setWindowSize, setWindowSizeLimits, setWindowAspectRatio, getFramebufferSize, getWindowFrameSize, getWindowContentScale, iconifyWindow, restoreWindow, maximizeWindow, showWindow, hideWindow, requestWindowAttention, focusWindow, setWindowMonitor
• Window state: windowFocused, windowIconified, windowVisible, windowMaximized, windowHovered, framebufferTransparent, getWindowOpacity, setWindowResizable, setWindowDecorated, setWindowFloating, setWindowOpacity, setWindowMousePassthrough
• Events: pollEvents, waitEvents, waitEventsTimeout, postEmptyEvent

---

Winit Implementation Details

Architecture Patterns

• Trait-based abstraction - ActiveEventLoop, Window, ApplicationHandler traits
• Enum-based event system - discriminated unions for events (40+ WindowEvent variants)
• Separate crates per platform - winit-core (shared), winit-x11, winit-wayland, winit-win32, etc.
• Runtime backend selection on Linux - check WAYLAND_DISPLAY then DISPLAY env vars
• Window IDs - distinct u64 identifiers for multi-window handling

ApplicationHandler Callbacks

• can_create_surfaces() - lifecycle point for surface creation (critical for Android)
• window_event(event_loop, window_id, event) - per-window events
• device_event(event_loop, device_id, event) - raw input events
• about_to_wait() - pre-blocking hook
• new_events(cause) - start of event batch
• proxy_wake_up() - inter-thread signaling

Window Attributes (Builder Pattern)

• surface_size, min_surface_size, max_surface_size, surface_resize_increments
• position
• resizable
• enabled_buttons (bitflags for min/max/close)
• title
• maximized, visible, transparent, blur, decorations
• window_icon
• preferred_theme (Light/Dark)
• content_protected
• window_level (Normal, AlwaysOnTop, AlwaysOnBottom)
• active
• cursor
• parent_window
• fullscreen (Borderless or Exclusive with video mode)
• platform (boxed trait object for platform-specific extensions)

Keyboard Input Hierarchy

1. Physical scancode (XKB keycode, Windows scancode)
2. Platform-native NativeKeyCode: Xkb(u32), Windows(u16), MacOS(u16)
3. Logical key via NativeKey (keysym, vkcode)
4. Named key enum: Enter, Escape, ArrowUp, F1-F24, etc.

Key Modifiers

• Shift, Control, Alt, Super (meta/win/cmd)
• Separate left/right tracking
• CapsLock, NumLock state

Pointer Events

• PointerMoved { position, primary, source }
• PointerEntered { position, primary, kind }
• PointerLeft { position, primary, kind }
• PointerButton { state, position, button }
• MouseWheel { delta: LineDelta | PixelDelta, phase }
• Primary vs secondary pointer for multi-touch

Event Loop Control Flow

• Poll - continuous polling (games)
• Wait - block until events (UI apps, most efficient)
• WaitUntil(instant) - block with timeout

StartCause (Why event loop woke)

• Init - first iteration
• Poll - Poll control flow triggered
• WaitCancelled { start, requested_resume } - new events interrupted wait
• ResumeTimeReached { start, requested_resume } - WaitUntil timeout fired

Window Events (Key Variants)

• SurfaceResized, Moved, CloseRequested, Destroyed
• Focused(bool), Occluded(bool)
• KeyboardInput { device_id, event, is_synthetic }
• ModifiersChanged
• PointerMoved, PointerEntered, PointerLeft, PointerButton
• MouseWheel, AxisMotion
• Touch, TouchpadPressure
• PinchGesture, PanGesture, DoubleTapGesture, RotationGesture
• DragEntered, DragMoved, DragDropped, DragLeft
• ScaleFactorChanged { scale_factor, surface_size_writer }
• ThemeChanged
• Ime(Enabled, Preedit, Commit, Disabled)
• RedrawRequested

Coordinate Systems

• Surface coordinates - relative to drawable area (0,0 at content top-left)
• Window coordinates - relative to window including decorations
• Desktop coordinates - absolute screen position
• Methods: surface_size(), outer_size(), surface_position(), outer_position()

DPI/Scaling

• scale_factor() on Window
• ScaleFactorChanged event when DPI changes
• Physical and Logical types that auto-convert
• Fractional scaling support (Wayland)

Monitor API

• available_monitors() - iterator of MonitorHandle
• primary_monitor() - Option<MonitorHandle>
• MonitorHandle: id, native_id, name, position, scale_factor, video_modes, current_video_mode

Cross-Thread Communication

• EventLoopProxy::wake_up() - coalesced (multiple calls = 1 proxy_wake_up event)
• Used for background threads signaling work completion

Raw Window Handles

• raw_window_handle() → RawWindowHandle for Vulkan/OpenGL/Metal/DirectX
• raw_display_handle() → DisplayHandle for display connection

X11-Specific

• Window types: Desktop, Dock, Toolbar, Menu, Utility, Splash, Dialog, DropdownMenu, PopupMenu, Tooltip, Notification, Combo, Dnd, Normal
• XAtom handling
• Drag & drop (XDND protocol)
• Input method integration
• XSettings for desktop settings

Wayland-Specific

• Client-side decorations (CSD) option
• xdg_toplevel access
• Activation tokens
• Fractional scaling protocol
• Tablet input v2

---

Current Implementation Status

Core Data Structures

• [x] Global library state (Platform_Event_Loop in platform_linux.odin)
• [x] Window struct (Platform_Window with union of X11/Wayland data)
• [x] Monitor struct (Monitor_Info with id, name, dimensions, modes, position, scale)
• [x] Event enum (discriminated union: Window_Event, Device_Event, Loop_Event)

Window Management

• [x] Window creation with attributes (create_window() + Window_Attributes)
• [x] Window destruction (destroy_window())
• [x] Title (set_title())
• [ ] Window icon
• [x] Position (outer_position(), set_outer_position(), set_position(), get_position())
• [x] Size (surface_size(), request_surface_size(), outer_size(), set_size())
• [x] Min/max size constraints (set_min_surface_size(), set_max_surface_size())
• [ ] Aspect ratio constraints
• [x] Visible (set_visible(), is_visible())
• [x] Focused (focus(), is_focused())
• [x] Maximized (set_maximized(), is_maximized() - state tracking TODO)
• [x] Minimized (set_minimized(), is_minimized() - state tracking TODO)
• [x] Fullscreen (set_fullscreen(), get_fullscreen() - borderless + exclusive)
• [x] Decorations (set_decorations(), is_decorated() - state tracking TODO)
• [x] Resizable (set_resizable(), is_resizable() - state tracking TODO)
• [ ] Floating/always-on-top
• [ ] Mouse passthrough
• [ ] Opacity
• [~] Content scale / DPI (scale_factor() - hardcoded 1.0, detection TODO)

Input Handling

• [x] Keyboard input with scancodes (Key_Input event, Key_Code enum 126+ keys)
• [ ] Key state array for polling
• [x] Modifier keys tracking (Modifiers struct: shift, ctrl, alt, super)
• [x] Mouse button input (Mouse_Button_Input event)
• [x] Cursor position (Pointer_Moved event with position)
• [x] Scroll wheel (Mouse_Wheel event with line + pixel deltas)
• [ ] Cursor modes (normal, hidden, disabled/grabbed)
• [ ] Raw mouse motion (relative pointer protocol)
• [ ] Cursor shapes (standard cursors)
• [~] Key repeat detection (TODO in both X11 and Wayland)

Event System

• [x] Poll events (poll() - non-blocking)
• [x] Wait events (run() with Wait control flow - blocking)
• [x] Wait events with timeout (Wait_Until control flow)
• [ ] Post empty event / wake from wait (TODO in code)
• [x] Callback-based design (winit-style Event_Handler callback)
• [x] Start cause tracking (Init, Poll, Wait_Cancelled, Resume_Time_Reached)
• [x] Loop events (New_Events, About_To_Wait, Loop_Exiting)

Monitor/Display

• [x] Enumerate monitors (get_monitors())
• [x] Primary monitor (get_primary_monitor())
• [x] Monitor name (get_monitor_name())
• [x] Monitor position (get_monitor_position())
• [x] Monitor workarea (get_monitor_workarea())
• [x] Physical size (get_monitor_physical_size())
• [x] Content scale (get_monitor_content_scale())
• [x] Video modes enumeration (get_video_modes())
• [x] Current video mode (get_current_video_mode())
• [x] Combined info (get_monitor_info())

Platform Abstraction

• [x] Platform-specific state embedded in structs (union in Platform_Window)
• [x] Runtime platform selection (X11 vs Wayland via select_backend())
• [x] Environment variable checks (WAYLAND_DISPLAY, ODIN_WINDOW_BACKEND)
• [x] X11 backend (complete)
• [x] Wayland backend (functional - window creation, input, monitors, decorations)

Raw Handle Support

• [x] raw_window_handle() - X11 window ID or Wayland wl_surface
• [x] raw_display_handle() - X11 display or Wayland wl_display

API Design (Implemented Choices)

• [x] Distinct handle types (Window_Id, Device_Id, Monitor_Handle)
• [x] Attributes struct pattern (not hints)
• [x] Callback-based events (winit-style)
• [ ] User pointer on objects
• [x] Error handling via Error enum return values
• [ ] Thread-local error storage

---

Not Yet Implemented

Window Features

• Window icon
• Aspect ratio constraints
• Floating/always-on-top window level
• Mouse passthrough
• Window opacity
• Proper DPI detection (currently hardcoded to 1.0)
• State tracking for maximized/minimized/resizable/decorated flags

Input Features

• Key state array for polling (currently event-only)
• Cursor visibility modes (hidden, disabled/grabbed)
• Raw mouse motion (Wayland relative-pointer protocol)
• Standard cursor shapes
• Key repeat detection (marked TODO)
• Event loop wake-up mechanism (marked TODO)

Advanced Features

• Clipboard access (copy/paste)
• Custom cursor images
• Drag & drop
• Input method (IME) integration
• Touch input
• Gamepad/joystick
• Pointer gestures (pinch, pan, rotate)
• Tablet input

Wayland-Specific Incomplete

• Exclusive fullscreen with specific video mode
• Pointer constraints (cursor locking)
• Activation tokens
• Fractional scaling (protocol exists, not wired through)