perf(pipeline): shared, disk-persisted VkPipelineCache (#69)

vkCreateComputePipelines and vkCreateRayTracingPipelinesKHR were passed
VK_NULL_HANDLE, so the driver couldn't reuse compiled shader binaries
across the pipelines built at startup (4 UI shaders + user/RT pipelines)
or across runs.

Add one process-wide Device::pipelineCache. LoadPipelineCache (called
from Initialize) seeds it from pipeline_cache.bin when the file's
VkPipelineCacheHeaderVersionOne header matches this device's
vendorID / deviceID / pipelineCacheUUID; a stale or foreign blob is
discarded so the driver never rejects it. SavePipelineCache is registered
with std::atexit, serialising the cache at process shutdown without any
explicit teardown hook. Both create sites now pass the cache; a null
handle stays valid, so no create-site null check is needed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

implementations/Crafter.Graphics-ComputeShader.cpp

@@ -82,7 +82,7 @@ void ComputeShader::Load(const std::filesystem::path& spvPath) {
         .layout = VK_NULL_HANDLE,
     };
     Device::CheckVkResult(vkCreateComputePipelines(
-        Device::device, VK_NULL_HANDLE, 1, &info, nullptr, &pipeline));
+        Device::device, Device::pipelineCache, 1, &info, nullptr, &pipeline));
 }
 
 void ComputeShader::Dispatch(VkCommandBuffer cmd,

implementations/Crafter.Graphics-Device.cpp

@@ -136,6 +136,97 @@ void Device::CheckVkResult(VkResult result) {
     }
 }
 
+bool Device::PipelineCacheDataCompatible(std::span<const std::byte> data) {
+    // VkPipelineCacheHeaderVersionOne is a fixed 32-byte little-endian header
+    // (Vulkan spec 16.5.2): u32 headerSize, u32 headerVersion, u32 vendorID,
+    // u32 deviceID, then VK_UUID_SIZE bytes of pipelineCacheUUID. Parse the
+    // fields by offset rather than reinterpret_cast'ing the struct so the
+    // check is independent of the C struct's alignment/padding.
+    constexpr std::size_t headerBytes = 16 + VK_UUID_SIZE;
+    if (data.size() < headerBytes) {
+        return false;
+    }
+
+    auto readU32 = [&](std::size_t offset) {
+        std::uint32_t value;
+        std::memcpy(&value, data.data() + offset, sizeof(value));
+        return value;
+    };
+
+    const std::uint32_t headerSize    = readU32(0);
+    const std::uint32_t headerVersion = readU32(4);
+    const std::uint32_t vendorID      = readU32(8);
+    const std::uint32_t deviceID      = readU32(12);
+
+    if (headerSize < headerBytes) {
+        return false;
+    }
+    if (headerVersion != VK_PIPELINE_CACHE_HEADER_VERSION_ONE) {
+        return false;
+    }
+    if (vendorID != deviceProperties.vendorID || deviceID != deviceProperties.deviceID) {
+        return false;
+    }
+    return std::memcmp(data.data() + 16, deviceProperties.pipelineCacheUUID, VK_UUID_SIZE) == 0;
+}
+
+void Device::LoadPipelineCache() {
+    std::vector<std::byte> initialData;
+
+    std::error_code ec;
+    if (std::filesystem::exists(pipelineCachePath, ec)) {
+        std::ifstream file(pipelineCachePath, std::ios::binary | std::ios::ate);
+        if (file) {
+            const std::streamoff size = file.tellg();
+            if (size > 0) {
+                initialData.resize(static_cast<std::size_t>(size));
+                file.seekg(0);
+                file.read(reinterpret_cast<char*>(initialData.data()), size);
+                if (!file) {
+                    initialData.clear();  // partial/short read — start cold
+                }
+            }
+        }
+    }
+
+    // Drop a blob the current driver/device wouldn't accept: a header from a
+    // different GPU (or a corrupt/empty file) would at best be ignored and at
+    // worst rejected. Starting empty just costs a one-time cold compile.
+    if (!PipelineCacheDataCompatible(initialData)) {
+        initialData.clear();
+    }
+
+    VkPipelineCacheCreateInfo info {
+        .sType           = VK_STRUCTURE_TYPE_PIPELINE_CACHE_CREATE_INFO,
+        .initialDataSize = initialData.size(),
+        .pInitialData    = initialData.empty() ? nullptr : initialData.data(),
+    };
+    CheckVkResult(vkCreatePipelineCache(device, &info, nullptr, &pipelineCache));
+}
+
+void Device::SavePipelineCache() {
+    if (pipelineCache == VK_NULL_HANDLE) {
+        return;
+    }
+
+    // Two-call idiom: query size, then fetch. Best-effort — a failure here only
+    // forfeits the next run's warm start, so it must never throw out of an
+    // atexit handler.
+    std::size_t size = 0;
+    if (vkGetPipelineCacheData(device, pipelineCache, &size, nullptr) != VK_SUCCESS || size == 0) {
+        return;
+    }
+    std::vector<std::byte> data(size);
+    if (vkGetPipelineCacheData(device, pipelineCache, &size, data.data()) != VK_SUCCESS) {
+        return;
+    }
+
+    std::ofstream file(pipelineCachePath, std::ios::binary | std::ios::trunc);
+    if (file) {
+        file.write(reinterpret_cast<const char*>(data.data()), static_cast<std::streamsize>(size));
+    }
+}
+
 VkBool32 onError(VkDebugUtilsMessageSeverityFlagBitsEXT severity, VkDebugUtilsMessageTypeFlagsEXT type, const VkDebugUtilsMessengerCallbackDataEXT* callbackData, void* userData)
 {
     printf("Vulkan ");
@@ -603,6 +694,9 @@ void Device::Initialize() {
         .pNext = &rayTracingProperties
     };
     vkGetPhysicalDeviceProperties2(physDevice, &properties2);
+    // Keep the core properties around for the pipeline-cache identity check
+    // (vendorID / deviceID / pipelineCacheUUID).
+    deviceProperties = properties2.properties;
 
     // NVIDIA's brand-new VK_EXT_descriptor_heap acceleration-structure read
     // path faults (see #7); enable the SPIR-V rewrite workaround there. Other
@@ -810,6 +904,14 @@ void Device::Initialize() {
             memoryDecompressionSupported = false;
         }
     }
+
+    // Create the shared pipeline cache (seeded from disk when a compatible
+    // blob exists) and arrange for it to be written back at process exit. The
+    // device handle is a never-destroyed static, so it is still valid when the
+    // atexit handler runs. Registered once — Initialize is the single device
+    // bring-up.
+    LoadPipelineCache();
+    std::atexit(SavePipelineCache);
 }
 
 std::uint32_t Device::GetMemoryType(uint32_t typeBits, VkMemoryPropertyFlags required, VkMemoryPropertyFlags preferred) {

interfaces/Crafter.Graphics-Device.cppm

@@ -161,6 +161,27 @@ export namespace Crafter {
 
         inline static VkPhysicalDeviceMemoryProperties memoryProperties;
 
+        // Core physical-device properties, captured once at Initialize from the
+        // VkPhysicalDeviceProperties2 query. Kept because the pipeline-cache
+        // persistence path needs vendorID / deviceID / pipelineCacheUUID to
+        // decide whether an on-disk blob was written by this exact device.
+        inline static VkPhysicalDeviceProperties deviceProperties = {};
+
+        // One process-wide pipeline cache fed to every vkCreate*Pipelines call
+        // (compute UI/user shaders + RT pipelines). Pipeline compilation is a
+        // one-time cold-start cost, not a per-frame one; a single shared cache
+        // lets the driver reuse compiled shader binaries across the several
+        // pipelines built at startup and — once persisted to disk (see
+        // LoadPipelineCache / SavePipelineCache) — across runs. VK_NULL_HANDLE
+        // until LoadPipelineCache runs; passing VK_NULL_HANDLE to a create call
+        // is valid and simply means "no cache", so the create sites need no
+        // null check.
+        inline static VkPipelineCache pipelineCache = VK_NULL_HANDLE;
+        // Where the serialized cache lives. Relative to the working directory,
+        // matching the gpu_crash_dump-* convention. Set before Initialize to
+        // relocate it.
+        inline static std::filesystem::path pipelineCachePath = "pipeline_cache.bin";
+
         inline static VkPhysicalDeviceDescriptorHeapPropertiesEXT descriptorHeapProperties = {
             .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_DESCRIPTOR_HEAP_PROPERTIES_EXT
         };
@@ -199,6 +220,23 @@ export namespace Crafter {
         // ComputeShader read the offset off the pipeline they record.
 
         static void CheckVkResult(VkResult result);
+
+        // ─── Pipeline cache persistence (issue #69) ─────────────────────
+        // LoadPipelineCache creates `pipelineCache`, seeding it from
+        // pipelineCachePath when the file exists *and* its header matches this
+        // device (PipelineCacheDataCompatible) — a stale or foreign blob is
+        // discarded so the driver never rejects it. Called once from
+        // Initialize. SavePipelineCache writes the driver's current cache blob
+        // back out; Initialize registers it with std::atexit so the cache is
+        // serialized at process shutdown without any explicit teardown call.
+        static void LoadPipelineCache();
+        static void SavePipelineCache();
+        // True when `data` is a VkPipelineCache blob whose header was written by
+        // a device with the same vendorID / deviceID / pipelineCacheUUID as
+        // `deviceProperties`. Pure logic over the standard 32-byte cache header,
+        // so it is driven directly by the PipelineCacheValidation test with no
+        // GPU device. A blob too short to hold the header is incompatible.
+        static bool PipelineCacheDataCompatible(std::span<const std::byte> data);
         // Selects a memory type index from typeBits that satisfies `required`.
         // When `preferred` bits are also given, a type satisfying both is
         // chosen first; if none exists we fall back to required-only rather

interfaces/Crafter.Graphics-PipelineRTVulkan.cppm

@@ -82,7 +82,7 @@ export namespace Crafter {
                 .layout = VK_NULL_HANDLE
             };
 
-            Device::CheckVkResult(Device::vkCreateRayTracingPipelinesKHR(Device::device, {}, {}, 1, &rtPipelineInfo, nullptr, &pipeline));
+            Device::CheckVkResult(Device::vkCreateRayTracingPipelinesKHR(Device::device, {}, Device::pipelineCache, 1, &rtPipelineInfo, nullptr, &pipeline));
 
             std::size_t dataSize = Device::rayTracingProperties.shaderGroupHandleSize * rtPipelineInfo.groupCount;
             shaderHandles.resize(dataSize);