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 #

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 #

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 #

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 #

def default_library_path() -> String

The library path for this OS relative to the repository root, unless CINDER_NATIVE_LIB is set.

struct NativeLibrary #

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 #

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 #

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 #

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.