PlatformAPI reference
Class SdlPlatform
Namespace: MicroEngine.Sdl
Assembly: MicroEngine.Sdl.dll
Guide: Backends and platforms
SDL3-backed platform. Games draw through SDL’s 2D renderer into a texture of the virtual size, which is scaled to
the window by the largest integer factor that fits (letterboxed), as on the raylib platform. SDL chooses the
graphics API per system (Direct3D, Metal, OpenGL, OpenGL ES, Vulkan, or its software renderer); the
SDL_RENDER_DRIVER environment variable forces one (for example software on a machine without a GPU).
Fingers go to the game’s on-screen controls through ITouchScreen (SdlTouchScreen), which
also reports the window’s safe area and density; a system that sends the app to the background suspends it
(Suspending). Its capabilities (TryGetCapability``1):
IDisplayControl, IPlatformDiagnostics, IDisplayPacing,
ITouchScreen and, outside browsers, IPreciseDelay.
public sealed class SdlPlatform : IPlatform, IPlatformHost, IDisposable, IPlatformDiagnostics, IDisplayControl, IDisplayPacing, IPreciseDelay, IMonotonicClock, IScreenView, IViewCaptureInheritance
Implements
IPlatform, IPlatformHost, IDisposable, IPlatformDiagnostics, IDisplayControl, IDisplayPacing, IPreciseDelay, IMonotonicClock, IScreenView, IViewCapture
Remarks
In a browser (SDL compiled to WebAssembly, BrowserProfile) the platform is page-driven
(CanBlock is false): the page calls one frame per animation frame, so nothing waits (no VSync, no
delay, no wait while suspended); the window is the page’s canvas, sized from the canvas after start; a hidden page
suspends the game; touches, safe-area insets, density and vibration come from the page (BrowserPage);
sound plays through the page’s AudioWorklet (SdlAudioDevice); full screen and the window’s place
belong to the page. A few SDL calls go through declarations of the engine’s own there (SdlWeb), because .NET’s
WebAssembly interpreter mispasses SDL3-CS’s 64-bit enum parameters.
Constructors
SdlPlatform(PlatformRequest, string?)
Opens the SDL window, renderer and (unless the request says otherwise) audio for request, with
the audio device and extra input sources the request supplies. Hosts usually go through Profile or
CreateProfile instead.
public SdlPlatform(PlatformRequest request, string? renderer = null)Parameters
request PlatformRequest
The game’s settings and window options.
renderer string?
An SDL render driver name (see RenderDrivers), or null to let SDL choose.
Fields
GpuDevice
The tier-1 graphics device (Device, –graphics sdl-gpu): SDL_GPU (Direct3D 12,
Vulkan, Metal) with custom shaders and depth, which the 3D path needs. A system without an SDL_GPU driver refuses
it when the platform starts, saying why. On-screen touch controls are not drawn on it.
public const string GpuDevice = "sdl-gpu"Field Value
RendererDevice
The default graphics device (Device): SDL’s 2D renderer behind the device contract, tier 0.
public const string RendererDevice = "sdl-renderer"Field Value
Properties
Audio
Plays sound; a silent device when there is no audio.
public IAudioDevice Audio { get; }Property Value
CanBlock
True on SDL’s native hosts, which own their thread; false in a browser, whose page drives the frames.
public bool CanBlock { get; }Property Value
Canvas
The canvas the game draws into, with the 2D batcher’s counts for the last frame.
public DeviceCanvas Canvas { get; }Property Value
Clock
SDL’s nanosecond ticks since the platform opened, in seconds (the platform is its own clock).
public IMonotonicClock Clock { get; }Property Value
CurrentDisplay
Index in Displays of the display the window is on; -1 when unknown.
public int CurrentDisplay { get; }Property Value
Device
The graphics device the platform draws with: SDL’s renderer behind the device contract (SdlRendererDevice),
or SDL_GPU (SdlGpuDevice) when Device is GpuDevice.
public GraphicsDeviceBase Device { get; }Property Value
Diagnostics
The facts, read when asked (a value may change, such as the display’s refresh rate).
public IReadOnlyDictionary<string, string> Diagnostics { get; }Property Value
IReadOnlyDictionary<string, string>
DisplayRate
The refresh rate of the display the window is on while VSync paces the frames; 0 otherwise.
public double DisplayRate { get; }Property Value
Displays
The displays the system reports, in its order.
public IReadOnlyList<DisplayInfo> Displays { get; }Property Value
Graphics
Creates textures.
public IGraphicsDevice Graphics { get; }Property Value
GraphicsDeviceName
The graphics device the platform draws with: RendererDevice or GpuDevice.
public string GraphicsDeviceName { get; }Property Value
Input
The keyboard, gamepads and mouse as a polled source, read together with the request’s extra sources. The engine reads SDL’s input as events instead (the IInputBackend capability).
public IInputSource Input { get; }Property Value
Letterbox
Colour of the window around the frame. Starts as Letterbox; the start screen sets its own colour while it shows. Platforms without a window keep it and ignore it.
public Color Letterbox { get; set; }Property Value
MainSurface
The window: an SDL_Window* as NativeWindow, its size in pixels and density.
public ISurface MainSurface { get; }Property Value
Now
Seconds since an arbitrary start (the host’s creation); never decreases.
public double Now { get; }Property Value
Profile
The SDL3 platform as a catalog entry for Windows, Linux, macOS, Android and iOS. A browser page uses BrowserProfile, which knows its page.
public static PlatformProfile Profile { get; }Property Value
RenderDrivers
The render drivers this SDL build offers on this system, in SDL’s order of preference.
public static IReadOnlyList<string> RenderDrivers { get; }Property Value
RendererName
The graphics API in use, for logs and tests: SDL_Renderer’s driver (“direct3d11”, “metal”, “opengl”, “software”…), or “sdl-gpu” and the SDL_GPU API (“sdl-gpu vulkan”) on the tier-1 device.
public string RendererName { get; }Property Value
Suspended
Whether the system took the app away (a phone app in the background, a hidden page); no frame runs meanwhile.
public bool Suspended { get; }Property Value
Touch
The touch screen (also the ITouchScreen capability).
public ITouchScreen Touch { get; }Property Value
VSync
Whether frames wait for the display’s refresh.
public bool VSync { get; }Property Value
WindowMode
The window’s current mode.
public WindowMode WindowMode { get; }Property Value
Methods
BeginFrame()
Starts a frame and returns the renderer that draws into the virtual canvas.
public IRenderer BeginFrame()Returns
BrowserProfile(BrowserPage)
The SDL3 platform of a browser page, named sdl: the WebGL canvas, page input and Web Audio sound, with the
touches, screen facts, visibility and vibration of page. The browser host offers this
profile; a game’s composition may offer others.
public static PlatformProfile BrowserProfile(BrowserPage page)Parameters
page BrowserPage
Returns
Exceptions
page is null.
CreateProfile(string?)
The SDL3 platform with a fixed render driver (“direct3d11”, “direct3d12”, “metal”, “opengl”, “opengles2”,
“vulkan”, “gpu”, “software”), named sdl-<driver>; null lets SDL choose (the sdl profile).
A driver this system lacks fails when the platform is created, naming the drivers it has.
public static PlatformProfile CreateProfile(string? renderer = null)Parameters
renderer string?
Returns
Delay(double)
Waits with SDL’s precise delay (a high-resolution timer, then a short spin); never offered in a browser, whose page cannot be blocked.
public void Delay(double seconds)Parameters
seconds double
Dispose()
Closes the window, the renderer and the audio device the platform opened.
public void Dispose()EndFrame()
Finishes the frame and presents it.
public void EndFrame()MoveToDisplay(int)
Moves the window to the centre of display index; a full-screen window follows to that display.
public bool MoveToDisplay(int index)Parameters
index int
Returns
PumpEvents(IEngineEventSink)
Processes SDL’s pending events and delivers the engine’s: a trip to the background (latched by the lifecycle
watch, so one that ended before this pump is still delivered as Suspending then Resumed), one quit
request however many close and quit events arrived together, focus changes and size changes of the window.
While suspended it waits 50 ms instead of spinning, except in a browser, whose page stops calling while hidden.
public bool PumpEvents(IEngineEventSink sink)Parameters
sink IEngineEventSink
Returns
SaveScreenshot(string)
Writes the most recently completed virtual frame as a PNG.
public void SaveScreenshot(string path)Parameters
path string
SetVSync(bool)
Turns VSync on or off; hidden windows and requests that do not wait for the display keep it off.
public bool SetVSync(bool on)Parameters
on bool
Returns
SetWindowMode(WindowMode)
Changes the window’s mode; phones keep theirs (always full screen), and a page owns its full screen (the Fullscreen API needs a gesture).
public bool SetWindowMode(WindowMode mode)Parameters
mode WindowMode
Returns
ToString()
“SDL renderer” followed by the name of the render driver in use, or “SDL sdl-gpu” and the API.
public override string ToString()Returns
ToggleFullscreen()
Switches between the window and borderless full screen (exclusive full screen goes back to the window).
public void ToggleFullscreen()TryGetCapability<T>(out T?)
The optional feature of type T this host offers, if it offers one.
public bool TryGetCapability<T>(out T? capability) where T : classParameters
capability T?
Returns
Type Parameters
T