Platform architecture

CNA snapshot 009d40f5  ·  Development › Architecture Maps  ·  source links pinned to 009d40f5

IPlatform (IPlatform.hpp) owns host integration: subsystem acquisition, windows, event pumping, timing, input services, host services and the seams through which a renderer gets a native surface. Renderers receive narrow window and surface capabilities instead of a platform object, so that the same renderer works whichever of CNA's seven platform implementations created the window. This page states the boundary, the rules an implementation is held to, and the mechanical gates that protect them; the per-backend source tours are the platform backends pages.

Contract shape

PlatformFactory::Create()      default implementation chosen by CNA_PLATFORM
        │                      (Create(name) and GetAvailable() serve the conformance suite)
        ▼
    IPlatform
     ├─ subsystems       AcquireSubsystem / ReleaseSubsystem / IsSubsystemInitialized
     ├─ events           PollEvents(caller-owned batch)  →  input bridge, then Game
     ├─ timing           performance counter, frequency, Delay
     ├─ windows          CreateWindow / AdoptWindow  →  IPlatformWindow
     ├─ services         keyboard, mouse, gamepad, joystick, clipboard, dialogs, filesystem, system info ...
     └─ graphics seams   GetGlContext · GetVulkanSurface · CreateSurfacePresenter
                              │
                              └── RendererSurfaceInfo snapshot + one narrow service ──► renderer

The factory is the single place where an implementation is chosen. Create() builds the one selected by CNA_PLATFORM; Create(name) builds any compiled implementation by name, and GetAvailable() lists them. HEADLESS is compiled into every binary and TERMINAL into every POSIX one, whatever the selection says, because a conformance suite is only worth something with more than one implementation live in one process.

• Subsystems are acquired, not initialized. There is deliberately no platform-wide Initialize() or Shutdown(). PlatformSubsystem (Video, Audio, Gamepad, Haptic, Sensor) is acquired lazily through reference-counted AcquireSubsystem/ReleaseSubsystem; an unpaired release is a no-op, and global native-library lifetime belongs to the embedding application. Nothing is controlled by a process-global switch.
• Capability reports are promises. PlatformCapabilities has 32 flags, every one defaulting to false; it is read once and cached, and querying it per frame is defined as a defect. A service accessor is null exactly when its presence capability is false (quality flags such as exactKeyboardState do not gate presence), and unsupported behavior refuses deterministically with PlatformNotSupportedException naming the missing capability. Capabilities do not change during an instance's lifetime.
• Events are batches. PollEvents(std::vector<PlatformEvent>&) clears and refills a caller-owned vector that the runtime reuses every frame. PlatformEvent is a std::variant of 16 event types, and per-event virtual dispatch is intentionally impossible.
• Native pointers stay at the edge. Native input and event data is mapped into CNA enums and owning values inside the implementation. A renderer receives a RendererSurfaceInfo value (window id, a tagged non-owning NativeWindowHandle whose system field says which of Win32, X11, Wayland, Cocoa, Android, Web, Headless or Terminal its pointers belong to, drawable pixel size and display scale) plus one narrow service if its descriptor asks for it: the GL context service, the Vulkan surface service or a surface presenter. It never receives an IPlatformWindow or a windowing-library type, and it never calls back through the platform to draw.
• The ambient accessor is for the static XNA surface only. Keyboard::GetState(), Mouse::GetState(), StorageDevice and TitleContainer take no context argument, so they reach the platform through GetCurrentPlatform(); Game installs its owned platform there, and code that has a Game should use it directly.

IPlatformSurfacePresenter is a one-finished-frame API, not a drawing API, for a CPU-raster family that owns no swap chain. GraphicsDevice builds a presenter only for a family whose descriptor sets needsSurfacePresenter (only the SOFTWARE descriptor does) and only when the platform reports surfacePresentation without a native window handle. At this snapshot that means SOFTWARE on TERMINAL attached to a TTY; every windowing platform offers a native handle and keeps a CPU renderer off-screen.

The seven implementations

SDL12 and EMSCRIPTEN are reserved and refused, and a host-conditional name is reserved on the hosts that cannot build it (TERMINAL on Windows, WIN32 elsewhere), so the refusal reads as “not here” rather than as a typo. Each backend's source tour, tests and CI cell is on the platform backends page; what each offers a game, with the full capability matrix, is in the Platform Support guide.

Window units and synchronization

Window size and placement APIs distinguish logical units from physical framebuffer pixels. IPlatformWindow::GetClientBounds() and SetSize() are logical; GetPixelSize() is the drawable size in physical pixels and may exceed the logical size under high DPI; GetDisplayScale() relates the two and is 1.0 where the platform reports no HighDpi capability. A renderer sizes its swapchain from the pixel size, never from the logical bounds. Four concerns stay separate: logical client coordinates for input, physical drawable dimensions for back buffers and swapchains, renderer-owned viewport, letterbox and overscan transforms, and the stable WindowId used by events and the renderer registry. Borderless and exclusive fullscreen are distinct modes, and a backend that cannot provide the requested distinction fails the operation instead of reporting the other mode as success.

Window state changes are asynchronous on most systems: a SetSize followed immediately by GetClientBounds may report the old size. Sync() blocks until pending changes have been applied, and it is part of the contract that code whose next step depends on the change calls it; consuming stale dimensions is a common route to an incorrectly sized swapchain. The Headless backend models the asynchrony deliberately so code cannot accidentally depend on immediate application. GraphicsDevice::UpdateViewportFromWindow tolerates a platform window that refuses a size query by logging a warning and keeping the renderer's previous surface, so a resize delivered from inside the event pump cannot end the game by throwing.

Event ordering

The runtime sends each PlatformEvent through the input bridge before applying game-level quit, window and lifecycle handling; that order is what stops an Exit() in the middle of a batch from hiding the remaining events from input. The current implementation of PlatformInputBridge::ProcessEvent is in modules/input/src/Internal/SdlInputBridge.cpp; older prose that names a standalone PlatformInputBridge.cpp is stale. The bridge maps mouse clicks, text input and editing, touch, device connect and disconnect events into the input module. The keyboard, mouse and gamepad state that games read is different: it lives in the platform's own services, whose Update() runs once per frame at the end of Game::PollEvents, after the batch (see the input flow).

Window ids are stable non-zero identifiers within one platform instance. The current runtime deliberately does not filter events by its own window id; that observable behavior, and the whole event-to-state mapping, is pinned by the golden transcript platform-event-semantics.txt and GameEventSemanticsGoldenTest. A new event variant must update the event taxonomy helpers, every implementation's mapper, the input bridge where applicable and that golden transcript.

Required platform gates

python3 tools/platform/sdl_inventory.py --check
python3 tools/platform/sdl_classify.py --check
python3 tools/platform/renderer_sdl_audit.py --check
python3 tools/platform/sdl_ratchet.py --check --strict
python3 tools/platform/hot_path_lint.py
python3 tools/platform/nonproduction_sdl_audit.py --check
python3 tools/platform/check_contract.py

These seven commands live in tools/platform, are listed in the implementer's checklist in docs/platform-abstraction.md, and run in the HEADLESS cell of the platform-contract job of the platform CI workflow (the SDL-containment subset also runs in the x11-sdl-free job). Two of them also run at configure time when a Python 3 interpreter is found: the ratchet (options CNA_PLATFORM_RATCHET and CNA_PLATFORM_RATCHET_STRICT, both ON, which also audits the non-production manifest) and the hot-path lint (CNA_PLATFORM_HOT_PATH_LINT, ON).

• sdl_inventory.py counts every SDL identifier per module and checks that the generated section of plans/plan_platform.md is current; sdl_classify.py assigns each identifier to a contract area and fails on an unclassified one.
• renderer_sdl_audit.py holds the allowlist of renderer families that may use SDL: sdl-renderer and sdl-gpu by identity, fna3d and freedirect by upstream dependency. sdl_ratchet.py records a checked-in budget that may go down and never up; without --strict it only warns.
• hot_path_lint.py rejects platform calls reached through a platform receiver inside per-pixel, per-vertex, per-sample or per-event loops (a justified exception carries CNA_PLATFORM_HOT_PATH_OK: reason); nonproduction_sdl_audit.py keeps SDL use in tests and examples classified and under per-file ceilings; check_contract.py keeps every contract header in the SDL-free probe and documented.

Run focused unit and conformance tests too. The audits protect architecture and source classification; they do not prove event behavior on every host, and the two heuristic checks under-report by design, so a pass is not proof and a failure is always real. The conformance suites are parameterized over PlatformFactory::GetAvailable() and run as EveryImplementation/PlatformConformance.*, EveryImplementation/PlatformWindowConformance.* and EveryImplementation/GameEventSemanticsGoldenTest.*; ContractIsSdlFreeTests.EveryContractHeaderCompilesWithoutSdl proves the contract headers pull in no SDL, Vulkan or GL header. None of them was executed for this page. The last changes under tools/platform before this snapshot were routine upkeep: a Mesa gallium leak-suppression entry for the OpenGL4 tests and two new SDL_GPU example entries in the non-production budget.

Adding host behavior safely

1. Find the narrow platform contract that owns the capability; if none does, add one under the platform contract headers.
2. Define semantics in platform-neutral types. Do not expose an SDL, Win32, X11 or Wayland pointer or an event-lifetime string across the contract.
3. Update every implementation that claims the capability, or narrow its advertised capability: start each implementation with every flag false and flip a flag only when the accessor and its refusal behavior are complete.
4. Trace how Game consumes the event or service and how input state is published (the end of Game::PollEvents).
5. Add contract tests to the parameterized suites, add implementation-specific mapper tests beside them, and run the source gates above.

Adding a whole implementation

The implementer's guide adds these steps: create modules/platform/src/<Name>/ and implement the entire IPlatform surface without subclassing the SDL3 one; add the uppercase name to PlatformSelection.cmake and fail loudly on unsupported hosts instead of falling back; add conditional sources and private native-library links in modules/platform/CMakeLists.txt; register the display name in all three PlatformFactory operations (default selection, named construction, GetAvailable()); give every acquired native resource an explicit owner and test constructor failure as well as teardown order; and add one compatible renderer to the CI matrix rather than multiplying every platform by every renderer. The SDL2 and SDL3 implementations cannot share a process because their entry points collide, which is why CNA_PLATFORM=SDL2 with CNA_AUDIO_PLATFORM=SDL3 (and the reverse) is a configure error.