examples/10-graphics: the offscreen example runs on all three platforms

macOS and Windows built it and did not run it, which is the shape the
cross-platform work exists to remove: the half of a lane written for a host is
the half that host never exercises. A build asserts that the shader compiler
this platform publishes works and that the Vulkan half links. It cannot assert
that the loader hands the program a device, and on macOS that is the
interesting half.

The example now declares a device for those two platforms as well --
`xim:moltenvk` under `cfg(macos)`, `xim:mesa-lavapipe` under `cfg(windows)` --
rather than leaving CI to install one. The omission was invisible while the
example was never run, because a program that does not run never asks the
loader for a device, and declaring it here is what makes the example complete
for anyone who checks it out rather than only for the runner that had an extra
command.

The two CI steps therefore install nothing. They locate the ICD the build
already provisioned and set `VK_DRIVER_FILES`, so a manifest that failed to
name the driver fails the step. An `xlings install` in the step would have made
it pass either way.

macOS and Windows assert different things, and the difference is the point.
lavapipe is a software rasteriser producing the same pixels by construction, so
the image cannot distinguish it and the device name is what does. MoltenVK is
the host's own GPU through Metal, so its name differs by runner; what
distinguishes reaching a device there is that a centre pixel was reported at
all, which a portability driver the loader declined to show would not produce.

This closes the dependency between the two halves of the portability change:
the package without the enumeration finds no device, and the enumeration
without the package has nothing to find.

Author: speak-agent

.github/workflows/ci-macos.yml

@@ -361,6 +361,54 @@ jobs:
           done
           echo "ok: both shader stages compiled and the Vulkan half linked"
 
+      # AND NOW IT RUNS, WHICH IS A DIFFERENT CLAIM FROM THE ONE ABOVE.
+      #
+      # A build asserts that the shader compiler this platform publishes works
+      # and that the Vulkan half links. It cannot assert that the loader hands
+      # this program a device, and on macOS that is the interesting half:
+      # MoltenVK is a PORTABILITY driver, which the loader does not give to
+      # `vkEnumeratePhysicalDevices` unless the instance asked for portability
+      # enumeration. A program written against native drivers therefore finds no
+      # device here and reports it as "this machine has no GPU".
+      #
+      # This step is what turns that into a red build rather than a plausible
+      # message. It depends on the portability enumeration in this PR: without
+      # it the run reaches zero devices even though everything installed
+      # correctly.
+      #
+      # `VK_DRIVER_FILES` rather than an ICD search directory: the package is in
+      # the xlings store, not in `/usr/local/share/vulkan/icd.d`, and naming the
+      # file is the one form that does not depend on where the loader looks.
+      - name: "Graphics: the offscreen example RUNS on MoltenVK"
+        shell: bash
+        run: |
+          set -e
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          # NOT installed from here. The example declares `xim:moltenvk` under
+          # `cfg(macos)`, so the build above already provisioned it, and looking
+          # for the ICD without installing anything is what asserts that the
+          # declaration works. An `xlings install` here would make this step
+          # pass whether the manifest named the driver or not.
+          icd=$(find "${MCPP_HOME:-$HOME/.mcpp}/registry/data/xpkgs/xim-x-moltenvk" \
+                     "$HOME/.xlings/data/xpkgs/xim-x-moltenvk" \
+                     -name 'MoltenVK_icd.json' -print -quit 2>/dev/null || true)
+          [ -n "$icd" ] || { echo "no MoltenVK ICD in either store"; exit 1; }
+          echo "ICD: $icd"
+          cd "$GITHUB_WORKSPACE/examples/10-graphics/offscreen"
+          out=$(VK_DRIVER_FILES="$icd" "/tmp/mcpp-fresh" run 2>&1) || { echo "$out"; exit 1; }
+          echo "$out"
+          # The program asserts the corners and the centre itself and exits
+          # non-zero on either. What CI adds is that the run reached a DEVICE:
+          # a portability driver that the loader declined to show would leave
+          # the program reporting no device, which is the failure this step
+          # exists for. The name is not compared to a fixed string because it is
+          # the host's GPU and differs by runner; that it is non-empty and the
+          # centre pixel is opaque is what distinguishes reaching a device from
+          # not.
+          echo "$out" | grep -qE 'centre pixel: \([0-9]+, [0-9]+, [0-9]+, 255\)' \
+            || { echo "no centre pixel was reported: the run reached no device"; exit 1; }
+          echo "ok: MoltenVK enumerated and the image was rendered on it"
+
       # Integration: the mcpp built from THIS PR's source (the self-host binary,
       # $MCPP = /tmp/mcpp-fresh) builds & runs a real external C++ project —
       # xlings (openxlings/xlings ships its own mcpp.toml).

.github/workflows/ci-windows.yml

@@ -456,6 +456,45 @@ jobs:
           done
           echo "ok: both shader stages compiled and the Vulkan half linked"
 
+      # AND NOW IT RUNS. `xim:mesa-lavapipe` publishes a Windows build, so this
+      # host has a software device and the claim can be the same one Linux
+      # makes: the program reached a device and rendered the image, not merely
+      # that it compiled.
+      #
+      # The device name IS compared here, unlike on macOS. lavapipe is a
+      # software rasteriser that produces the same pixels by construction, so
+      # the image cannot distinguish it from any other implementation and the
+      # name is what does.
+      #
+      # `VK_DRIVER_FILES` rather than an ICD search directory: the package is in
+      # the xlings store rather than in the registry the Windows loader reads,
+      # and naming the file is the one form that does not depend on that.
+      - name: "Graphics: the offscreen example RUNS on lavapipe"
+        shell: bash
+        run: |
+          set -e
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          # NOT installed from here, for the reason the macOS job records: the
+          # example declares `xim:mesa-lavapipe` under `cfg(windows)`, so
+          # finding the ICD without installing anything is what asserts the
+          # declaration works.
+          icd=$(find "${MCPP_HOME:-$HOME/.mcpp}/registry/data/xpkgs/xim-x-mesa-lavapipe" \
+                     "$HOME/.xlings/data/xpkgs/xim-x-mesa-lavapipe" \
+                     -name '*.json' -path '*icd.d*' -print -quit 2>/dev/null || true)
+          [ -n "$icd" ] || { echo "no lavapipe ICD in either store"; exit 1; }
+          echo "ICD: $icd"
+          cd "$GITHUB_WORKSPACE/examples/10-graphics/offscreen"
+          # `$MCPP_SELF`, which is what the build step above used. `/tmp/mcpp-fresh.exe`
+          # is a copy a LATER step makes, so naming it here would look right and
+          # fail with a missing file.
+          out=$(VK_DRIVER_FILES="$icd" "$MCPP_SELF" run 2>&1) || { echo "$out"; exit 1; }
+          echo "$out"
+          echo "$out" | grep -q 'llvmpipe' \
+            || { echo "the run did not reach the lavapipe device"; exit 1; }
+          echo "$out" | grep -qE 'centre pixel: \([0-9]+, [0-9]+, [0-9]+, 255\)' \
+            || { echo "no centre pixel was reported"; exit 1; }
+          echo "ok: lavapipe enumerated and the image was rendered on it"
+
       - name: "Toolchain: LLVM — build mcpp (self-host)"
         shell: bash
         run: |

examples/10-graphics/offscreen/mcpp.toml

@@ -44,6 +44,29 @@ vulkan-runtime = "2026.09.07"
 [target.'cfg(linux)'.xlings.workspace]
 "xim:mesa-lavapipe" = "26.2.1"
 
+# THE OTHER TWO PLATFORMS GET A DEVICE TOO, AND FOR THE SAME REASON.
+#
+# These were absent while the example was built but not run on macOS and
+# Windows, which made the omission invisible: a program that never runs never
+# asks the loader for a device. Declaring the driver here rather than installing
+# it from a CI step is what makes the EXAMPLE complete -- anyone who checks it
+# out gets a machine that can run it, not only the runner that had an extra
+# command.
+#
+# macOS has no native Vulkan. MoltenVK is an implementation on top of Metal, and
+# the specification calls that a portability driver: the loader does not hand it
+# to `vkEnumeratePhysicalDevices` unless the instance asked for portability
+# enumeration, which `src/vulkan/render.cpp` now does. The two halves are one
+# change -- the package without the enumeration finds no device, and the
+# enumeration without the package has nothing to find.
+[target.'cfg(macos)'.xlings.workspace]
+"xim:moltenvk" = "1.4.2"
+
+# Windows takes the same software rasteriser Linux does; upstream publishes a
+# separate build of it, one minor behind the Linux one.
+[target.'cfg(windows)'.xlings.workspace]
+"xim:mesa-lavapipe" = "26.2.0"
+
 [build]
 accel = "vulkan1.2"
 sources = [