> Cinder 0.1.0 documentation: cinder.platform API > Canonical page: https://cinder.ash10.dev/docs/api/platform/ · Source: `docs/api/platform.md` in the engine repository (engine commit 47c9352, imported 2026-11-09) > Index of every page for agents: https://cinder.ash10.dev/llms.txt # `cinder.platform` ## `cinder.platform` Source: `cinder/platform/__init__.mojo` Platform layer: the native library, SDL3 windows, input events and wgpu surfaces. This is the only engine module with per-operating-system branches (library file names, surface creation inside the shim). Everything above it is platform-neutral. ## `cinder.platform.events` Source: `cinder/platform/events.mojo` Platform events in engine terms, translated from SDL3's event union. ### struct `EventKind` ```mojo struct EventKind(Equatable, ImplicitlyCopyable, RegisterPassable, Writable) ``` What an `Event` describes. Fields: - `value`: UInt8 - **`none`** `none() -> EventKind` No event: an SDL event this layer does not translate (`Platform.poll` drops it). - **`quit`** `quit() -> EventKind` The application was asked to quit (SDL_EVENT_QUIT). - **`window_close`** `window_close() -> EventKind` The user asked to close the window `window_id`. - **`window_resized`** `window_resized() -> EventKind` Pixel size changed; `a`/`b` carry the new width and height. - **`window_minimized`** `window_minimized() -> EventKind` Window `window_id` was minimised. - **`window_restored`** `window_restored() -> EventKind` Window `window_id` was restored. - **`window_focus_gained`** `window_focus_gained() -> EventKind` Window `window_id` gained keyboard focus. - **`window_focus_lost`** `window_focus_lost() -> EventKind` Window `window_id` lost keyboard focus. - **`key`** `key() -> EventKind` `scancode`, `keycode`, `mods`, `down`, `repeat`. - **`mouse_motion`** `mouse_motion() -> EventKind` `x`, `y` absolute; `dx`, `dy` relative. - **`mouse_button`** `mouse_button() -> EventKind` `button` (1 = left, 2 = middle, 3 = right), `down`, `x`, `y`. - **`mouse_wheel`** `mouse_wheel() -> EventKind` `dx`, `dy` scroll amounts. - **`gamepad_added`** `gamepad_added() -> EventKind` A gamepad was connected; `device` is its SDL joystick id (`Platform.poll` opens it). - **`gamepad_removed`** `gamepad_removed() -> EventKind` A gamepad was disconnected; `device` is its SDL joystick id (`Platform.poll` closes it). - **`gamepad_button`** `gamepad_button() -> EventKind` `device`, `button` (SDL_GamepadButton), `down`. - **`gamepad_axis`** `gamepad_axis() -> EventKind` `device`, `axis` (SDL_GamepadAxis), `value` normalised to [-1, 1]. - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### struct `Event` ```mojo struct Event(ImplicitlyCopyable, RegisterPassable, Writable) ``` One translated platform event. Fields are interpreted per `kind` (see `EventKind` docstrings). Fields: - `kind`: EventKind - `window_id`: UInt32 - `device`: UInt32 - `a`: Int32 - `b`: Int32 - `scancode`: UInt32 - `keycode`: UInt32 - `mods`: UInt16 - `button`: UInt8 - `axis`: UInt8 - `down`: Bool - `repeat`: Bool - `x`: Float32 - `y`: Float32 - `dx`: Float32 - `dy`: Float32 - `value`: Float32 - **`empty`** `empty(kind: EventKind) -> Event` An event of `kind` with every other field zero or False. - **`write_to`** `write_to(self, mut writer: Some[Writer])` ### def `translate_event` ```mojo def translate_event(ev: SDL_Event) -> Event ``` Translates an SDL event into an `Event`; unknown SDL events become `EventKind.none()`. ## `cinder.platform.native` Source: `cinder/platform/native.mojo` Loading libcinder_native exactly once and sharing it by pointer. `NativeLibrary` keeps the generated `CinderNative` struct (library handle plus every resolved symbol) at a stable heap address for the life of the program. Subsystems hold a `NativePtr` to it and never copy function pointers out (docs/MOJO_NOTES.md: the handle must outlive every call). - `comptime NativePtr = Pointer[CinderNative, MutUntrackedOrigin]` — How subsystems refer to the loaded native library. - `comptime LIBRARY_PATH_ENV = "CINDER_NATIVE_LIB"` — Environment variable that, when set and non-empty, replaces the library path `default_library_path` returns. ### def `default_library_path` ```mojo def default_library_path() -> String ``` The library path for this OS relative to the repository root, unless CINDER_NATIVE_LIB is set. ### struct `NativeLibrary` ```mojo struct NativeLibrary(Movable) ``` Owns the one loaded copy of libcinder_native. Fields: - **`__init__`** `__init__(out self, path: String) raises` Loads the library at `path`, resolving every bound symbol. Raises when the library is missing, a symbol is missing, or the shim's ABI version differs from the bindings'. - **`__init__`** `__init__(out self) raises` Loads the library from `default_library_path()`. - **`ptr`** `ptr(self) -> NativePtr` Pointer to the loaded bindings, valid only while this `NativeLibrary` lives: it must be destroyed after every subsystem holding the pointer. ## `cinder.platform.window` Source: `cinder/platform/window.mojo` SDL3 platform: initialisation, windows, event polling, gamepads and wgpu surface creation. - `comptime SdlWindowPtr = Optional[Pointer[SDL_Window, MutUntrackedOrigin]]` — Nullable pointer to an SDL window. - `comptime EventQueuePtr = Optional[Pointer[CnEventQueue, MutUntrackedOrigin]]` — Nullable pointer to a shim event queue (the platform's SDL log queue). ### struct `GamepadSlot` ```mojo struct GamepadSlot(ImplicitlyCopyable, Movable) ``` An open gamepad: SDL joystick id and the SDL_Gamepad handle. Fields: - `id`: UInt32 - `handle`: Optional[Pointer[SDL_Gamepad, MutUntrackedOrigin]] ### struct `Platform` ```mojo struct Platform(Movable) ``` SDL initialised for video, events and gamepads. Create one, before any Window, on the main thread. SDL's log goes to a shim queue and is drained into `diagnostics` by `poll`. Fields: - `lib`: NativePtr - `gamepads`: List[GamepadSlot] - `diagnostics`: List[LogRecord] — SDL log lines collected since the last `take_diagnostics`. - `forward_to_imgui`: Bool — When set (by the debug UI), every raw SDL event is also handed to the ImGui backend. - **`__init__`** `__init__(out self, lib: NativePtr) raises` - **`video_driver`** `video_driver(self) -> String` Name of the current SDL video driver; empty when SDL reports none. - **`last_error`** `last_error(self) -> String` SDL's most recent error message (`SDL_GetError`). - **`poll`** `poll(mut self, mut events: List[Event])` Drains SDL's event queue into `events` (cleared first; capacity is retained so a warmed-up list does not allocate), opening and closing gamepads as they come and go, and moves SDL log lines into `diagnostics`. - **`take_diagnostics`** `take_diagnostics(mut self) -> List[LogRecord]` Moves out the SDL log records collected by `poll`, leaving `diagnostics` empty. - **`push_event`** `push_event(self, ev: SDL_Event) -> Bool` Injects an SDL event (tests and replay). Returns False when SDL refused it. ### struct `Window` ```mojo struct Window(Movable) ``` An SDL window. Destroyed with the struct; create the wgpu surface through `create_surface`. Fields: - `lib`: NativePtr - `handle`: SdlWindowPtr - `id`: UInt32 - **`__init__`** `__init__( out self, platform: Platform, title: String, width: Int, height: Int, resizable: Bool = True, hidden: Bool = False, ) raises` - **`pixel_size`** `pixel_size(self) raises -> Tuple[Int, Int]` Drawable size in pixels as (width, height); with high pixel density it can differ from the size the window was created with. Raises when SDL fails. - **`set_size`** `set_size(self, width: Int, height: Int) raises` Requests a new window size and waits for it to apply (`SDL_SyncWindow`, whose result is ignored); raises when SDL rejects the request. - **`set_title`** `set_title(mut self, title: String)` Sets the window title, keeping the text alive in the window; SDL failures are ignored. - **`show`** `show(self)` Shows the window (one created with `hidden`); SDL failures are ignored. - **`set_relative_mouse`** `set_relative_mouse(self, enabled: Bool) -> Bool` Turns SDL relative mouse mode on or off for this window; returns False when SDL refused. - **`create_surface`** `create_surface(self, instance: WGPUInstance) raises -> WGPUSurface` Creates the wgpu surface for this window through the shim (X11, Wayland or Metal). - **`destroy_surface`** `destroy_surface(self, surface: WGPUSurface)` Destroys a surface returned by `create_surface`, through the shim with this window's handle.