examples/10-graphics: 可移植性驱动默认是看不见的

四期(软件设备把 CI 上限抬到运行)的程序侧那一半。

接设备之前先测了上游产物,而第一行的读数就是本条的理由:Khronos 官方的
`MoltenVK-macos.tar` v1.4.2 里,ICD 带着 **`"is_portability_driver": true`**。
**loader 默认不把可移植性驱动交给 `vkEnumeratePhysicalDevices`** —— 一个照着原生
驱动写的 Vulkan 程序因此在 macOS 上一个设备都找不到,并把它报成「这台机器没有
GPU」。诊断是错的,而它看起来完全合理。

规范要的是成对的两半:实例要**启用** `VK_KHR_portability_enumeration` **并且**置位
`VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR`;随后凡是声明了
`VK_KHR_portability_subset` 的设备,必须在 `vkCreateDevice` 时启用它,否则调用失败。

按**能力**问,不按 `#ifdef __APPLE__`:性质是「我面前这个 loader 在展示可移植性
驱动」,而 `#ifdef` 两个方向都会错 —— Linux 上跑翻译层的机器也有它,macOS 上对着
原生驱动构建的程序并不需要它。

实测:Linux/lavapipe 上读数不变,中心像素仍是 `(124, 70, 62, 255)`。

顺带记下 Windows 那一侧的测量:`mesa3d-26.2.0-release-msvc` 的 `vulkan_lvp.dll`
**只导入系统 DLL**(无 MSVCP140/VCRUNTIME140),静态 CRT,机器上不需要装任何东西。

载荷侧(把 MoltenVK 与 Windows 的 lavapipe 收进索引)未做:那要往发布组织推新的二进制
资产,而 GitCode 的资产不可替换不可删除。

Author: speak-agent

.agents/docs/2026-09-07-heterogeneous-cross-platform-ecosystem.md

@@ -332,7 +332,11 @@ install/config 形状,而那套形状是按 Linux 写的:
 - **二期(shaderc 三平台)**:xim-pkgindex #778,规则按平台选编译器。已实现。
 - **三期(CUDA/SYCL 上 Windows)**:xim-pkgindex #779(五个包),规则侧的路径推导与
   路线判断。已实现;端到端由 `windows-test` job 装卸五个包并断言注册的程序验证。
-- **四期(软件设备把 CI 上限抬到运行)**:**未实现,记录为发布工作**。Windows 上需要
+- **四期(软件设备把 CI 上限抬到运行)**:**部分实现**。程序侧那一半做完了:一个
+  Vulkan 程序在 macOS 上**看不见任何设备**,除非它显式打开可移植性枚举 —— MoltenVK 是
+  portability driver,而 loader 默认不把这种驱动交给 `vkEnumeratePhysicalDevices`。
+  示例现在按**能力**而不是按 `#ifdef __APPLE__` 问这件事(见 10.4e)。载荷侧仍未做,
+  记录为发布工作。Windows 上需要
   一个 Mesa-on-Windows 的 `vulkan_lvp` 构建;macOS 上 runner 自带 GPU 与 MoltenVK,
   所以那一侧不需要软件设备,需要的是把 `compat.vulkan` 的 macOS 腿接到示例上。
   今天的上限:三平台**构建**,Linux **运行**。
@@ -396,6 +400,31 @@ include 它。**
 同一版还给「每条规则都为本宿主编译过」那个夹具补了它自己的分母:它断言的是「每一条」,
 而「每一条」是它 carry 的一张清单。
 
+### 10.4e 四期的程序侧:可移植性驱动默认是看不见的
+
+把软件/可移植设备接到 CI 上之前,先测了上游产物:
+
+| 产物 | 读数 |
+|---|---|
+| `MoltenVK-macos.tar` v1.4.2(Khronos 官方) | 92 个条目;`dynamic/dylib/macOS/libMoltenVK.dylib` 是 x86_64+arm64 的 universal binary(11 MB),ICD 用相对路径 `./libMoltenVK.dylib`,并带 **`"is_portability_driver": true`** |
+| `mesa3d-26.2.0-release-msvc.7z`(pal1000 重分发) | `x64/vulkan_lvp.dll` 56 MB + `x64/lvp_icd.x86_64.json`;**只导入系统 DLL**(KERNEL32/GDI32/USER32/ADVAPI32/ole32/SHELL32/ntdll),没有 MSVCP140 —— 静态 CRT,机器上不需要装任何东西 |
+
+第一行那个 `is_portability_driver` 是本节存在的理由:**loader 默认不把可移植性驱动交给
+`vkEnumeratePhysicalDevices`**。一个照着原生驱动写的程序因此在 macOS 上一个设备都找不到,
+并把它报成「这台机器没有 GPU」—— 诊断是错的,而它看起来完全合理。
+
+规范要求的是成对的两半:实例要**启用** `VK_KHR_portability_enumeration` **并且**置位
+`VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR`;随后凡是声明了
+`VK_KHR_portability_subset` 的设备,必须在 `vkCreateDevice` 时启用它,否则调用失败。
+
+示例按**能力**问这两件事,不按 `#ifdef __APPLE__`。性质是「我面前这个 loader 在展示
+可移植性驱动」,而 `#ifdef` 两个方向都会错:Linux 上跑翻译层的机器也有它,而 macOS 上
+对着原生驱动构建的程序并不需要它。实测:Linux/lavapipe 上读数不变,中心像素仍是
+`(124, 70, 62, 255)`。
+
+载荷侧(把 MoltenVK 与 Windows 的 lavapipe 收进索引)未做,因为那要往发布组织推新的
+二进制资产,而 GitCode 的资产不可替换不可删除 —— 这是一个该由人做的决定,不该顺手做掉。
+
 ### 10.5 一条留下的不一致,以及它什么时候消失
 
 `mcpp:plugins` 0.2.5/0.2.6 里 `xim:shaderc` 在 macOS 与 Windows 上是**精确版本**,而

examples/10-graphics/README.md

@@ -80,6 +80,23 @@ dropped while the source that includes it, selected by the same predicate, was
 kept. Packages are therefore unconditional or conditioned on the platform;
 `[build]` sources are what the accelerator selects.
 
+**A portability driver is hidden until the program asks for it.** macOS has no
+native Vulkan: MoltenVK implements it on top of Metal, and the specification
+calls such an implementation a *portability driver*. The loader does not show
+one to `vkEnumeratePhysicalDevices` unless the instance enables
+`VK_KHR_portability_enumeration` and sets
+`VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR`; a device that advertises
+`VK_KHR_portability_subset` must then have that extension enabled at
+`vkCreateDevice` or the call fails. A program written against a native driver
+alone therefore finds no device on such a machine and reports it as "no GPU
+here", which is the wrong diagnosis.
+
+`src/vulkan/render.cpp` asks the loader and the device what they advertise
+rather than testing for the platform. The property is "the loader in front of
+me is showing portability drivers", and an `#ifdef __APPLE__` would be wrong in
+both directions: a Linux machine running a translation layer has it, and a
+macOS build against a native driver does not need it.
+
 **One shader per stem.** The generated name is the shader's stem and its stage,
 so `ui/text.vert` and `world/text.vert` would both produce `text_vert.h`
 declaring `text_vert_spv`. The rule refuses that and names both files. The

examples/10-graphics/offscreen/src/vulkan/render.cpp

@@ -33,6 +33,43 @@ const char* g_ran_on = "";
 
 constexpr unsigned char kClear[4] = { 16, 16, 16, 255 };
 
+// WHETHER AN EXTENSION IS THERE, ASKED RATHER THAN ASSUMED.
+//
+// The two below decide whether this program can see a PORTABILITY driver -- an
+// implementation of Vulkan on top of something else, which is the only kind
+// macOS has, because Apple's platform interface is Metal and MoltenVK
+// translates. A portability driver is HIDDEN from `vkEnumeratePhysicalDevices`
+// unless the instance opts in, so a program written against a native driver
+// alone finds no device there and reports it as "this machine has no GPU".
+//
+// Written as a capability query rather than `#ifdef __APPLE__`: the property is
+// "the loader in front of me advertises this", and a Linux machine running a
+// portability layer would have it too. The `#ifdef` would also be wrong in the
+// other direction -- a macOS build against a native driver does not need it.
+bool instance_extension_present(const char* name) {
+    std::uint32_t n = 0;
+    if (vkEnumerateInstanceExtensionProperties(nullptr, &n, nullptr) != VK_SUCCESS || n == 0)
+        return false;
+    std::vector<VkExtensionProperties> props(n);
+    if (vkEnumerateInstanceExtensionProperties(nullptr, &n, props.data()) != VK_SUCCESS)
+        return false;
+    for (auto const& p : props)
+        if (std::strcmp(p.extensionName, name) == 0) return true;
+    return false;
+}
+
+bool device_extension_present(VkPhysicalDevice phys, const char* name) {
+    std::uint32_t n = 0;
+    if (vkEnumerateDeviceExtensionProperties(phys, nullptr, &n, nullptr) != VK_SUCCESS || n == 0)
+        return false;
+    std::vector<VkExtensionProperties> props(n);
+    if (vkEnumerateDeviceExtensionProperties(phys, nullptr, &n, props.data()) != VK_SUCCESS)
+        return false;
+    for (auto const& p : props)
+        if (std::strcmp(p.extensionName, name) == 0) return true;
+    return false;
+}
+
 int find_memory_type(VkPhysicalDevice phys, std::uint32_t bits,
                      VkMemoryPropertyFlags want) {
     VkPhysicalDeviceMemoryProperties props{};
@@ -129,6 +166,18 @@ extern "C" int render_offscreen(unsigned w, unsigned h, unsigned char* rgba) {
     app.apiVersion       = VK_API_VERSION_1_2;
     VkInstanceCreateInfo ici{ VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO };
     ici.pApplicationInfo = &app;
+
+    // The opt-in, when the loader has it. Both halves are required and the
+    // pair is what the specification asks for: the extension has to be
+    // ENABLED, and the flag has to be set, before a portability driver appears
+    // in `vkEnumeratePhysicalDevices`.
+    std::vector<const char*> instanceExts;
+    if (instance_extension_present(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME)) {
+        instanceExts.push_back(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME);
+        ici.flags |= VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR;
+    }
+    ici.enabledExtensionCount   = static_cast<std::uint32_t>(instanceExts.size());
+    ici.ppEnabledExtensionNames = instanceExts.empty() ? nullptr : instanceExts.data();
     if (vkCreateInstance(&ici, nullptr, &f.instance) != VK_SUCCESS) return 1;
 
     VkPhysicalDevice phys = VK_NULL_HANDLE;
@@ -143,6 +192,16 @@ extern "C" int render_offscreen(unsigned w, unsigned h, unsigned char* rgba) {
     VkDeviceCreateInfo dci{ VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO };
     dci.queueCreateInfoCount = 1;
     dci.pQueueCreateInfos    = &qci;
+
+    // AND THE OTHER HALF: a device that advertises `VK_KHR_portability_subset`
+    // must have it enabled, or `vkCreateDevice` fails. The specification makes
+    // this one mandatory rather than optional precisely so that a program
+    // cannot use such a device while believing it is a complete one.
+    std::vector<const char*> deviceExts;
+    if (device_extension_present(phys, "VK_KHR_portability_subset"))
+        deviceExts.push_back("VK_KHR_portability_subset");
+    dci.enabledExtensionCount   = static_cast<std::uint32_t>(deviceExts.size());
+    dci.ppEnabledExtensionNames = deviceExts.empty() ? nullptr : deviceExts.data();
     if (vkCreateDevice(phys, &dci, nullptr, &f.device) != VK_SUCCESS) return 1;
 
     VkQueue queue = VK_NULL_HANDLE;