Trait Platform 

pub trait Platform {
    // Required methods
    fn display(&self) -> DisplayInfo;
    fn present(&mut self, frame: &Frame<'_>);
    fn poll_input(&mut self, out: &mut Vec<RawInputEvent>);
    fn system_events(&mut self, out: &mut Vec<SystemEvent>);
    fn storage(&mut self) -> Box<dyn Storage>;
    fn audio(&mut self) -> &mut dyn Audio;
    fn text_input(&mut self) -> Option<&mut dyn TextInput>;
    fn facts(&self) -> PlatformFacts;

    // Provided methods
    fn clock(&self) -> Option<PerfClock> { ... }
    fn memory(&mut self) -> Option<MemoryReading> { ... }
    fn memory_scopes(&self) -> Option<MemoryScopes> { ... }
    fn heap_snapshot(&mut self) -> Option<HeapSnapshot> { ... }
    fn changed_files(&mut self, _out: &mut Vec<String>) { ... }
}

What a backend gives the engine: a display to present frames on, the player’s input, the system’s events, storage, a sound device, the facts of where the game runs and, if the device has one, its own keyboard for text and, in debug builds, a clock to measure frames with.

The backend owns the loop (macroquad’s, the Playdate SDK’s update callback, a console’s main loop) and calls App::frame once per frame with its clock; App calls these methods from inside it, in the order docs/platform-backends.md gives. Only a backend touches a device (AGENTS.md rule 5): the engine’s other crates see this trait.

Required Methods

fn display(&self) -> DisplayInfo

The display, as it is now (a window may be resized between frames).

fn present(&mut self, frame: &Frame<'_>)

Shows frame. Called once per frame the game isn’t suspended, after its input, audio and update; the backend shows it as soon as it can and keeps it on the screen until the next.

fn poll_input(&mut self, out: &mut Vec<RawInputEvent>)

Adds the keyboard and controller events since the last call to out, in the order they happened: releases before presses within one poll of a device, as RawInputEvent::from_pads gives them.

fn system_events(&mut self, out: &mut Vec<SystemEvent>)

Adds the system’s events since the last call to out, in order.

fn storage(&mut self) -> Box<dyn Storage>

Hands over the game’s storage: its saves, settings and key bindings, by key. App calls it once, as the game loads, and the game’s context keeps it (screens save through it).

fn audio(&mut self) -> &mut dyn Audio

The sound device: it plays each frame’s sounds, music and voices and says what music is sounding.

fn text_input(&mut self) -> Option<&mut dyn TextInput>

The system’s own keyboard for text (a console’s, Steam’s on-screen one), if the device has one; None where the player types on keys, which come through poll_input.

fn facts(&self) -> PlatformFacts

Where the game runs (PlatformFacts): the target’s id, whether the game may quit, whether its window goes full screen and back, and the keyboard, pointer and touch screen the device has. Read from the target’s profile, or from what the backend reads of the system; constant for a run. App asks once, as the game loads, and the game’s context keeps them (Ctx::platform).

It has no default: a backend always says which target it is, so a console’s can’t inherit the desktop’s facts by forgetting.

Provided Methods

fn clock(&self) -> Option<PerfClock>

A clock in whole microseconds, to measure frames with in debug builds (ADR-0046): App takes it once, on its first frame, and only with DEBUG_TOOLS on. None (the default) for a backend without one: nothing is measured.

fn memory(&mut self) -> Option<MemoryReading>

The device’s memory now, in debug builds (ADR-0046): the heap’s live bytes, their peak and the allocations since the last call. App asks once a frame, at the end of a frame it keeps a record of (debug tools on, with a clock), and puts the heap’s counts in the record. None (the default) for a backend that doesn’t count: records have no heap counts.

fn memory_scopes(&self) -> Option<MemoryScopes>

The memory tags of the backend’s heap counter, in debug builds (ADR-0046 §6): plain functions over its tags, so what the game allocates counts by the frame’s phase and the game’s spans. App takes them with the clock (clock), once, with DEBUG_TOOLS on, and moves them into the game’s context when it runs. None (the default) for a backend whose counter has no tags. A backend with them also tags each asset decode when it starts, before the game’s load (shuyi_assets::format::watch_decodes).

fn heap_snapshot(&mut self) -> Option<HeapSnapshot>

What holds the heap now, by memory tag, in debug builds (ADR-0046 §6): its live bytes and each tag’s counts, its frame left 0 for App::heap_snapshot to stamp. Taking one allocates the rows, so it is asked for now and then (a tool, a trace every 600 frames), never every frame. None (the default) for a backend whose counter has no tags.

fn changed_files(&mut self, _out: &mut Vec<String>)

Adds the paths in the bundle of the files that changed since the last call to out, in a build with debug tools (ADR-0071): the backend has already put their new bytes in their layers (Layer::replace). App asks once a frame while the game runs, only with Ctx::debug_tools on. By default it adds nothing: a device with no files to watch.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Platform for HeadlessPlatform