Platform Support

Per-platform status, stated at the level it has actually been verified  ·  CNA snapshot c1c316b9

Four separate axes

In this snapshot, “backend” is still too ambiguous to be useful. CNA makes four different decisions, plus one build switch that decides whether SDL is present at all:

The platform implementation implements CNA::Platform::IPlatform and supplies narrow services to a renderer. It does not decide the renderer, audio implementation or target OS. This is also why the old public CNA::Platform enum became CNA::TargetPlatform (Desktop, Android, iOS, Web): CNA::Platform now names the host-integration namespace. The axes are independent with hard exclusions, listed under combination rules.

Platform and audio implementations

# A display-free simulation that still uses SDL3 audio
cmake -S . -B build-headless \
  -DCNA_PLATFORM=HEADLESS \
  -DCNA_AUDIO_PLATFORM=SDL3 \
  -DCNA_GRAPHICS_RENDERER=HEADLESS


# No SDL anywhere: a windowless build with ALSA audio and CNA's own mixer (Linux)
cmake -S . -B build-sdl-free -G Ninja \
  -DCNA_ENABLE_SDL=OFF \
  -DCNA_PLATFORM=HEADLESS \
  -DCNA_AUDIO_PLATFORM=ALSA \
  -DCNA_GRAPHICS_RENDERER=HEADLESS

# POSIX terminal host: CPU renderers only
cmake -S . -B build-terminal \
  -DCNA_PLATFORM=TERMINAL \
  -DCNA_AUDIO_PLATFORM=NULL \
  -DCNA_GRAPHICS_RENDERER=SOFTWARE

The three platform implementations

The three audio implementations at a glance

Combination rules and hard exclusions

• TERMINAL accepts only CPU renderers: SOFTWARE, HEADLESS, STUB.
• CNA_ENABLE_SDL=OFF refuses platform SDL3, audio SDL3 and the three SDL-linked renderers, with a message naming the reason.
• Platform gates: TERMINAL only off Windows; ALSA only on Linux. A windowed build on any operating system uses SDL3.
• Renderer combinations in CNA_GRAPHICS_RENDERERS obey one rule: identities gated to different operating systems cannot be mixed. See Runtime Renderer Selection.
• A name outside the 14 public renderer identities is a configure-time error.

Window systems through SDL3, and SDL-free builds

SDL3 is CNA’s one windowing implementation, and the window system is SDL’s choice of video driver rather than a separate CNA platform: Windows uses SDL’s windows driver, a Linux desktop its x11 or wayland driver, and macOS, iOS, Android and the browser SDL’s own drivers for them. The native handles a renderer needs still reach it unchanged — an HWND, an X11 Display* and window, a Wayland wl_display* and wl_surface* — through NativeWindowHandle and its TryGetWin32/TryGetX11/TryGetWayland accessors (and CNA_NATIVE_WINDOW_SYSTEM_* in the C API). The dedicated page, Windows, X11 and Wayland, has the details and the evidence.

Two other tutorials cover the remaining pieces: Tutorial 137 (ALSA audio with CNA's own mixer) and Tutorial 139 (the POSIX terminal platform).

Capability matrix (32 flags)

Every platform reports a fixed set of 32 boolean capabilities through IPlatform::GetCapabilities(). A capability is true only when the service behind it is really wired up; a false one means the call refuses deterministically with PlatformNotSupportedException (never a silent no-op). “If…” entries depend on the machine and are decided once, when the platform is created. Three flags — dragAndDrop, primarySelection, clipboardData — were appended since alpha.1's 29.

Read from Sdl3Platform.cpp, TerminalPlatform.cpp and HeadlessPlatform.cpp at snapshot c1c316b9. The SDL3 column is the SDL3 platform’s own report; whether SDL’s video driver on a given system can deliver a service (a global pointer on Wayland, for example) is decided by SDL and the window system at run time. Touch and pen events (TouchEvent) are delivered by SDL3.

What "supported" means here

"Supported" is doing a lot of work in most framework documentation. This page avoids the word and names the level instead, because the difference between "there is code for it" and "someone ran it" is exactly the difference that costs you a weekend.

These levels do not imply each other. The repository contains MinGW/Wine paths, but no automatic workflow uses them; the native-Windows lanes still require manual dispatch. macOS and iOS have build workflows that trigger automatically, and a recorded campaign on a physical Mac (see macOS). Android has source/NDK wiring and no workflow.

Platform matrix

Status by operating system and platform implementation

Only what CI or code proves. CI = an automatic workflow (push or pull request to next, develop, main) builds or tests it. Manual CI = a workflow exists but runs only on workflow_dispatch. Code = sources and CMake wiring, no workflow. Local = only in-tree documents or scripts claim validation.

Renderer availability by operating system

Which identities CMake will accept for each target. “Gated” means a hard FATAL_ERROR on any other target; “not gated” means CMake has no operating-system rule (the renderer may still need its own dependency: a Vulkan loader, a fetched library, a sibling checkout). This is configure-time acceptance, not a statement that every accepted pair has been run.

That is 2 + 1 + 1 platform-gated identities and 10 that are not gated by operating system, for the 14 in total. The iOS allow-list can be overridden with CNA_APPLE_ALLOW_UNVALIDATED_RENDERER=ON for experiments only; that is not a support claim. TERMINAL further restricts the choice to SOFTWARE, HEADLESS and STUB. Which native window services a renderer needs is on Windows, X11 and Wayland.

Default selection per operating system

There is no per-OS default for the platform or audio axes — both are SDL3 everywhere — and no CNA_PLATFORM environment variable. Only the renderer has run-time selection (CNA_GRAPHICS_RENDERER in the environment, in a multi-renderer build).

Linux

Linux is CNA's primary development platform and carries most of its CI. It is where the largest number of renderers can be selected, where all three platform implementations are offered, and where the project is developed on real hardware — the default renderer here is OPENGLES3, one of the three EasyGL profiles.

SDL3 (the default) works on X11 and Wayland sessions alike, through SDL’s x11 and wayland video drivers; SDL_VIDEO_DRIVER chooses between them when both are available. HEADLESS and TERMINAL need no display server. See Windows, X11 and Wayland.

The Windows-gated renderers are also driven from Linux: they are cross-compiled with MinGW-w64 and executed under Wine, so a Linux workstation is in practice the machine where the Direct3D ladder gets exercised too. See Windows for what that does and does not prove.

Practical requirements: the sharp-runtime sibling checkout (on the branch matching CNA’s) for every build, easy-gl plus meta-gl for the default renderer, a C++23 compiler (CI uses GCC 14), and, for a windowed build, the X11/GL/Vulkan/ALSA/D-Bus development packages so the vendored SDL3 gets real video drivers. FFmpeg development packages are optional now. Building has the exact commands and package lists.

Windows

Windows has the largest platform-exclusive renderer set in the project: 2 renderers refuse to configure anywhere else — DIRECTX9 and DIRECTX11. The default renderer on Windows is SDL_RENDERER. Windows windows come from SDL3’s windows video driver, which hands the Direct3D and Vulkan renderers the HWND they present into; HEADLESS is the windowless alternative. An SDL-free Windows build is therefore windowless, and must also use CNA_AUDIO_PLATFORM=NULL.

Two further Windows facts worth knowing before you plan a release:

• FFmpeg video is never built for Windows. CNA_ENABLE_VIDEO=AUTO silently falls back to the no-video backend on Windows and MinGW, and ON is a configure error. Video and VideoPlayer still compile and link; without a decoder they throw System::NotSupportedException at run time.
• The MinGW cross-build is not covered by CI. Apart from a MinGW header-compatibility check for the experimental C API, building the engine for Windows is exercised by hand (MinGW + Wine/DXVK) or by the manual MSVC workflows.

Web (Emscripten)

The web target is real and has a browser build workflow. WEBGL2 is Emscripten-only and the default; WEBGPU also has a browser route. The strongest evidence is the 90 C++ sample builds playable at samples.libcna.com; saves persist in the browser’s IndexedDB, and games that start threads use a threaded build. The multi-renderer Emscripten job configures and links a WEBGL2 + WEBGPU bundle, and the workflow pins emsdk 6.0.3. The platform is SDL3 here by default and in every browser workflow (CMake’s platform selection would also list HEADLESS and TERMINAL, neither of which is exercised on the web); CNA_PLATFORM=EMSCRIPTEN is reserved and refused.

Video links but cannot decode here: the Video/VideoPlayer types are part of every build, no FFmpeg backend exists for Emscripten, and playback throws System::NotSupportedException at run time. Networking discovery does not work on Emscripten either.

Serve the generated .html, .js and .wasm from a local web server; browsers block direct file:// access. Configure with emcmake: emcmake cmake --preset web — the web preset carries no toolchain file, so cmake --preset web alone would configure natively.

macOS

macOS has a recorded full-suite run on real hardware. CNA’s Apple stabilization campaign ran on a physical Mac mini M4 (Apple M4, arm64, 16 GB, macOS 27.0.1, Xcode 27, Apple clang 21), on SDL3 — Apple is reached through SDL’s Cocoa video driver, not through a CNA backend of its own. Seven renderer trees ran their complete CTest suites there with no failing test; every skip declines by name:

The runs were made with the console locked, so macOS reported every window occluded: the readback-based pixel tests ran, but on-screen presentation and vsync pacing were never observed. OPENGLES3 does not apply (macOS has no native OpenGL ES; OPENGL33 uses Apple’s 4.1 core context), VULKAN through MoltenVK was out of scope, no Intel Mac was run, and WEBGL2 is a browser renderer. CNA’s own verdict on METAL is Supported but not primary-production: compiled XNA effects need -DCNA_METAL_COMPILED_EFFECTS=ON, custom MSL effects are SpriteBatch-scoped, PresentInterval.Two presents as One, the sampler LOD bias needs the macOS 26 SDK and OS, and no soak run has bounded its caches. See Graphics Renderers and Tutorial 109.

CI is a separate, narrower layer: apple-ci.yml builds CnaTests on SDL_RENDERER on GitHub’s macos-26 runners, runs the portable suites and launches a self-contained .app, and metal-macos-ci.yml builds METAL and runs its ^Metal tests on the runners’ paravirtual GPU, which cannot run Metal shader validation. CNA records no green hosted run after the campaign’s last workflow change.

Practical notes. The macOS deployment floor is 13.3 (a lower CNA_MACOS_DEPLOYMENT_TARGET is a configure error, because CNA needs Apple’s floating-point std::to_chars); Xcode 15.4 is too old, CI uses Xcode 26. FFmpeg is optional (CNA_ENABLE_VIDEO=AUTO uses it when found), but Homebrew’s FFmpeg is built for the host macOS, so a binary linked against it does not start on an older macOS whatever the deployment target says; use CNA_ENABLE_VIDEO=OFF or an FFmpeg built for the floor. Online Gamer Services sessions need a libcurl with WebSocket support (Homebrew’s curl): Apple’s system libcurl lacks it, and the relay then refuses by name. SystemLink discovery between processes works on macOS. SDL3 is the platform; CMake also offers HEADLESS and TERMINAL, which no macOS lane exercises.

Android

Android is genuinely wired rather than aspirational: the NDK toolchain path is in the build system, the code paths exist, and the NDK sensor implementations are real — Compass and Motion are in fact Android-only and report NotSupported elsewhere. See Sensors.

iOS and tvOS

iOS support is experimental. The snapshot ships an iOS toolchain file (cmake/toolchains/ios.cmake, with CNA_IOS_SIMULATOR=ON for the simulator SDK) and admits two renderers: SDL_RENDERER and the native METAL renderer, which attaches its CAMetalLayer view to SDL’s UIWindow. A configure needs -DCNA_ENABLE_NET=OFF (the iOS SDK ships no libcurl), so iOS builds have no networking, and FFmpeg video is off. The deployment floor is iOS 16.3.

What has been demonstrated, at its real level:

• iOS Simulator execution with pixel evidence. In the iOS Simulator (iPhone 17 profile) on the Mac mini M4, cna_ios_smoke runs and cna_ios_pixel_probe reads back the METAL frame. The first campaign run was exact on 29 of 31 launches, the two all-zero results being the first two after the initial install; the cause was later found in SDL’s UIKit view-frame handling and patched in CNA’s vendored SDL, after which the stricter probe (frame 1 and the ten frames after it) was exact in 8 of 8 launches.
• A final-linked device build. Device apps for SDL_RENDERER and METAL compile and link (arm64, iOS 16.3, system frameworks only). They were never run: there was no physical device or signing identity.
• CI, as configured. apple-ci.yml builds device and simulator apps for both renderers and, on the simulator, launches the smoke app and the METAL pixel probe.

No physical iPhone or iPad has run CNA, so nothing here establishes device pixels, real touch input, audio, storage, background and resume, or performance. CNA_APPLE_ALLOW_UNVALIDATED_RENDERER=ON merely permits experiments outside the allow-list; it is not a support claim. tvOS has no validated path.

What CI actually covers

This snapshot contains 18 GitHub Actions workflow files (24 jobs; 16 files run automatically on pushes and pull requests to next, develop and main, and two are manual or branch-specific). They cover general tests, platform conformance, multi-renderer Linux and Emscripten builds, Apple/Metal, declared C API compatibility/release gates, and focused renderer/subsystem checks. Trigger and evidence still matter more than the raw file count. The general job configures OPENGLES3, runs a full default build and an unfiltered ctest, and tolerates a single named known failure.

How to read the matrix

The snapshot has much broader automated coverage than alpha.1, but a workflow is not universal proof:

• The Windows Direct3D, SDL3-on-Windows and content-pipeline lanes remain manual, so their existence is not an automatic merge gate.
• The iOS device lane final-links; the simulator lane launches a smoke app. Neither establishes physical-device or full-game correctness.
• The Emscripten multi-renderer lane covers configuration and linking; the runtime evidence for the web is the published sample gallery and CNA.NET’s headless-Chromium runs.
• Android has source and NDK wiring but no automatic workflow.
• Every Linux job runs on a virtual X server (or a headless Weston) with Mesa’s software drivers, and the macOS jobs on GitHub’s virtual Macs. None provides a physical-GPU or real-desktop run; the physical-hardware evidence comes from recorded campaigns.

Not exercised by any workflow: Android, tvOS, CNA_BUILD_C_API=ON builds, Clang on Linux (except C header compatibility), CNA_ENABLE_VIDEO=OFF on Linux, the full engine + DirectX under Wine/MinGW, and the GPU pixel/oracle corpus (run locally, by hand). Verification & Known Issues covers the wider testing picture, and Graphics Renderers the per-renderer side of it.

Where video is available