From d4a83e75bbe69425f8d1e7b4fa46aed78f373260 Mon Sep 17 00:00:00 2001 From: BlackMark Date: Mon, 22 Jun 2026 12:19:16 +0200 Subject: [PATCH] Roadmap: Vulkan mock done; capture remaining (read-back approach + test caveat) Reflect that the Vulkan mock backend + submodules are done, and scope the remaining Vulkan capture honestly: hook vkGetInstance/DeviceProcAddr + intercept device/swapchain creation, and read the presented image back with vkCmdCopyImageToBuffer (the same read-back pattern as D3D10/D3D9/OpenGL -- simpler/robuster than a VK_KHR_external_memory keyed-mutex blit). Note testing needs the early-load path (late-inject can't catch a Vulkan present), and Vulkan games mirror via WGC meanwhile. Co-Authored-By: Claude Opus 4.8 --- README.md | 70 +++++++++++++++++++++++++++---------------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 42fd341..d520c5b 100644 --- a/README.md +++ b/README.md @@ -147,41 +147,41 @@ Conventions for every milestone below: nothing clipped/overlapping, colours/labels correct. A green unit test is not a substitute for looking at the product; this real-screenshot check is required, not optional. -- **M2 — Vulkan (mock → capture).** The largest. - 1. **Mock backend** (`render_vk.cpp`). New submodules **Vulkan-Headers** - (`KhronosGroup/Vulkan-Headers`, official) + **volk** (`zeux/volk`); raw - `vkCreateWin32SurfaceKHR`, swap chain, per-frame acquire → clear → present. Background via - `vkCmdClearColorImage`, bar + block via `vkCmdClearAttachments` clear-rects (no - pipeline/shaders → **no SPIR-V toolchain**). Loads Vulkan via **volk** on purpose — that's - the loader-bypass case the capture hook must handle. Validation layers used when a Vulkan - SDK is present, skipped otherwise. - 2. **Capture.** Hook `vkQueuePresentKHR`; import a D3D11 keyed-mutex shared texture into Vulkan - (`VK_KHR_external_memory_win32` + `VK_KHR_win32_keyed_mutex`) and `vkCmdBlitImage` the - swap-chain image into it each present; the host samples it as usual. Because Vulkan caches - its present pointer at init, the hook **cannot be placed by late injection** — it must be - present before `vkCreateInstance`: - - **Attach via auto-attach — best-effort by default, opt-in layer for reliability.** By - default, arming Auto-attach for a detected Vulkan game injects as early as possible on - relaunch (the existing poll-and-inject) — enough for games that initialize Vulkan a little - into startup. For games that init Vulkan immediately, an **opt-in** Injection-panel - checkbox ("Set up Vulkan layer") registers a per-user (HKCU, no admin) implicit Vulkan - layer (thin `coop_vk_layer.dll` + JSON manifest) scoped to that game's image name; on - relaunch the loader loads it at `vkCreateInstance` — guaranteed before init — and it wires - up present capture + IPC. The layer is removed when the option is unticked or the host - exits, and self-deactivates for any non-target app, so a stale registration (e.g. after a - host crash) is harmless. - - **Too-late detection + red prompt.** A late-injected hook that finds `vulkan-1.dll` loaded - but no working hooked-present reports a *"Vulkan, injected too late"* status; the host - overlays a **red** banner on the mirror window: "Detected a Vulkan game — the hook attached - too late to mirror it with low latency. Enable Auto-attach (and, if it persists, 'Set up - Vulkan layer') and relaunch the game." **WGC keeps mirroring meanwhile** so the session - stays usable; the banner clears once the hooked path goes live. (New end-user UI → keep - M1's fit test green.) - - Sub-steps (separate commits): present-hook placement (best-effort inject + the implicit - layer), external-memory image import + keyed-mutex sync, the too-late status code, the - host red-banner UI, and the Auto-attach / Vulkan-layer Injection-panel controls. Test the - early (layer) path against the mock (decode frames) and the too-late path (assert the - status + banner fire). +- **M2 — Vulkan capture.** The Vulkan **mock backend is done** (`render_vk.cpp`, selectable `vk`): + volk + Vulkan-Headers submodules, a real instance / device / swap chain, and a per-frame + `vkCmdClearColorImage` of the frame-counter colour (no pipeline/shaders → **no SPIR-V + toolchain**); it loads Vulkan via **volk** on purpose (the loader-bypass case the capture hook + must handle). `mock_game_test` runs a **liveness** check on it — its present pointer is cached + at init, so late injection can't hook it, which is exactly why the capture below is the hard + part. The remaining **capture hook** (Vulkan games mirror via **WGC** meanwhile — the default): + 1. **Present interception (needs early presence).** Hook `vkGetInstanceProcAddr` / + `vkGetDeviceProcAddr` (the `vulkan-1.dll` exports) so a volk-using app resolves *our* + wrappers, and intercept `vkCreateDevice` / `vkCreateSwapchainKHR` to capture the + device/queue/images/format. Read the presented image back with `vkCmdCopyImageToBuffer` into + a host-visible buffer (the same read-back pattern as D3D10/D3D9/OpenGL — simpler and more + robust than a `VK_KHR_external_memory_win32` + keyed-mutex blit), swizzle if BGRA, and upload + via the hook-owned D3D11 device. **Testing needs the early-load path** (the mock loads the + hook before `vkCreateInstance`, e.g. via an env-var or the layer); the normal late-inject + `mock_game_test` flow can't catch a Vulkan present. + 2. **Attach via auto-attach — best-effort by default, opt-in layer for reliability.** By + default, arming Auto-attach for a detected Vulkan game injects as early as possible on + relaunch (the existing poll-and-inject) — enough for games that initialize Vulkan a little + into startup. For games that init Vulkan immediately, an **opt-in** Injection-panel checkbox + ("Set up Vulkan layer") registers a per-user (HKCU, no admin) implicit Vulkan layer (thin + `coop_vk_layer.dll` + JSON manifest) scoped to that game's image name; on relaunch the loader + loads it at `vkCreateInstance` — guaranteed before init — and it wires up present capture + + IPC. The layer is removed when the option is unticked or the host exits, and self-deactivates + for any non-target app, so a stale registration (e.g. after a host crash) is harmless. + 3. **Too-late detection + red banner.** A late-injected hook that finds `vulkan-1.dll` loaded + but no working hooked-present reports a *"Vulkan, injected too late"* status; the host + overlays a **red** banner on the mirror window: "Detected a Vulkan game — the hook attached + too late to mirror it with low latency. Enable Auto-attach (and, if it persists, 'Set up + Vulkan layer') and relaunch the game." **WGC keeps mirroring meanwhile** so the session stays + usable; the banner clears once the hooked path goes live. This is new end-user UI, so it must + keep M1's fit test (and the visual inspection) green. + + Each of 1–3 is its own commit; test the early/layer path against the mock (decode frames) and + the too-late path (assert the status + banner fire). ### Future work