Tutorial 109: macOS on Apple Silicon

CNA Tutorials  ·  Renderers  ·  CNA snapshot 3b43bd86

CNA has no macOS-only renderer. A macOS build uses the same renderers as Linux, through SDL3’s Cocoa video driver: SDL_GPU — CNA’s modern native path, on SDL’s Metal GPU driver — is the default, and OPENGL33, WEBGPU, FNA3D and SOFTWARE are the alternatives. OPENGLES3 does not apply (macOS has no native OpenGL ES), DIRECTX9 is Windows-only and WEBGL2 browser-only.

Apple targets, floors and what is refused

macOS on Apple silicon (arm64) is the Apple target CNA builds and tests natively. Intel and universal macOS builds are configurable but not CI-verified. iOS and iPadOS are experimental (below), and tvOS, watchOS and visionOS are refused at configure time.

Deployment floor. CNA's macOS floor is 13.3 (CNA_MACOS_DEPLOYMENT_TARGET; iOS 16.3), a hard lower bound because CNA and sharp-runtime use Apple’s floating-point std::to_chars. A binary that links Homebrew's FFmpeg starts only on the macOS that FFmpeg was built for, whatever the floor says; build with -DCNA_ENABLE_VIDEO=OFF or an FFmpeg built for the floor if that matters.

iOS/iPadOS. On iOS the Apple allow-list admits exactly two renderers, SOFTWARE and SDL_GPU; any other renderer is a configure error unless the explicitly unsupported -DCNA_APPLE_ALLOW_UNVALIDATED_RENDERER=ON is given. SDL_GPU is allowed but has never been built for iOS. CI final-links a one-frame smoke app with SOFTWARE for device and simulator and launches the simulator build; the device build has never run on a physical iPhone or iPad. An iOS configure needs -DCNA_ENABLE_NET=OFF, because the iOS SDK ships no libcurl.

What SDL does, and where the renderer takes over

The division of labour is worth knowing if you are debugging a window-level problem:

SDL_GPU feeds SDL SPIR-V; on Apple, SDL_shadercross (fetched, with SPIRV-Cross, and on by default there through CNA_SDL_GPU_SHADERCROSS) translates the renderer’s stock shaders for SDL’s Metal driver. On Apple, SDL's Cocoa and UIKit drivers create windows only on the process's main thread, so create and run the game there.

No Retina back buffer. CNA creates the game window without SDL’s high-pixel-density flag, so, by SDL3’s documented behaviour, the back buffer is sized in points and the system scales it to the display — XNA's model of a back buffer sized in window pixels. Retina-resolution rendering is not offered at this snapshot and has not been measured.

Building it

brew install cmake ninja ccache ffmpeg nlohmann-json
# FFmpeg is optional; nlohmann-json is needed by Gamer Services and networking

# Next to cna/: sharp-runtime on its next branch, as on every platform
cmake -S . -B build-macos \
  -DCNA_GRAPHICS_RENDERER=SDL_GPU \
  -DCNA_BUILD_TESTS=ON \
  -DCNA_USE_CCACHE=ON
cmake --build build-macos --parallel

# The configuration macOS CI builds and runs: the CPU renderer
cmake -S . -B build-macos-software -DCNA_GRAPHICS_RENDERER=SOFTWARE -DCNA_BUILD_TESTS=ON
cmake --build build-macos-software --parallel

The repository’s macos preset (cmake --preset macos) is a Release SDL_GPU build with tests and examples on. OPENGL33 additionally needs the easy-gl and meta-gl sibling checkouts (v0.1.1 and v0.4.1); WEBGPU downloads its pinned wgpu-native release, whose macOS package CNA lists as unverified; FNA3D fetches FNA3D and MojoShader. The toolchain must be recent: CNA’s macOS CI uses Xcode 26 on the macos-26 runner, and Xcode 15.4 is too old (its library has no std::jthread). Like every CNA build you need the sharp-runtime sibling checkout beside cna/, on its next branch for this snapshot. Desktop networking needs a libcurl: macOS's own works for TLS but has no WebSocket support, so a build that found it refuses the online relay by name — install Homebrew's curl if you need online play.

What each renderer does on a Mac

Capabilities are answered per renderer, not per platform, so the capability matrix applies on macOS too. The differences that matter most for a Mac game:

Remember that XNA's default Reach profile still refuses HiDef features (MRT, occlusion queries, float targets) until you request HiDef. As Tutorial 101 explains, branch on capability answers and the renderer capability profile rather than on the renderer name.

Custom shaders on macOS

The default renderer is the one that cannot run a custom ShaderEffect on a Mac: SDL_GPU compiles that path out of Apple builds and reports CustomEffects false. If your game needs its own shaders on macOS, you have two routes:

• Pick a renderer that executes ShaderEffect source — OPENGL33 (desktop GLSL) or WEBGPU (WGSL) — and supply that dialect (Tutorial 151 shows how to ship one variant per dialect).
• Use compiled XNA effects: build with the renderer’s compiled-effects option (CNA_SDL_GPU_COMPILED_EFFECTS, CNA_EASYGL_COMPILED_EFFECTS, CNA_WEBGPU_COMPILED_EFFECTS, CNA_SOFTWARE_COMPILED_EFFECTS; all default OFF) or use FNA3D, where they are always on, and load your game’s own .fxb/XNB effects (Tutorial 128).

#include "CNA/GraphicsCapability.hpp"

using CNA::GraphicsCapability;

void MyGame::LoadContent()
{
    auto& device = getGraphicsDeviceProperty();

    // False on SDL_GPU in an Apple build: ShaderEffect is compiled out there.
    if (device.SupportsCapability(GraphicsCapability::CustomEffects))
        gradeEffect_ = std::make_unique<ShaderEffect>(device, kVertexGlsl, kFragmentGlsl);

    // Stock effects work on every renderer that draws.
    basicEffect_ = std::make_unique<BasicEffect>(device);
}

What macOS CI checks

Apple coverage lives in one automatically triggered workflow, apple-ci.yml, on GitHub's macos-26 runner (plus a Linux job that checks the Apple CMake layer). Its legs claim deliberately unequal things:

CI evidence here is compile, bundle and bounded smoke evidence. It does not observe on-screen presentation, frame pacing or pixel fidelity of a GPU renderer on a Mac.

What an earlier Mac mini M4 campaign recorded

Before this snapshot, CNA ran a qualification campaign on a physical Mac mini M4 (arm64, 16 GB, macOS 27.0.1, Xcode 27, Apple clang 21) on 7–8 October 2026, recorded task by task in plans/plan_apple_m4.md and summarised in docs/apple-platforms.md. Its full-tree runs for the renderers this snapshot still has, recorded by CNA and not re-run for this page:

Refusals, not silent degradation

Where a renderer cannot serve a request on a Mac, CNA’s rule is to fail by name rather than render something plausible-but-wrong: an OcclusionQuery constructor on SDL_GPU throws NotSupportedException, so does a partial BlendState.MultiSampleMask on a multisampled SDL_GPU target, and a texture format a renderer does not classify throws NotSupportedException. One exception is worth knowing: SOFTWARE accepts a custom ShaderEffect and silently draws with its fixed stock path.

What remains open

• SDL_GPU, the default, has not been re-qualified on Apple hardware, and its gating macOS smoke leg had no recorded run at this snapshot.
• ShaderEffect is compiled out of Apple SDL_GPU builds, and SDL_GPU has no occlusion queries.
• No Retina-resolution back buffer, no safe-area handling on iOS, and no app-icon, asset-catalog or .ipa packaging.
• No current Intel-macOS CI run; x86_64 and universal builds are configured but unverified.
• iOS: SDL_GPU has never been built for it; the evidence is a one-frame SOFTWARE simulator smoke run.

What you can build on today

A 2D or 3D XNA-style game builds and runs on an Apple-silicon Mac with any of the five renderers above; SOFTWARE is the one CI keeps green there, and the GPU renderers carry the earlier campaign’s record. Budget for the evidence gap rather than a feature gap: test your game on a real, unlocked Mac display (presentation and pacing were never observed by CNA), on the macOS versions you intend to ship to, and on Intel Macs if you target them.

Keeping a macOS build in a portable codebase

A macOS build is normally a single-renderer configuration like any other, and nothing in it is Apple-only, so the same source tree builds for Linux, Windows and the web. If you want a fallback on the Mac, compile several renderers into one binary (Tutorial 126) and let run-time selection fall back from SDL_GPU to OPENGL33 or SOFTWARE. Capability queries keep one source tree honest across the configurations:

// Resolve once at startup and cache the answers; do not query per frame.
struct RenderPathPlan
{
    bool deferred       = false;
    bool antialiased    = false;
    bool occlusionCull  = false;
};

RenderPathPlan PlanRenderPath(GraphicsDevice& device)
{
    RenderPathPlan plan;
    plan.deferred      = device.SupportsCapability(GraphicsCapability::MultipleRenderTargets);
    plan.antialiased   = device.SupportsCapability(GraphicsCapability::MultiSampleAntiAliasing);
    plan.occlusionCull = device.SupportsCapability(GraphicsCapability::OcclusionQuery);
    return plan;   // On SDL_GPU, occlusionCull is false on every platform.
}

Two habits pay off. Log device.GetGraphicsRendererName() at startup — it answers for the renderer the device actually resolved to, so a bug report from a Mac user tells you immediately which renderer produced it. And keep a CPU renderer (SOFTWARE) in your regression matrix as well, so image-level tests also run where no GPU is available.

Where to go next

• Tutorial 131: The SDL_GPU Renderer
• Tutorial 101: Querying Renderer Capabilities
• Tutorial 128: Compiled XNA Effects
• Tutorial 107: CPU-Only Renderers
• Tutorial 72: Choosing a Renderer
• Tutorial 80: Cross-Platform Build Guide
• Platforms reference, Renderers reference and Verification