Interface IPlatformHost

Namespace: MicroEngine.Platform
Assembly: MicroEngine.Platform.dll
Guide: The platform host

The platform a game runs on, as the loop sees it: a monotonic clock, the events of the window and the system, the main surface, optional features found by type and whether the host may block its thread.

C#

public interface IPlatformHost : IDisposable

Implements

IDisposable

Remarks

The platform contract, which every host follows:

1. One thread. The loop calls every member on the game's thread. A host that learns of an event on another thread (a phone's lifecycle callbacks) holds it until the next [PumpEvents](/docs/api/microengine.platform.iplatformhost/#MicroEngine_Platform_IPlatformHost_PumpEvents_MicroEngine_Platform_IEngineEventSink_).
2. Events are delivered only by [PumpEvents](/docs/api/microengine.platform.iplatformhost/#MicroEngine_Platform_IPlatformHost_PumpEvents_MicroEngine_Platform_IEngineEventSink_), which the loop calls once at the start of every frame, in the order they happened. Nothing is delivered between pumps.
3. Lifecycle order. [Suspending](/docs/api/microengine.platform.iengineeventsink/#MicroEngine_Platform_IEngineEventSink_Suspending) and [Resumed](/docs/api/microengine.platform.iengineeventsink/#MicroEngine_Platform_IEngineEventSink_Resumed) alternate, starting with Suspending: a host never sends two in a row, and never Resumed without a Suspending before it. A trip to the background and back that happened between two pumps is delivered as both, in that order, in one pump. [FocusChanged](/docs/api/microengine.platform.iengineeventsink/#MicroEngine_Platform_IEngineEventSink_FocusChanged_System_Boolean_) is sent only when the focus changes. [QuitRequested](/docs/api/microengine.platform.iengineeventsink/#MicroEngine_Platform_IEngineEventSink_QuitRequested) is sent once per request; the loop decides (handlers may veto it), and a later request is sent again.
4. Resizes. When the main surface's pixel size changes, the same pump raises [Resized](/docs/api/microengine.platform.isurface/#MicroEngine_Platform_ISurface_Resized) and delivers [Resized](/docs/api/microengine.platform.iengineeventsink/#MicroEngine_Platform_IEngineEventSink_Resized_MicroEngine_Kernel_SurfaceResized_) with the new [PixelSize](/docs/api/microengine.platform.isurface/#MicroEngine_Platform_ISurface_PixelSize); a size that did not change is not delivered.
5. Clock. [Clock](/docs/api/microengine.platform.iplatformhost/#MicroEngine_Platform_IPlatformHost_Clock) is monotonic and nothing else: it is never derived from frames, steps or the update rate. The loop owns time.
6. Capabilities. Optional features (changing the display mode, diagnostics, a touch screen, display pacing, a precise timer) are found with [TryGetCapability``1](/docs/api/microengine.platform.iplatformhost/#MicroEngine_Platform_IPlatformHost_TryGetCapability__1___0__), never by casting the host. A host's capabilities do not change while it runs (a capability's values may). A host that wraps another forwards the query.
7. Page-driven hosts. A host whose frames are driven by a page (a browser's animation frames) reports [CanBlock](/docs/api/microengine.platform.iplatformhost/#MicroEngine_Platform_IPlatformHost_CanBlock) false and then never blocks: no waits, sleeps or precise delays in any member; the page paces the frames. It reads the surface size from the canvas after start, never from the size requested at creation. It opens the audio output inside the user gesture that starts the game.
8. No time coupling. Nothing a host does depends on how the loop advances time: display pacing, device start-up and audio output are explicit options of the host's creation.

Properties

CanBlock

Whether the host may block its thread to pace frames (a desktop window, a phone, headless runs). False for page-driven hosts (a browser), which must never block: the loop then skips a frame that comes early instead of waiting for it.

C#

bool CanBlock { get; }

Property Value

bool

Clock

The host’s monotonic clock.

C#

IMonotonicClock Clock { get; }

Property Value

IMonotonicClock

MainSurface

The surface the game presents to (its window or canvas), or null when the host has none.

C#

ISurface? MainSurface { get; }

Property Value

ISurface?

Methods

PumpEvents(IEngineEventSink)

Processes the system’s pending events (window, keyboard, gamepad, touch) and delivers those the engine handles to sink, in the order they happened. Called by the loop once at the start of every frame.

C#

bool PumpEvents(IEngineEventSink sink)

Parameters

sink IEngineEventSink

Returns

bool

True when the game can run a frame now; false while it is suspended (between Suspending and Resumed).

TryGetCapability<T>(out T?)

The optional feature of type T this host offers, if it offers one.

C#

bool TryGetCapability<T>(out T? capability) where T : class

Parameters

capability T?

Returns

bool

Type Parameters

T