Native Platforms (X11, Wayland, Win32)

CNA snapshot 009d40f5

The SDL-free platform backends  ·  CNA snapshot 009d40f5  ·  CNA_PLATFORM=X11, WAYLAND, WIN32

What “native” means

A platform implementation owns windows, events, input, timing and host services (clipboard, dialogs, displays, controllers). CNA selects exactly one at configure time with CNA_PLATFORM; all of them implement the same CNA::Platform::IPlatform contract and report what they can do through a set of 32 capability flags. A native backend is one that talks to the operating system's own window-system API and contains no SDL code: source scans and link checks in CNA's test suite keep it that way. Three exist, and each is only offered where it can actually be built.

Each backend is a source directory of its own under modules/platform/src/: X11 has 43 source files, Wayland 34 and Win32 31, against 28 for the SDL3 backend. X11 and Wayland share a few helpers that are not specific to either — XKB key tables, the freedesktop portal client (libdbus, loaded at run time), POSIX timing and Linux evdev controller support (kernel <linux/input.h>, no libudev).

Choosing between SDL3 and a native backend

Native X11

CNA_PLATFORM=X11 is written directly against Xlib and answers the question “can CNA run on a Linux desktop without SDL?” with a build configuration that a CI job builds and runs on every push. Only libX11, libXext and the XKBlib.h header are mandatory; every other extension is optional and switches off exactly one capability when absent, so the backend stays available on stripped-down systems.

Dependencies and what each one gates

The configure log ends its X11 line with a summary such as “X11 + Xext; optional present: Xi, Xrandr, …; absent: …”, which is the quickest way to see which capabilities your build will have.

Behaviour worth knowing

• No HiDPI, by design. X11 has one coordinate space, so highDpi is false and a window's display scale is 1. The session's scale is exposed per display as its content scale.
• Keyboard. Layout-independent scancodes are derived from XKB key names; key releases are real events (nothing is synthesised). Text goes through XIM (Xutf8LookupString), and IME composition is available when the application asks to draw it.
• Clipboard and drag-and-drop. ICCCM selection ownership including INCR, any MIME type, the middle-click PRIMARY selection, and XDND 5 as a drop target.
• Fullscreen. Borderless fullscreen uses the EWMH hint when the window manager advertises it; exclusive fullscreen changes the display mode through XRandR and restores it on exit, and after SIGKILL through a guardian process.
• Message boxes are drawn with Xlib in a window of their own; file dialogs come from the desktop portal when the session bus offers one. Nothing shells out to zenity or kdialog.
• Under Xwayland (X11 on a Wayland desktop) the backend works, but the compositor owns the screen: the global pointer is exact only over your own windows, minimised windows can stay mapped, focus is the compositor's decision, and scaling happens in the compositor. CNA's notes record validation on GNOME 48 with real hardware; that is the project's own record, not a CI result.
• Controllers need no display. Gamepads, joysticks, rumble, motion sensors and force-feedback devices come from the kernel's evdev nodes (Linux only), so they work even for a process that could not reach an X server.

Native Wayland

CNA_PLATFORM=WAYLAND is a genuine Wayland client: libwayland-client, xdg-shell, xkbcommon and the compositor's own protocols, with no SDL, no Xlib and no Xwayland. Window state follows an explicit configure state machine (CreateWindow returns only after the compositor's first configure has been acknowledged), and a compositor that goes away ends the connection cleanly instead of crashing the game.

Dependencies

Behaviour worth knowing

• Scaling. Fractional scale through wp_fractional_scale_v1 and wp_viewporter where offered, integer scale otherwise, so highDpi is true (unlike X11).
• No global pointer, by design. Wayland gives a client neither the pointer position outside its surfaces nor the power to move it, so globalPointer is false and pointer capture, global position and warping refuse with PlatformNotSupportedException.
• Window position belongs to the compositor. WindowDescription x/y/centre are ignored and no “moved” event exists. Exclusive fullscreen is requested but reported as borderless fullscreen: an ordinary Wayland client cannot own a display mode.
• No message box and no tray. Wayland has no dialog protocol, and CNA declined both to embed a font and to launch zenity; draw the dialog with your own SpriteFont. File dialogs are unaffected (the desktop portal draws them).
• Only unprivileged protocols. Nothing from wlr-*, no layer shell, no virtual input, no screen capture — a client that needed those would be a desktop component, not a game.
• The capability set is fixed at start-up. If a compositor later withdraws a global, the corresponding call throws PlatformNotSupportedException naming it rather than silently pretending.
• Software presentation. The wl_shm presenter service exists, but a CPU renderer (SOFTWARE) opens no window on any windowing platform; see Renderers on native platforms.

Native Win32

CNA_PLATFORM=WIN32 implements the platform contract directly on the Windows API: one HWND per window, WGL for OpenGL, StretchDIBits for CPU frames, Raw Input for relative mouse, IFileOpenDialog/IFileSaveDialog for file dialogs, EnumDisplayMonitors for displays. It links only operating-system import libraries — user32, gdi32, opengl32, ole32, shell32, uuid — and resolves vulkan-1.dll at run time, so a machine without a Vulkan driver simply reports vulkanSurface as false. It declares Windows 8.1 (0x0603) as the level its headers target; a source comment says every entry point above a Windows 7 floor is resolved at run time, so the binary itself is not meant to require more (read from source, not executed on Windows 7). It builds with MSVC and with mingw-w64.

What it does not have yet

Each missing capability is reported false, its service accessor returns nullptr, and a gated call raises PlatformNotSupportedException naming the capability — none is a stub that silently succeeds.

Host-process etiquette

• The backend never sets DPI awareness, never raises the timer resolution, never changes the current directory and never takes over the thread's COM apartment. Declare DPI awareness in your manifest; the backend reports values that are coherent with whatever you chose.
• Closing a window is a request. WM_CLOSE becomes CloseRequested and does not destroy the window; closing one of several windows does not quit the process at the platform level. A Game, however, calls Exit() on any CloseRequested without checking which window sent it.
• Window sizes are client sizes (converted through AdjustWindowRectExForDpi).
• If you include <windows.h> together with CNA platform headers, four macros collide with CNA identifiers (CreateWindow, CreateDirectory, MessageBox, GetClassName): #undef them or include the CNA headers first.

Audio on an SDL-free Windows build

Audio is a separate axis, and Windows has no SDL-free audio implementation: ALSA is Linux-only and WASAPI is reserved and refused. A fully SDL-free Win32 build therefore selects CNA_AUDIO_PLATFORM=NULL (silent). If you need sound on Windows, keep SDL3 audio (which needs SDL, so CNA_ENABLE_SDL cannot be OFF). See Audio System.

Capability differences

The platform contract exposes 32 boolean capabilities. Each backend reports what it can really do, and a false capability means the call refuses deterministically with PlatformNotSupportedException. The full seven-platform matrix is on Platform Support; here are the columns that matter for choosing a native backend, with SDL3 for comparison. “If…” means the answer depends on the running system and is decided once, when the platform object is created.

Sources: modules/platform/src/{Sdl3,X11,Wayland,Win32}/*Platform.cpp at snapshot 009d40f5, read directly.

Building without SDL

CNA_ENABLE_SDL decides whether the vendored SDL3 sub-build is configured at all.

With OFF, these selections are refused with a message that begins “CNA_ENABLE_SDL=OFF, but this configuration genuinely requires SDL”: platform SDL3 or SDL2; audio SDL3 or SDL2; and the renderers SDL_RENDERER, SDL_GPU, FNA3D and FREEDIRECT (also when they appear only in CNA_GRAPHICS_RENDERERS). Note that the default audio is SDL3, so an SDL-free configure must always choose NULL or ALSA explicitly.

Recipes

The first is the CI-proven, sound-free X11 cell; the second adds real renderers and ALSA audio. Both were run by CI at this snapshot; the exact flags are copied from the workflow.

# SDL-free X11, headless renderer, silent audio (workflow job "x11-sdl-free")
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCNA_ENABLE_SDL=OFF \
  -DCNA_PLATFORM=X11 \
  -DCNA_GRAPHICS_RENDERER=HEADLESS \
  -DCNA_AUDIO_PLATFORM=NULL \
  -DCNA_ENABLE_NET=OFF

# SDL-free X11 with OpenGL 3.3, Vulkan, software and headless renderers
# selectable at run time, and ALSA audio (job "x11-sdl-free-gpu")
cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DCNA_ENABLE_SDL=OFF \
  -DCNA_PLATFORM=X11 \
  -DCNA_GRAPHICS_RENDERER=OPENGL33 \
  -DCNA_GRAPHICS_RENDERERS="OPENGL33;VULKAN;SOFTWARE;HEADLESS" \
  -DCNA_AUDIO_PLATFORM=ALSA \
  -DCNA_ENABLE_NET=OFF

A native-Wayland recipe and a mingw-w64 Windows recipe are in Build recipes. Step-by-step versions with run commands are tutorials 135, 136 and 138.

Proving that no SDL is in the binary

ldd build/cna_demo_2d | grep -i sdl                 # prints nothing
readelf -d build/cna_demo_2d | grep -i 'NEEDED.*sdl'  # prints nothing
nm -D --undefined-only build/cna_demo_2d | grep ' SDL_'   # prints nothing
find build -iname '*SDL2*' -o -iname '*SDL3*'         # no SDL artifact in the build tree

CI runs equivalent checks, plus one that asserts libasound is not a NEEDED entry: ALSA is dlopened at run time so that a machine without it still starts.

Renderers on native platforms

The platform and renderer axes are independent, but a renderer needs services the platform must offer (a native window handle, a GL context, a Vulkan surface). What that means for the native backends:

Build recipes

These assume the workspace layout from Building: cna on the next branch, sharp-runtime on its next branch, and — for the GL-family renderers — easy-gl and meta-gl next to them. Package names are Debian/Ubuntu (CI uses Ubuntu 24.04 and GCC 14).

X11

sudo apt-get install -y g++-14 cmake ninja-build pkg-config \
  libx11-dev libxext-dev libxrandr-dev libxi-dev libxcursor-dev libxfixes-dev libxss-dev \
  libgl-dev libglx-dev libvulkan-dev libdbus-1-dev libasound2-dev

cd cna
git submodule update --init third_party/draco     # or add -DCNA_ENABLE_DRACO=OFF
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCNA_ENABLE_SDL=OFF -DCNA_PLATFORM=X11 \
  -DCNA_GRAPHICS_RENDERER=OPENGL33 -DCNA_AUDIO_PLATFORM=NULL \
  -DCNA_BUILD_TESTS=OFF -DCNA_ENABLE_NET=OFF
cmake --build build --target cna_demo_2d
(cd build && ./cna_demo_2d)

Only libx11-dev and libxext-dev are mandatory. Add libasound2-dev only for CNA_AUDIO_PLATFORM=ALSA. Tutorial 135 walks through this end to end.

Wayland

sudo apt-get install -y g++-14 cmake ninja-build pkg-config \
  libwayland-dev libwayland-bin wayland-protocols libxkbcommon-dev \
  libegl-dev libvulkan-dev libdbus-1-dev

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DCNA_ENABLE_SDL=OFF -DCNA_PLATFORM=WAYLAND \
  -DCNA_GRAPHICS_RENDERER=OPENGL33 -DCNA_AUDIO_PLATFORM=NULL \
  -DCNA_BUILD_TESTS=OFF -DCNA_ENABLE_NET=OFF
cmake --build build --target cna_demo_2d

This is the documented recipe; it is not exercised by CI. Tutorial 136 covers it honestly, including what to check first.

Win32 (from Linux with mingw-w64, or natively)

# From Linux, targeting Windows
sudo apt-get install -y g++-mingw-w64-x86-64 cmake ninja-build
cmake -S . -B build-windows -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/mingw-w64.cmake \
  -DCNA_ENABLE_SDL=OFF -DCNA_PLATFORM=WIN32 \
  -DCNA_AUDIO_PLATFORM=NULL -DCNA_GRAPHICS_RENDERER=DIRECTX11 \
  -DCNA_BUILD_TESTS=OFF -DCNA_BUILD_EXAMPLES=OFF

# Natively on Windows (MSVC)
cmake -S . -B build -DCNA_PLATFORM=WIN32 -DCNA_GRAPHICS_RENDERER=DIRECTX11

The full CNA + DirectX build for Windows is manual CI only; the automatic Windows evidence is the platform harness described in the next section.

Validation harnesses

CNA ships its own harnesses for the native backends. They are ordinary CTest entries or standalone programs in the repository, so you can re-run them.

A minimal way to see which platforms your own binary contains and what the active one can do (this compiles against the snapshot's headers):

#include <iostream>

#include "CNA/Platform/IPlatform.hpp"
#include "CNA/Platform/PlatformCapabilities.hpp"
#include "CNA/Platform/PlatformFactory.hpp"

int main() {
    using CNA::Platform::PlatformFactory;

    // Every platform implementation compiled into this binary, and the default one.
    for (const std::string& name : PlatformFactory::GetAvailable()) {
        std::cout << "available: " << name << '\n';
    }
    std::cout << "default:   " << PlatformFactory::GetDefaultName() << '\n';

    auto platform = PlatformFactory::Create();
    const auto caps = platform->GetCapabilities();
    std::cout << std::boolalpha
              << "openGlContext=" << caps.openGlContext
              << " vulkanSurface=" << caps.vulkanSurface
              << " highDpi=" << caps.highDpi
              << " gamepad=" << caps.gamepad
              << " ime=" << caps.ime
              << " globalPointer=" << caps.globalPointer << '\n';
    return 0;
}

Exactly one implementation is compiled as the default (CNA_PLATFORM_<NAME>); HEADLESS is always compiled in, and TERMINAL is compiled on every non-Windows build, so GetAvailable() can list more than one name. There is no CNA_PLATFORM environment variable: the platform is a build-time choice.

What CI is configured to check

All of it lives in .github/workflows/platform-ci.yml and runs on push and pull request to next, develop and main unless noted. This section describes what those jobs are configured to build, run and assert, read from the workflow file; we did not inspect run results. These jobs fetch sharp-runtime through scripts/ci/clone_siblings.sh, which picks its next branch on a push to next — unlike several other workflows that pin an older revision (see Platform Support). Every Linux job runs under a virtual X server (Xvfb) and Mesa's software GL and Vulkan drivers; none is a real desktop or a physical GPU.

The Win32 jobs build tools/platform/standalone_tests, not the full CNA engine: the automatic Windows evidence is about the platform module, not about a DirectX game. The native-MSVC, Direct3D and GDI lanes of the full engine are manual workflows.

Honest limits

• Wayland has no CI and its local validation is recorded only in CNA's own documents.
• X11 evidence comes from Xvfb. A physical GPU's GLX driver, a real compositor's fullscreen behaviour, multi-monitor layouts and hot-plug, real input devices and language-specific input-method engines are outside what CI can show; CNA's notes record manual validation on real desktops, but that is not a gate.
• Win32 has no gamepads, no IME, no drag-and-drop and text-only clipboard; the full-engine Windows lanes are manual.
• No SDL-free audio on Windows or macOS. ALSA is Linux-only; OPENAL and WASAPI are reserved and refused.
• SDL-free means no SDL-based renderers (SDL_RENDERER, SDL_GPU, FNA3D, FREEDIRECT).
• X11 on other Unixes (FreeBSD, OpenBSD, NetBSD) is expected to build but is untested; native Wayland is not offered on macOS, iOS, Android or the web, and native X11 is not offered on iOS, Android or the web (on macOS it is offered whenever libX11, libXext and XKBlib.h are found; not exercised).
• The native backends are new in this development snapshot on next; they are not part of the v0.1.0-alpha.1 tag.

Further reading

• Platform Support — the axes, the seven-platform capability matrix, per-OS status and renderer availability.
• Building CNA — branches, siblings, submodules, presets and every CMake option.
• Audio System — ALSA, CNA's own mixer and CNA_AUDIO_DEVICE.
• Tutorials: 135 Native X11, 136 Native Wayland, 137 ALSA audio, 138 SDL-free build, 139 Terminal platform.
• CNA's own manuals at this snapshot: platform-x11.md, platform-wayland.md, platform-win32.md, testing-x11-desktop.md.