Cache prewarm base case (#9552)

anishmgoyal · web-flow · commit 5a14fb4b5da5 · 2026-01-08T11:43:32.000-08:00
Prevents hitching for most pipelines, on certain devices with Turnip-based drivers

This does not address external samplers yet. This simply handles the
case where we want to prewarm a pipeline with the base configuration.

Refactor program's descriptor set layout bindings, clean up some leaking
resources
diff --git a/filament/backend/include/backend/Platform.h b/filament/backend/include/backend/Platform.h
@@ -320,6 +320,12 @@ class UTILS_PUBLIC Platform {
          */
         StereoscopicType stereoscopicType = StereoscopicType::NONE;
 
+        /*
+         * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
+         * between 1 and Engine::getMaxStereoscopicEyes() (inclusive).
+         */
+        uint8_t stereoscopicEyeCount = 2;
+
         /**
          * Assert the native window associated to a SwapChain is valid when calling makeCurrent().
          * This is only supported for:
diff --git a/filament/backend/include/backend/Program.h b/filament/backend/include/backend/Program.h
@@ -50,8 +50,13 @@ class Program {
         descriptor_binding_t binding;
     };
 
+    struct DescriptorSetLayoutBinding {
+        descriptor_set_t set;
+        DescriptorSetLayout layout;
+    };
+
     using SpecializationConstant = std::variant<int32_t, float, bool>;
-    using DescriptorSetLayoutArray = std::array<DescriptorSetLayout, MAX_DESCRIPTOR_SET_COUNT>;
+    using DescriptorSetLayoutArray = utils::FixedCapacityVector<DescriptorSetLayoutBinding>;
 
     struct Uniform { // For ES2 support
         utils::CString name;    // full qualified name of the uniform field
@@ -150,7 +155,10 @@ class Program {
 
     inline Program& descriptorLayout(backend::descriptor_set_t set,
             DescriptorSetLayout descriptorLayout) noexcept {
-        mDescriptorLayouts[set] = std::move(descriptorLayout);
+        mDescriptorLayouts.push_back({
+            .set = set,
+            .layout = std::move(descriptorLayout),
+        });
         return *this;
     }
 
@@ -189,7 +197,8 @@ class Program {
 
     // Descriptions for descriptor set layouts that may be used for this Program, which
     // can be useful for attempting to compile the pipeline ahead of time.
-    DescriptorSetLayoutArray mDescriptorLayouts;
+    DescriptorSetLayoutArray mDescriptorLayouts =
+        DescriptorSetLayoutArray::with_capacity(MAX_DESCRIPTOR_SET_COUNT);
 
     // For ES2 support only
     AttributesInfo mAttributes;
diff --git a/filament/backend/include/backend/platforms/VulkanPlatform.h b/filament/backend/include/backend/platforms/VulkanPlatform.h
@@ -28,6 +28,7 @@
 #include <utils/Hash.h>
 #include <utils/PrivateImplementation.h>
 
+#include <cstring>
 #include <cstddef>
 #include <functional>
 #include <string>
@@ -61,8 +62,15 @@ class VulkanPlatform : public Platform, utils::PrivateImplementation<VulkanPlatf
             return std::hash<std::string>{}(s.data());
         }
     };
+    // Note: utils::CString::operator== has an edge case that breaks for the extension set.
+    // Instead, we'll provide our own comparator.
+    struct ExtensionEqualFn {
+        bool operator()(utils::CString const& a, utils::CString const& b) const noexcept {
+            return strcmp(a.c_str(), b.c_str()) == 0;
+        }
+    };
     // Utility for managing device or instance extensions during initialization.
-    using ExtensionSet = std::unordered_set<utils::CString, ExtensionHashFn>;
+    using ExtensionSet = std::unordered_set<utils::CString, ExtensionHashFn, ExtensionEqualFn>;
 
     /**
      * A collection of handles to objects and metadata that comprises a Vulkan context. The client
diff --git a/filament/backend/src/vulkan/VulkanDriver.cpp b/filament/backend/src/vulkan/VulkanDriver.cpp
@@ -251,6 +251,7 @@ VulkanDriver::VulkanDriver(VulkanPlatform* platform, VulkanContext& context,
       mIsSRGBSwapChainSupported(mPlatform->getCustomization().isSRGBSwapChainSupported),
       mIsMSAASwapChainSupported(false), // TODO: support MSAA swapchain
       mStereoscopicType(driverConfig.stereoscopicType),
+      mStereoscopicEyeCount(driverConfig.stereoscopicEyeCount),
       mAsynchronousMode(driverConfig.asynchronousMode) {
 
 #if FVK_ENABLED(FVK_DEBUG_DEBUG_UTILS)
@@ -796,6 +797,32 @@ void VulkanDriver::createProgramR(Handle<HwProgram> ph, Program&& program, utils
             program);
     vprogram.inc();
     mResourceManager.associateHandle(ph.getId(), std::move(tag));
+
+    if (!mContext.shouldUsePipelineCachePrewarming()) {
+        return;
+    }
+
+    // If async prewarming is enabled, let's find the proper layout and build the pipeline.
+    VulkanDescriptorSetLayout::DescriptorSetLayoutArray vkLayouts {};
+    for (const auto& layoutBinding : program.getDescriptorSetLayouts()) {
+        DescriptorSetLayout layoutDescription = layoutBinding.layout;
+        auto layoutHandle = mResourceManager.allocHandle<VulkanDescriptorSetLayout>();
+        auto layout = mDescriptorSetLayoutCache.createLayout(layoutHandle, std::move(layoutDescription));
+        vkLayouts[layoutBinding.set] = layout->getVkLayout();
+    }
+
+    StereoscopicType stereoscopicType = mStereoscopicType;
+    if (stereoscopicType == StereoscopicType::MULTIVIEW && !program.isMultiview()) {
+        stereoscopicType = StereoscopicType::NONE;
+    }
+
+    VkPipelineLayout layout = mPipelineLayoutCache.getLayout(vkLayouts, vprogram);
+    mPipelineCache.asyncPrewarmCache(
+        *vprogram.get(),
+        layout,
+        stereoscopicType,
+        mStereoscopicEyeCount,
+        program.getPriorityQueue());
 }
 
 void VulkanDriver::destroyProgram(Handle<HwProgram> ph) {
@@ -1800,7 +1827,11 @@ void VulkanDriver::generateMipmaps(Handle<HwTexture> th) {
 void VulkanDriver::compilePrograms(CompilerPriorityQueue priority,
         CallbackHandler* handler, CallbackHandler::Callback callback, void* user) {
     if (callback) {
-        scheduleCallback(handler, user, callback);
+        if (mContext.shouldUsePipelineCachePrewarming()) {
+            mPipelineCache.addCachePrewarmCallback(handler, callback, user);
+        } else {
+            scheduleCallback(handler, user, callback);
+        }
     }
 }
 
diff --git a/filament/backend/src/vulkan/VulkanDriver.h b/filament/backend/src/vulkan/VulkanDriver.h
@@ -206,6 +206,7 @@ class VulkanDriver final : public DriverBase {
     bool const mIsSRGBSwapChainSupported;
     bool const mIsMSAASwapChainSupported;
     backend::StereoscopicType const mStereoscopicType;
+    uint8_t const mStereoscopicEyeCount;
     backend::AsynchronousMode const mAsynchronousMode;
 
     // setAcquiredImage is a DECL_DRIVER_API_SYNCHRONOUS_N which means we don't necessarily have the
diff --git a/filament/backend/src/vulkan/VulkanPipelineCache.cpp b/filament/backend/src/vulkan/VulkanPipelineCache.cpp
@@ -107,7 +107,7 @@ VulkanPipelineCache::PipelineCacheEntry* VulkanPipelineCache::getOrCreatePipelin
         .handle = createPipeline(mPipelineRequirements),
         .lastUsed = mCurrentTime,
     };
-    assert_invariant(cacheEntry.handle != VK_NULL_HANDLE && "Pipeline handle is nullptr");
+    assert_invariant(cacheEntry.handle != VK_NULL_HANDLE && "Pipeline handle is VK_NULL_HANDLE");
     return &mPipelines.emplace(mPipelineRequirements, cacheEntry).first.value();
 }
 
@@ -126,7 +126,66 @@ void VulkanPipelineCache::bindPipeline(VulkanCommandBuffer* commands) {
     }
 }
 
-VkPipeline VulkanPipelineCache::createPipeline(const PipelineKey& key) noexcept {
+void VulkanPipelineCache::asyncPrewarmCache(const VulkanProgram& program,
+        VkPipelineLayout layout,
+        StereoscopicType stereoscopicType,
+        uint8_t stereoscopicViewCount, CompilerPriorityQueue priority) {
+    PipelineKey key {
+        .shaders = {
+            program.getVertexShader(),
+            program.getFragmentShader(),
+        },
+        // We're using dynamic rendering, so this should be empty.
+        .renderPass = VK_NULL_HANDLE,
+        .topology = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST,
+        .subpassIndex = 0,
+        // We're using vertex input dynamic state, so these should be empty.
+        .vertexAttributes = {},
+        .vertexBuffers = {},
+        // Create a reasonable default raster state; we're assuming this is not cached.
+        .rasterState = {
+            .cullMode = VK_CULL_MODE_NONE,
+            .frontFace = VK_FRONT_FACE_COUNTER_CLOCKWISE,
+            .depthBiasEnable = VK_FALSE,
+            .blendEnable = VK_FALSE,
+            .depthWriteEnable = VK_FALSE,
+            .alphaToCoverageEnable = VK_FALSE,
+            .srcColorBlendFactor = VK_BLEND_FACTOR_ONE,
+            .dstColorBlendFactor = VK_BLEND_FACTOR_ONE,
+            .srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE,
+            .dstAlphaBlendFactor = VK_BLEND_FACTOR_ONE,
+            .colorWriteMask = 0,
+            .rasterizationSamples = VK_SAMPLE_COUNT_1_BIT,
+            .depthClamp = VK_FALSE,
+            .colorTargetCount = 1,
+            .colorBlendOp = BlendEquation::SUBTRACT,
+            .alphaBlendOp = BlendEquation::SUBTRACT,
+            .depthCompareOp = SamplerCompareFunc::L,
+            .depthBiasConstantFactor = 0.f,
+            .depthBiasSlopeFactor = 0.f,
+        },
+        .layout = layout,
+    };
+    PipelineDynamicOptions dynamicOptions {
+        .useDynamicVertexInputState = true,
+        .useDynamicRenderPasses = true,
+        .stereoscopicType = stereoscopicType,
+        .stereoscopicViewCount = stereoscopicViewCount,
+    };
+
+    CallbackManager::Handle cmh = mCallbackManager.get();
+    auto token = std::make_shared<ProgramToken>();
+    mCompilerThreadPool.queue(priority, token, [this, key, dynamicOptions, cmh]() mutable {
+        VkPipeline pipeline = createPipeline(key, dynamicOptions);
+        mCallbackManager.put(cmh);
+        // We don't actually need this pipeline, we just wanted to force the driver to cache
+        // the pipeline's information.
+        vkDestroyPipeline(mDevice, pipeline, VKALLOC);
+    });
+}
+
+VkPipeline VulkanPipelineCache::createPipeline(
+        const PipelineKey& key, const PipelineDynamicOptions& dynamicOptions) noexcept {
     assert_invariant(key.shaders[0] && "Vertex shader is not bound.");
     assert_invariant(key.layout && "No pipeline layout specified");
 
@@ -150,27 +209,30 @@ VkPipeline VulkanPipelineCache::createPipeline(const PipelineKey& key) noexcept
         .pAttachments = colorBlendAttachments,
     };
 
-    // Expand our size-optimized structs into the proper Vk structs.
-    uint32_t numVertexAttribs = 0;
-    uint32_t numVertexBuffers = 0;
-
+    VkPipelineVertexInputStateCreateInfo vertexInputState;
     VkVertexInputAttributeDescription vertexAttributes[VERTEX_ATTRIBUTE_COUNT];
     VkVertexInputBindingDescription vertexBuffers[VERTEX_ATTRIBUTE_COUNT];
-    for (uint32_t i = 0; i < VERTEX_ATTRIBUTE_COUNT; i++) {
-        if (key.vertexAttributes[i].format > 0) {
-            vertexAttributes[numVertexAttribs++] = key.vertexAttributes[i];
-        }
-        if (key.vertexBuffers[i].stride > 0) {
-            vertexBuffers[numVertexBuffers++] = key.vertexBuffers[i];
+    if (!dynamicOptions.useDynamicVertexInputState) {
+        uint32_t numVertexAttribs = 0;
+        uint32_t numVertexBuffers = 0;
+
+        for (uint32_t i = 0; i < VERTEX_ATTRIBUTE_COUNT; i++) {
+            if (key.vertexAttributes[i].format > 0) {
+                vertexAttributes[numVertexAttribs++] = key.vertexAttributes[i];
+            }
+            if (key.vertexBuffers[i].stride > 0) {
+                vertexBuffers[numVertexBuffers++] = key.vertexBuffers[i];
+            }
         }
+        vertexInputState = {
+            .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO,
+            .vertexBindingDescriptionCount = numVertexBuffers,
+            .pVertexBindingDescriptions = vertexBuffers,
+            .vertexAttributeDescriptionCount = numVertexAttribs,
+            .pVertexAttributeDescriptions = vertexAttributes,
+        };
     }
-    VkPipelineVertexInputStateCreateInfo vertexInputState = {
-        .sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO,
-        .vertexBindingDescriptionCount = numVertexBuffers,
-        .pVertexBindingDescriptions = vertexBuffers,
-        .vertexAttributeDescriptionCount = numVertexAttribs,
-        .pVertexAttributeDescriptions = vertexAttributes,
-    };
+
     VkPipelineInputAssemblyStateCreateInfo inputAssemblyState = {
         .sType = VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO,
         .topology = (VkPrimitiveTopology) key.topology,
@@ -180,15 +242,22 @@ VkPipeline VulkanPipelineCache::createPipeline(const PipelineKey& key) noexcept
         .viewportCount = 1,
         .scissorCount = 1,
     };
-    VkDynamicState dynamicStateEnables[] = {
+
+    constexpr size_t maxDynamicStates = 3;
+    size_t numDynamicStates = 2;
+    VkDynamicState enabledDynamicStates[maxDynamicStates] = {
         VK_DYNAMIC_STATE_VIEWPORT,
         VK_DYNAMIC_STATE_SCISSOR,
     };
+    if (dynamicOptions.useDynamicVertexInputState) {
+        enabledDynamicStates[numDynamicStates++] = VK_DYNAMIC_STATE_VERTEX_INPUT_EXT;
+    }
     VkPipelineDynamicStateCreateInfo dynamicState = {
         .sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO,
-        .dynamicStateCount = 2,
-        .pDynamicStates = dynamicStateEnables,
+        .dynamicStateCount = static_cast<uint32_t>(numDynamicStates),
+        .pDynamicStates = enabledDynamicStates,
     };
+
     auto const& raster = key.rasterState;
     VkPipelineRasterizationStateCreateInfo vkRaster = {
         .sType = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO,
@@ -237,7 +306,7 @@ VkPipeline VulkanPipelineCache::createPipeline(const PipelineKey& key) noexcept
         .sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO,
         .stageCount = hasFragmentShader ? SHADER_MODULE_COUNT : 1,
         .pStages = shaderStages,
-        .pVertexInputState = &vertexInputState,
+        .pVertexInputState = dynamicOptions.useDynamicVertexInputState ? nullptr : &vertexInputState,
         .pInputAssemblyState = &inputAssemblyState,
         .pViewportState = &viewportState,
         .pRasterizationState = &vkRaster,
@@ -271,6 +340,27 @@ VkPipeline VulkanPipelineCache::createPipeline(const PipelineKey& key) noexcept
         }
     }
 
+    VkPipelineRenderingCreateInfoKHR renderingInfo {};
+    VkFormat pipelineRenderingColorFormats[] = {VK_FORMAT_UNDEFINED};
+    if (dynamicOptions.useDynamicRenderPasses) {
+        renderingInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO_KHR;
+        renderingInfo.pNext = pipelineCreateInfo.pNext;
+        // Fill values in with empty values where we do not already have values.
+        renderingInfo.depthAttachmentFormat = VK_FORMAT_UNDEFINED;
+        renderingInfo.stencilAttachmentFormat = VK_FORMAT_UNDEFINED;
+        // If multiview, create a bitmask with bits representing each enabled view set to 1;
+        // otherwise, set the view mask to 0.
+        renderingInfo.viewMask = dynamicOptions.stereoscopicType == StereoscopicType::MULTIVIEW ?
+            (1 << dynamicOptions.stereoscopicViewCount) - 1 : 0;
+
+        if (hasFragmentShader) {
+            renderingInfo.colorAttachmentCount = 1;
+            renderingInfo.pColorAttachmentFormats = pipelineRenderingColorFormats;
+        }
+
+        pipelineCreateInfo.pNext = &renderingInfo;
+    }
+
 #if FVK_ENABLED(FVK_DEBUG_SHADER_MODULE)
     FVK_LOGD << "vkCreateGraphicsPipelines with shaders = (" << shaderStages[0].module << ", "
              << shaderStages[1].module << ")";
@@ -351,6 +441,14 @@ void VulkanPipelineCache::bindVertexArray(VkVertexInputAttributeDescription cons
     }
 }
 
+void VulkanPipelineCache::addCachePrewarmCallback(CallbackHandler* handler,
+                                                  const CallbackHandler::Callback callback,
+                                                  void* user) {
+    if (callback) {
+        mCallbackManager.setCallback(handler, callback, user);
+    }
+}
+
 void VulkanPipelineCache::resetBoundPipeline() {
     mBoundPipeline = {};
 }
diff --git a/filament/backend/src/vulkan/VulkanPipelineCache.h b/filament/backend/src/vulkan/VulkanPipelineCache.h
@@ -104,8 +104,16 @@ class VulkanPipelineCache {
     // compiling the pipeline on the main thread at draw time. This is very dependent
     // on the implementation of the driver on the current device; it's expected to work
     // on devices with VK_EXT_vertex_input_dynamic_state and VK_KHR_dynamic_rendering.
-    void asyncPreloadCache(fvkmemory::resource_ptr<VulkanProgram> program,
-                           VkPipelineLayout layout);
+    void asyncPrewarmCache(const VulkanProgram& program, VkPipelineLayout layout,
+                           StereoscopicType stereoscopicType, uint8_t stereoscopicViewCount,
+                           CompilerPriorityQueue priority);
+
+    // Notifies the callback once all in-flight async cache prewarm jobs are complete.
+    // This typically signals that it is safe to use a material at draw time without
+    // hitching.
+    void addCachePrewarmCallback(CallbackHandler* handler,
+                                 const CallbackHandler::Callback callback,
+                                 void* user);
 
     // Creates a new pipeline if necessary and binds it using vkCmdBindPipeline.
     void bindPipeline(VulkanCommandBuffer* commands);
@@ -182,6 +190,19 @@ class VulkanPipelineCache {
         VkPipelineLayout layout;                                                  //  8   : 304
     };
 
+    // Provides information about any dynamic state that should be used in creation of the
+    // pipeline (if supported).
+    struct PipelineDynamicOptions {
+        // Requires `VK_EXT_vertex_input_dynamic_state` to enable.
+        bool useDynamicVertexInputState = false;
+        // Requires `VK_KHR_dynamic_rendering` to enable.
+        bool useDynamicRenderPasses = false;
+        // Only used if `useDynamicRenderPasses` is true.
+        StereoscopicType stereoscopicType = StereoscopicType::NONE;
+        // Only used if `stereoscopicType` is `StereoscopicType::MULTIVIEW`.
+        uint8_t stereoscopicViewCount = 2;
+    };
+
     static_assert(sizeof(PipelineKey) == 312, "PipelineKey must not have implicit padding.");
 
     using PipelineHashFn = utils::hash::MurmurHashFn<PipelineKey>;
@@ -213,8 +234,15 @@ class VulkanPipelineCache {
 
     PipelineMap mPipelines;
 
+    // Creates a pipeline, with all optional dynamic pipeline states diabled.
+    // Note - because PipelineDynamicOptions is defined within VulkanPipelineCache,
+    // we cannot define the function with a default arg for it explicitly.
+    inline VkPipeline createPipeline(const PipelineKey& key) noexcept {
+        return createPipeline(key, {});
+    }
+
     // These helpers all return unstable pointers that should not be stored.
-    VkPipeline createPipeline(const PipelineKey& key) noexcept;
+    VkPipeline createPipeline(const PipelineKey& key, const PipelineDynamicOptions& dynamicOptions) noexcept;
 
     // Immutable state.
     VkDevice mDevice = VK_NULL_HANDLE;
diff --git a/filament/src/details/Engine.cpp b/filament/src/details/Engine.cpp
