Skip to content

Add a native Metal renderer for macOS - #92

Open
AlexMcArdle wants to merge 57 commits into
ofpisnotdead-com:mainfrom
McArdle-Systems:port/macos-metal-renderer
Open

AlexMcArdle wants to merge 57 commits into
ofpisnotdead-com:mainfrom
McArdle-Systems:port/macos-metal-renderer

Conversation

@AlexMcArdle

@AlexMcArdle AlexMcArdle commented Jul 6, 2026 •

Copy link
Copy Markdown

Why

CWR-CE now supports macOS, but its hardware renderer is OpenGL. Apple deprecated OpenGL in macOS 10.14 and recommends Metal for high-performance GPU work: Apple OpenGL Programming Guide.

This PR adds a native Metal renderer on top of the macOS support already present in this repository. Metal becomes the default renderer on Apple platforms, while --render gl33, --render dummy, and --render auto remain available.

What this adds

  • The complete PoseidonMTL backend, including SDL/CAMetalLayer integration and the hardware-T&L and legacy draw paths.
  • Native Metal rendering for meshes, UI/ImGui, textures and mip streaming, shadows, fog, lighting, sampler addressing, depth bias, safe-area updates, and framebuffer screenshots.
  • Water, detail, and grass rendering equivalent to the GL33 equations, including animated water texture generation, bump/specular lighting, and grass alpha coefficients.
  • Correct water-bump binding for the legacy terrain-water path, with a safe fallback when the bump texture is unavailable.
  • Cutout coverage and transparent-depth handling, including the low-light foliage correction.
  • Backend-neutral texture-validity, debug-overlay, and renderer integration hooks.
  • Apple metal-cpp pinned to the exact tested upstream release through a small Apple-only vcpkg overlay port.
  • The ImGui Metal backend sources required by the installed ImGui version.
  • A Metal smoke test and focused renderer contract tests.
  • Fix a silent audio fallback on macOS: the OpenAL loader only tried a bare library name, which never resolved against the bundled or a user-installed dylib, so audio silently fell back to a no-op backend with no error logged. Widened the probe to check the bundled dylib, then a user-installed OpenAL, then Apple's system framework.

Parity with the GL33 backend

A second batch brings the Metal backend to feature parity with EngineGL33, implementing every applicable Engine virtual the GL33 backend overrides:

  • Display/monitor/window-mode queries and switching, guard band, resizable windowed mode.

  • Graphics options that previously no-op'd on Metal: MSAA (with alpha-to-coverage for cutouts), render scale (SSAA), gamma, VSync — via an offscreen frame target and present pass.

  • Trident harness hooks: back-buffer sampling, test patterns, flat shading, debug error count, recorded draws for the frame validator; readbacks are pre-gamma to match GL33's capture path.

  • Stars/laser points, night-eye desaturation, queue-reorder/projection-update hooks, IsColored tints, and the ScreenSpace3D pass-kind hint for 3D UI overlays (binocular reticle, TV vignette).

  • Instanced runs and GPU land clip (heightmap in a vertex-stage texture), so Metal takes the same perf path as GL33.

  • Cascaded shadow maps (opt-in, as on GL33), with the depth probe matching the CPU oracle.

  • Local lights selected from a per-frame light table, matching GL33's UploadLocalLights design.

  • Textures are released in place on a mod remount and reload from the new mod set on next use (GL33's model); previously Metal kept the old set under the same names.

  • Blended sections discard at GL33's 1/255 alpha reference (the earlier 18/255 cut punched holes in faint glass reflections such as the A-10 canopy).

The tests/integration/rendering suite is failure-for-failure identical between --render mtl and --render gl33 locally. Note: on macOS, GL33's shadow-map lit pass currently draws no shadows because Apple's GL driver rejects the sampler2DArray depth array ("GLD_TEXTURE_INDEX_2D_ARRAY is unloadable"); Metal's works.

One shared-engine fix came out of this: the original gun textures (o\guns\handle_bmp.pac and friends) are AI88 data in .pac files, and both texture sources picked the level reader by file extension, so they failed to decode on every backend (Metal, decoding at load, logged it; GL33 only fails once the model is drawn). A header format marker now selects the PAA-style readers regardless of extension, with an LZSS-packed AI88 .pac fixture and decode test.

Scope

This is centered on the Metal renderer and includes the narrow macOS integration work needed to build and exercise it across the repository:

  • Link PoseidonMTL into the Apple Tetris application and unit-test targets.
  • Make the Trident process-lifecycle test portable to macOS, where /proc is unavailable.
  • Complete Metal text-input handling and propagate text-input intent through embedded controls used by the mission editor and profile dialogs.

The broader macOS toolchain, distribution, packaging, and CI support remain outside this PR and are already merged upstream. Two small exceptions, both macOS-specific and both easy to drop if you would rather they came separately:

  • a narrow OpenAL loader fix (see "What this adds"), pulled in here because it was needed to verify Metal's audio behavior during this work,
  • a one-line .gitignore entry for .DS_Store. Finder writes these into any directory it browses, so they turn up constantly while working on the macOS side; the repo does not ignore them yet.

Kept current with upstream

This branch tracks main. Synced again on 2026-09-10, pulling in 52 more upstream commits (instancing/perf work, mission-browsing improvements including a new "blocked mission" UI state, mod/download robustness, Linux hardening). No conflicts touched Metal code this time; three non-Metal conflicts came up and were resolved by keeping our fork's independent fixes where they were strict supersets of upstream's version of the same bug:

  • engine/Poseidon/Foundation/Common/Platform.cpp (fileCopy) — both sides independently fixed a missing open() mode argument; kept our version, which adds atomic copy-then-rename on top (upstream's doesn't) and matches QOFStream::close()'s save-file permission convention.
  • Its test — upstream's new test asserts a 0644 destination mode that doesn't hold against our fixed 0600; kept our existing coverage instead.
  • engine/Poseidon/UI/OptionsUIImpl.cpp — upstream's new blocked-mission-message UI merged in cleanly; kept our CreateSingleMissionBank(directory, true) call in the preview path (a real fix for a bank-name collision between packed missions on the same island) over upstream's default.

Earlier syncs required two small fixes, both still in place:

  • PoseidonMTL's vertex-buffer init still referenced VBSmallDiscardable, an enum value main removed when it collapsed the discardable vertex-buffer types into VBStatic. GL33 had already been updated to match; Metal hadn't. Fixed to mirror GL33's simplified check.
  • Test locality bug: FormatTime's test hardcoded an expected year against a localtime()-formatted timestamp, so it failed outside UTC. Pinned to UTC for the duration of the test, matching the equivalent fix already on main.

Verification

  • Configured macos-arm64-clang-rwdi on Apple Silicon.
  • Installed the pinned Metal-cpp package from Apple through the vcpkg overlay.
  • Built PoseidonGame, MetalSmokeTest, and PoseidonTests.
  • Ran MetalSmokeTest --check --frames 3.
  • Eagerly compiled every embedded hardware-T&L Metal pipeline during the smoke check.
  • Ran the focused Metal renderer contract tests.
  • Visually tested terrain detail, trees, grass, and animated bump-mapped water on Metal.
  • Full local build + ctest suite after the latest upstream sync (3994/3994 passing).

Screenshots

A-10 cockpit gauges and HUD

First-person view on the airfield next to a Cobra

Chain-link perimeter fence rendering cleanly at distance

Gunship cockpit HUD/reticle over a wrecked vehicle hull

Close-up on a destroyed vehicle hull

@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch 3 times, most recently from 7762960 to 09f53c9 Compare July 6, 2026 17:04
@Dahlgren

Dahlgren commented Jul 6, 2026 •

Copy link
Copy Markdown
Contributor
  • We also opened Dahlgren/CWR-CE#1 against the macos branch this PR originated from, with two of the same fixes (MemGrow, OpenAL fallback) — that's been open since July 2 with no response, which is part of why we're bringing the fuller fix here instead.

You didn't request review so no notification was sent

Happy to close the other PR if we rather go with these changes

@AlexMcArdle

AlexMcArdle commented Jul 6, 2026 •

Copy link
Copy Markdown
Author

I don't have a button to request a review on that PR @Dahlgren .

I can also fold in any extra changes after the other PR. What do @simi? Let's get macOS support in!

Edit: As a side note I also don't have a button to request a review on this PR so hopefully it is seen by a maintainer.

@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch 2 times, most recently from a191305 to 4f44ee7 Compare July 8, 2026 23:59
@AlexMcArdle

AlexMcArdle commented Jul 8, 2026 •

Copy link
Copy Markdown
Author

Superseded by the July 15 refresh: CloudSync was later removed from this branch because it did not provide reliable cross-device continuity. The current PR tree does not contain CloudSync.

The parts of this update that remain are the Metal legacy alpha-test fix and the macOS OpenAL dylib bundling/runtime discovery work. Thanks again to @Dahlgren for identifying the missing runtime artifact gap.

See the current refresh summary: #92 (comment)

@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch 2 times, most recently from 6177d12 to 492e1f0 Compare July 9, 2026 00:34
@AlexMcArdle

Copy link
Copy Markdown
Author

Is this wanted @simi ?
Should I break out the Metal changes for after the #19 PR lands? That PR is basically comparable with this branches macOS changes.

@simi

simi commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Is this wanted @simi ?

Sure @AlexMcArdle, just give me a time please. I'll start to consolidate PRs probably at the second part of next week finally. 🙏 I have some workload to finish first 😉.

@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch 2 times, most recently from 4df7bcc to fdc7e0d Compare July 16, 2026 04:54
@AlexMcArdle

Copy link
Copy Markdown
Author

Refreshed the three curated commits from the latest macOS/Metal work:

  • added Metal framebuffer screenshot capture (389d5c9 + formatting follow-up)
  • folded in the latest Metal alpha/cutout depth fix and its regression test (18049af)
  • rewrote all three commit messages and the PR description to remove stale CloudSync claims; CloudSync is not in the current tree
  • preserved the existing macOS build/OpenAL bundling work and the three-commit review structure

Current tip: fdc7e0d. Local Apple Silicon validation completed: configured the macOS arm64 preset; built PoseidonGame, both renderer smoke-test targets, and PoseidonTests; the focused Metal alpha/depth test passes all 29 assertions; clang-format 21 and git diff --check pass. GitHub Actions verification is now the remaining checkbox.

@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch 2 times, most recently from 78ca1b0 to 2b63927 Compare July 16, 2026 05:05
@AlexMcArdle

Copy link
Copy Markdown
Author

Small follow-up folded into the existing Metal/portability commit: macOS now defaults to mtl when --render is omitted. Explicit --render gl33, dummy, and auto choices remain available.

Added regression coverage for the platform default; the macOS build passes and appConfig: singleton defaults passes all 10 assertions. The PR remains exactly three commits. New tip: 2b63927.

@AlexMcArdle AlexMcArdle changed the title Native Metal renderer + full macOS/Apple Silicon support Add native Metal renderer and macOS Apple Silicon support Jul 23, 2026
@AlexMcArdle
AlexMcArdle force-pushed the port/macos-metal-renderer branch from ade09fc to ae25c57 Compare July 25, 2026 04:20
@AlexMcArdle AlexMcArdle changed the title Add native Metal renderer and macOS Apple Silicon support Add native Metal renderer Jul 25, 2026
@AlexMcArdle AlexMcArdle changed the title Add native Metal renderer Add a native Metal renderer for macOS Jul 25, 2026
@AlexMcArdle

AlexMcArdle commented Jul 25, 2026 •

Copy link
Copy Markdown
Author

Update: this PR has been rebuilt around current upstream

The original version of this PR combined macOS platform support with the Metal renderer. Since macOS support has now landed in this repository, I rebuilt the branch on the current upstream main and narrowed the PR to the renderer itself.

What changed:

  • Removed the now-redundant macOS toolchain, OpenAL runtime, distribution, packaging, and CI changes.
  • Retained the complete native Metal backend, with ImGui’s Metal backend vendored and Metal-cpp pinned through vcpkg.
  • Kept GL33 and the dummy renderer available; Metal is the Apple-platform default.
  • Completed the previously missing Metal water, terrain-detail, and grass paths using the GL33 rendering equations.
  • Fixed the legacy terrain-water route to bind the dedicated water bump map instead of interpreting the generic specular texture as normals, which had made water render bright white.
  • Expanded the Metal smoke and contract tests; the focused Metal suite now passes 44 assertions in 2 test cases.
  • Re-tested the result locally on macOS/Apple Silicon: trees, grass, terrain detail, and animated bump-mapped water render correctly.

In short: this is no longer a macOS port PR. It is a renderer-only PR that adds native Metal support to the macOS foundation already present upstream.

@Dahlgren

Copy link
Copy Markdown
Contributor

Did a very quick test

tests/unit/apps/Tetris/PoseidonTetrisTests fails to compile

Undefined symbols for architecture arm64:
  "Poseidon::RegisterMetalGraphicsBackend()", referenced from:
      GameApplication::RegisterGraphicsBackends() in GameApplication.cpp.o
ld: symbol(s) not found for architecture arm64

Texture issue

Some textures such as the asphalt road on nogova looks wrong

GL33

cwr-ce-gl33

MTL

cwr-ce-mtl

Tested on M3 Max

@simi

simi commented Jul 25, 2026

Copy link
Copy Markdown
Contributor

looks like wrong sampling

@AlexMcArdle

Copy link
Copy Markdown
Author

Thanks for noticing that @Dahlgren .
I'm still trying different things to see if I can figure out what's causing the blockiness. @simi yeah messing with the sampling I was able to produce an extremely smooth looking road, but still not close to the GL33 renderer.

Cutout edges are most of what MSAA smooths in this game, and Metal's
opaque pipeline hard-discarded them regardless of sample count, so the
MSAA option looked like a no-op next to GL33. Add an alpha-to-coverage
specialization of the opaque mesh pipeline that emits GL33's sharpened
coverage in alpha, selected for measured cutouts whenever MSAA is on.
Title-effect objects (cutObj, RscObject) and ControlObject draws are
screen-space 3D overlays, and the descriptor layer already has a
PassKindHint for that which nothing produced. Set it at both producers
so Metal's legacy path can keep every such overlay on GL33's blend path
instead of the measured-cutout alpha test, which was hard-cutting the
TV set's glass vignette the same way it cut the binocular reticle.

Also carry the scene constant colour per object into the TL shaders;
IsColored fades and tints rendered at texture alpha on Metal.
Implement the Engine instanced-run contract for the Metal backend: the
scene's runs of identical static shapes upload their camera-relative
world matrices and per-instance light indices to a per-frame stream
buffer, and every DrawSectionTL inside the run issues one instanced draw.
Lights for instances come from a frame light table built by
UploadLocalLights, selected by index in the vertex shader and scaled by
the night-adjusted material there, matching GL33. Legacy fan emission
inside a run marks it impure so the scene redraws the tail scalar.

Also count Metal draw calls for the perf overlay, which never ticked on
this backend.
Upload the terrain height grid as an R32 vertex-stage texture and port
GL33's land-clip snapping to vsMesh: ClipLandOn vertices pin to the
sampled surface, ClipLandKeep vertices keep their authored height above
the terrain at the object's bounding centre, and mode 2 rides the land
square's plane. Normals are bent by the surface gradient as before.
LandClipInVS() now reports true once a heightmap is loaded, so the scene
skips its CPU ApplyLandClip deform and land-clipped shapes join
instanced runs. VertexMeshMTL grows a land-clip class per vertex.
Port GL33's opt-in shadow-map path: the scene's caster set is copied into
the frame stream and rendered from each cascade's light view-projection
into a Depth32Float array at the end of the frame (solid casters keep
their back faces, alpha batches discard on texture alpha), and the lit
fragment shaders sample the previous frame's array with GL33's tiered
select, 3x3 PCF, cross-fade and far fade. The tuning set, sun factor,
depth probe and cascade-0 dump follow the Engine contract; the probe
matches the CPU oracle exactly (iou 1.000). Metal's top-down texture
rows are accounted for in the sampling UV and the readbacks.
Host the scalar lit path on UploadLocalLights like GL33: SetMaterial packs
the object's light indices instead of embedding up to eight pre-multiplied
lights per draw, and vsMesh reads the same frame table for scalar and
instanced draws. The table now lives in rotating persistent buffers, since
the terrain draws before the scene uploads the frame's lights and reads
the previous table, as GL33's UBO does.
A mod remount now drops every texture's GPU surfaces and pixel copy while
the objects and their Refs stay valid, and the next use reloads them from
the current VFS, the way GL33's ReleaseMemory path works; previously the
Metal bank kept the old mod's textures under their names because its bulk
release could only run with nothing alive. FlushBank forgets the unloaded
bank's textures so a later Load decodes the replacement, and textures now
free their surfaces through their bank when destroyed instead of holding
them until shutdown.
fsMeshBlend dropped texels below 18/255 alpha, a threshold chosen when
AI88 textures were expanded through ARGB4444; the decoder has kept their
8-bit alpha since, and the higher cut punched a hole in the A-10 canopy
glass where its reflection texture dips below it, visible as a pale
blotch GL33 does not show. Use GL33's 1/255 reference instead.
The legacy measured-cutout guard gained the ScreenSpace3D exclusion and
DrawSectionTL uploads the per-draw copy of the object constants; the
source-matching test still looked for the old spellings.
The original gun textures (o\guns\handle_bmp.pac and friends) are AI88
data in .pac files. Both texture sources chose the level reader by file
extension, and the .pac reader has no case for the 16-bit formats, so
those textures failed to decode; Metal, which decodes on load, logged it
while GL33 stayed quiet unless the model was drawn. Treat a format marker
as PAA-style level data regardless of extension. Adds an LZSS-packed AI88
.pac fixture and a decode test that fails without the fix.
@AlexMcArdle

Copy link
Copy Markdown
Author

Parity achieved. And an FPS boost to boot. Please give it a look when you can!

@simi

simi commented Sep 12, 2026

Copy link
Copy Markdown
Contributor

Parity achieved. And an FPS boost to boot. Please give it a look when you can!

Good news. I don't have access to Mac currently, but that will probably change soon. Meanwhile I would like to finish porting perf updates from #126. Once done, we can start on adding more renderers. I have on side also Android (OpenGL ES) one also. 🙏 Thanks a lot for your work and patience.

@AlexMcArdle

Copy link
Copy Markdown
Author

Got it. I'll be waiting paitently for #126 . Please let me know if there's anything that will help speed things up!

@AlexMcArdle

Copy link
Copy Markdown
Author

What about now @simi ?

@simi

simi commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

I can finally test on my own, so I'll start with that. 🙏

The instanced ground pass is only implemented by GL33, so the landscape now
asks the backend before taking it and otherwise keeps the mesh-based ground
and water. Metal uploads its local light table itself, once per frame on the
first draw that packs light indices, now that the scene no longer calls
UploadLocalLights. The vendored ImGui Metal backend builds without ARC, where
its bridge casts are no-ops that warn.
Port the instanced ground pass to the Metal backend: one grid mesh per
segment displaced from the height map in the vertex stage, surface textures
in one array per size class, per-segment light sets read from a frame
buffer, and water drawn flat at sea level through the same instances.

The frame half of PrepareMeshTL moves into UpdateFrameConstants so the
ground can build its constants without a mesh draw before it. A map whose
setup fails falls back to the mesh-based ground.
@AlexMcArdle

Copy link
Copy Markdown
Author

Refreshed against current main (through #328), and the instanced terrain and water renderer is now ported to Metal.

Catching up with main (93b64c4)

  • Instanced terrain gate: the landscape now asks the backend whether it implements the instanced ground pass (Engine::DrawsInstancedGround()). This is the only change outside engine/PoseidonMTL: three lines in Engine.hpp, LandscapeRender.cpp and EngineGL33.hpp. GL33 behaviour is unchanged.
  • Local lights: UploadLocalLights is no longer a virtual called by the scene, so Metal uploads its light table itself once per frame.
  • Warnings as errors: the vendored ImGui Metal backend needed one warning suppressed.

Instanced terrain and water on Metal (fd1b6f1, 6c29ff8)

Metal now takes the same instanced ground path as GL33: one grid mesh per segment displaced from the height map in the vertex stage, surface textures in one array per size class, per-segment light sets, and water drawn through the same instances. It is contained in engine/PoseidonMTL. A map whose setup fails falls back to the mesh-based ground.

Verified locally on Apple Silicon

  • Clean build with warnings as errors, 4003/4003 unit tests.
  • tests/integration/rendering gives the same result under --render mtl and --render gl33: 7 pass, and the same 3 fail on both (aspect_load_gameplay_active, aspect_overlays_demo, fullscreen_toggle).
  • Single-frame captures compared against GL33 on Abel, Cain and Eden: ground, coast, open sea, and a night scene with a lit fire. Ground and coast match closely. Open-sea water is a few percent darker on Metal in one capture, which I have not tracked down yet.
  • The terrain texture arrays take 15 to 32 MB depending on the island.

Not covered yet

  • Maps that need more than one texture array (all three islands fit in one).
  • Shadow maps and MSAA together with the instanced ground.
  • I have no Metal frame-time numbers for the instanced path yet.

To try it on a Mac

cmake --preset macos-arm64-clang-rwdi
cmake --build build/macos-arm64-clang-rwdi --target PoseidonGame -j 8
build/macos-arm64-clang-rwdi/apps/cwr/Game/PoseidonGame -C <game data dir> --render mtl

Swap in --render gl33 for a side-by-side. The workflows on this PR are waiting for approval to run, @simi.

@AlexMcArdle

Copy link
Copy Markdown
Author

Follow-up on the "not covered yet" list above. No code changes; these are local runs on Apple Silicon at 6c29ff8.

  • Several texture arrays: all three islands fit in one array, so I forced the split by capping layers per array. Abel in 5 arrays renders the same as in 1 (static scene, largest per-pixel difference 1/255), and Cain in 10 arrays shows no visible difference.
  • MSAA: 4x on the instanced ground renders correctly, with no command buffer errors.
  • Shadow maps: with shadow maps enabled a vehicle's shadow falls on the instanced ground as expected, with and without 4x MSAA.
  • Timing: one scene (Demo data, 5 km view distance, vsync off, on battery), instanced ground against the mesh-based ground on Metal, two runs each:
ground CPU per frame draw calls per frame draw phase per frame
mesh-based 0.94 to 0.96 ms 2627 4.6 to 4.8 ms
instanced 0.13 to 0.14 ms 1315 4.0 to 4.1 ms

Whole-frame time did not move measurably in this scene (80 to 89 fps across the four runs); most of the frame there is spent waiting on present.

Still open: open-sea water is about 3.5% darker on Metal than on GL33. It is repeatable, so it is a real difference and not capture noise, and I have not found the cause.

The ground lighting helper took its output by unqualified reference, which
only the newest Metal shading language accepts. Builds with an older
deployment target failed to compile the whole mesh shader library. It now
returns the vertex it lights.
@AlexMcArdle

Copy link
Copy Markdown
Author

One fix since the comments above (394cacc): the new ground shader took an output by unqualified reference, which only the newest Metal shading language accepts, so a build with an older deployment target (macOS 14 in my case) failed to compile the mesh shader library. It now compiles under language versions 2.4, 3.0, 3.1 and 3.2. The checks above were all run under the newest version only.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants