Support VK_EXT_frame_boundary (#160)

This PR adds infrastructure for layers to expose and emulate Vulkan 
extensions not supported by the underlying driver, specifically 
implementing VK_EXT_frame_boundary in the layer_gpu_timeline layer. 
The changes introduce a standardized mechanism for extension 
injection and provide an example implementation of frame 
boundary tracking.

Key changes:

Introduces injectedInstanceExtensions and injectedDeviceExtensions 
properties in the Instance class to allow layers to declare additional 
extension support. Layers rebased on top of this change will need to 
provide definitions of these, even if empty. Refactors extension 
enumeration functions to support both driver-native and layer-injected 
extensions.

Implements VK_EXT_frame_boundary emulation in layer_gpu_timeline 
to mark frame boundaries in metadata.

Author: solidpixel

docs/extension_support.md

@@ -0,0 +1,113 @@
+# Extension support in a layer
+
+It might be useful for some layers to implement an extension, such as
+`VK_EXT_frame_boundary`, even if the underlying driver does not support it.
+This page explains the general approach that needs to be taken, and the
+specific API modifications that need to be applied for specific extensions.
+
+The core libGPULayers framework allows you to expose additional extensions via
+the default `vkEnumerate*ExtensionProperties()` implementation, but per-layer
+code must implement the API modifications in any other functions as needed.
+
+## Exposing a new extension
+
+New extensions are advertised to applications by adding the extension string to
+the list returned by `vkEnumerate*ExtensionProperties()`. This functionality
+is provided in the common framework default functions. Layer implementations
+add the new extension information that they want to expose to either:
+
+* `Instance::injectedInstanceExtensions` for instance extensions.
+* `Instance::injectedDeviceExtensions` for device extensions.
+
+Device extensions will be removed from this list if we can detect that the
+underlying device already supports them, which means we can just pass through
+rather than emulating support.
+
+### Handling extended API entry points
+
+All entrypoints that are touched by an extension need to be intercepted with a
+`user_tag` version of that function, which will implement the functionality
+that the layer requires.
+
+If the driver beneath the layer actually supports the extension, the extended
+API parameters can be passed down to the driver without modification. This
+scenario can be detected by checking that the extension name is no longer in
+the `injectedExtensions` list, although the layer will probably want to cache
+this check to reduce performance overhead.
+
+If the driver beneath the layer does not support the extension, the extended
+API parameters should be rewritten to remove the extension before passing down
+to the driver. User structure inputs to the Vulkan API are usually marked as
+`const`, so we must take a safe-struct copy which we can modify and then pass
+that copy to the driver.
+
+Note that Vulkan specifies that components must ignore structures in the
+`pNext` chain that they do not understand:
+
+> Any component of the implementation (the loader, any enabled layers, and
+> drivers) must skip over, without processing (other than reading the `sType`
+> and `pNext` members) any extending structures in the chain not defined by
+> core versions or extensions supported by that component.
+
+Any extension structures can therefore be left in-situ when being emulated, but
+any other API parameter modifications must be unpicked to hide the emulation.
+
+## Common extension notes
+
+This section is a set of brief notes about extensions that we have implemented,
+summarizing the changes needed and referencing where you can find an example
+of the changes if you need something similar.
+
+### VK_EXT_frame_boundary
+
+This extension allows applications to annotate arbitrary submit calls to
+indicate which frame the submitted work belongs to, instead of relying on
+`vkQueuePresent()`. This can be useful for multi-threaded applications,
+where CPU processing for frames can overlap, and for applications which
+do not have frames, but that want to use tools such as RenderDoc that
+require them.
+
+The `layer_gpu_timeline` layer is an example of a layer exposing this
+extension using emulation on devices that do not support it.
+
+#### Exposing extension
+
+Adding exposure handling:
+
+* Add `VK_EXT_frame_boundary` to device extension list.
+* Populate the `VkPhysicalDeviceFrameBoundary` in the
+  `VkPhysicalDeviceFeatures2.pNext` list returned by
+  `vkGetPhysicalDeviceFeatures2()`, forcing the value to `VK_TRUE`, if the
+  extension is "supported" but feature-disabled by the driver.
+* Query `VkPhysicalDeviceFrameBoundary` in `VkDeviceCreateInfo.pNext` to see if
+  application enabled the extension.
+
+#### Implementing extension
+
+Adding implementation handling:
+
+* Add `VkFrameBoundaryEXT` extension struct handling to:
+  * `vkQueueSubmit()`
+  * `vkQueueSubmit2()`
+  * `vkQueuePresent()`
+  * `vkQueueBindSparse()`
+
+#### Implementation notes
+
+Most applications using this that I have seen are using it to demarcate frames
+when using a single submitting render thread for off-screen rendering or
+compute use cases that do not use `vkQueuePresent()`. In these systems just
+detecting the frame boundary flag in the extension structure passed to a queue
+submit is enough, and how we would use `vkQueuePresent()` to do the same
+without this extension.
+
+It is possible for applications to have multiple concurrent frames being
+submitted in an overlapping manner, which can be handled by tagging work with
+the frame ID found in the extension structure for each `vkQueue*()` call. This
+will require downstream data handling to cope with overlapping frame
+submissions, which most of our layers do not handle, as it is rarely
+encountered.
+
+- - -
+
+_Copyright © 2025, Arm Limited and contributors._

generator/vk_layer/source/instance.cpp

@@ -38,10 +38,16 @@ static std::unordered_map<void*, std::unique_ptr<Instance>> g_instances;
 const APIVersion Instance::minAPIVersion { 1, 1 };
 
 /* See header for documentation. */
-const std::vector<std::string> Instance::extraExtensions {
+const std::vector<std::string> Instance::requiredDriverExtensions {
     VK_EXT_DEBUG_UTILS_EXTENSION_NAME
 };
 
+/* See header for documentation. */
+const std::vector<std::pair<std::string, uint32_t>> Instance::injectedInstanceExtensions {};
+
+/* See header for documentation. */
+std::vector<std::pair<std::string, uint32_t>> Instance::injectedDeviceExtensions {};
+
 /* See header for documentation. */
 void Instance::store(
     VkInstance handle,

generator/vk_layer/source/instance.hpp

@@ -143,7 +143,24 @@ class Instance
     static const APIVersion minAPIVersion;
 
     /**
-     * @brief The minimum set of instance extensions needed by this layer.
+     * @brief Required extensions from the driver.
+     *
+     * The layer will attempt to enable these even if the application does not.
+     */
+    static const std::vector<std::string> requiredDriverExtensions;
+
+    /**
+     * @brief Additional instance extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not.
+     */
+    static const std::vector<std::pair<std::string, uint32_t>> injectedInstanceExtensions;
+
+    /**
+     * @brief Additional device extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not. Items are
+     * removed from the list if the driver already exposes the extension.
      */
-    static const std::vector<std::string> extraExtensions;
+    static std::vector<std::pair<std::string, uint32_t>> injectedDeviceExtensions;
 };

layer_example/source/instance.cpp

@@ -35,10 +35,18 @@
 static std::unordered_map<void*, std::unique_ptr<Instance>> g_instances;
 
 /* See header for documentation. */
-const APIVersion Instance::minAPIVersion {1, 1};
+const APIVersion Instance::minAPIVersion { 1, 1 };
 
 /* See header for documentation. */
-const std::vector<std::string> Instance::extraExtensions {VK_EXT_DEBUG_UTILS_EXTENSION_NAME};
+const std::vector<std::string> Instance::requiredDriverExtensions {
+    VK_EXT_DEBUG_UTILS_EXTENSION_NAME
+};
+
+/* See header for documentation. */
+const std::vector<std::pair<std::string, uint32_t>> Instance::injectedInstanceExtensions {};
+
+/* See header for documentation. */
+std::vector<std::pair<std::string, uint32_t>> Instance::injectedDeviceExtensions {};
 
 /* See header for documentation. */
 void Instance::store(VkInstance handle, std::unique_ptr<Instance>& instance)

layer_example/source/instance.hpp

@@ -137,7 +137,24 @@ class Instance
     static const APIVersion minAPIVersion;
 
     /**
-     * @brief The minimum set of instance extensions needed by this layer.
+     * @brief Required extensions from the driver.
+     *
+     * The layer will attempt to enable these even if the application does not.
+     */
+    static const std::vector<std::string> requiredDriverExtensions;
+
+    /**
+     * @brief Additional instance extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not.
+     */
+    static const std::vector<std::pair<std::string, uint32_t>> injectedInstanceExtensions;
+
+    /**
+     * @brief Additional device extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not. Items are
+     * removed from the list if the driver already exposes the extension.
      */
-    static const std::vector<std::string> extraExtensions;
+    static std::vector<std::pair<std::string, uint32_t>> injectedDeviceExtensions;
 };

layer_gpu_profile/source/instance.cpp

@@ -35,13 +35,19 @@
 static std::unordered_map<void*, std::unique_ptr<Instance>> g_instances;
 
 /* See header for documentation. */
-const APIVersion Instance::minAPIVersion {1, 1};
+const APIVersion Instance::minAPIVersion { 1, 1 };
 
 /* See header for documentation. */
-const std::vector<std::string> Instance::extraExtensions {
+const std::vector<std::string> Instance::requiredDriverExtensions {
     VK_EXT_DEBUG_UTILS_EXTENSION_NAME,
 };
 
+/* See header for documentation. */
+const std::vector<std::pair<std::string, uint32_t>> Instance::injectedInstanceExtensions {};
+
+/* See header for documentation. */
+std::vector<std::pair<std::string, uint32_t>> Instance::injectedDeviceExtensions {};
+
 /* See header for documentation. */
 void Instance::store(VkInstance handle, std::unique_ptr<Instance>& instance)
 {

layer_gpu_profile/source/instance.hpp

@@ -143,7 +143,24 @@ class Instance
     static const APIVersion minAPIVersion;
 
     /**
-     * @brief The minimum set of instance extensions needed by this layer.
+     * @brief Required extensions from the driver.
+     *
+     * The layer will attempt to enable these even if the application does not.
+     */
+    static const std::vector<std::string> requiredDriverExtensions;
+
+    /**
+     * @brief Additional instance extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not.
+     */
+    static const std::vector<std::pair<std::string, uint32_t>> injectedInstanceExtensions;
+
+    /**
+     * @brief Additional device extensions injected by the layer.
+     *
+     * The layer will expose these even if the driver does not. Items are
+     * removed from the list if the driver already exposes the extension.
      */
-    static const std::vector<std::string> extraExtensions;
+    static std::vector<std::pair<std::string, uint32_t>> injectedDeviceExtensions;
 };

layer_gpu_profile/source/layer_device_functions_debug.cpp

@@ -42,7 +42,7 @@ VKAPI_ATTR void VKAPI_CALL layer_vkCmdDebugMarkerBeginEXT<user_tag>(VkCommandBuf
     auto* layer = Device::retrieve(commandBuffer);
 
     // Only instrument inside active frame of interest
-    if(layer->isFrameOfInterest)
+    if (layer->isFrameOfInterest)
     {
         auto& tracker = layer->getStateTracker();
         auto& cb = tracker.getCommandBuffer(commandBuffer);
@@ -67,7 +67,7 @@ VKAPI_ATTR void VKAPI_CALL layer_vkCmdDebugMarkerEndEXT<user_tag>(VkCommandBuffe
     auto* layer = Device::retrieve(commandBuffer);
 
     // Only instrument inside active frame of interest
-    if(layer->isFrameOfInterest)
+    if (layer->isFrameOfInterest)
     {
         auto& tracker = layer->getStateTracker();
         auto& cb = tracker.getCommandBuffer(commandBuffer);
@@ -93,7 +93,7 @@ VKAPI_ATTR void VKAPI_CALL layer_vkCmdBeginDebugUtilsLabelEXT<user_tag>(VkComman
     auto* layer = Device::retrieve(commandBuffer);
 
     // Only instrument inside active frame of interest
-    if(layer->isFrameOfInterest)
+    if (layer->isFrameOfInterest)
     {
         auto& tracker = layer->getStateTracker();
         auto& cb = tracker.getCommandBuffer(commandBuffer);
@@ -118,7 +118,7 @@ VKAPI_ATTR void VKAPI_CALL layer_vkCmdEndDebugUtilsLabelEXT<user_tag>(VkCommandB
     auto* layer = Device::retrieve(commandBuffer);
 
     // Only instrument inside active frame of interest
-    if(layer->isFrameOfInterest)
+    if (layer->isFrameOfInterest)
     {
         auto& tracker = layer->getStateTracker();
         auto& cb = tracker.getCommandBuffer(commandBuffer);

layer_gpu_support/source/device.cpp

@@ -180,7 +180,7 @@ static void modifyDeviceRobustBufferAccess(Instance& instance,
     {
         if (enableRobustness)
         {
-            if(config->robustBufferAccess)
+            if (config->robustBufferAccess)
             {
                 LAYER_LOG("Device feature already enabled: robustBufferAccess");
             }
@@ -190,9 +190,10 @@ static void modifyDeviceRobustBufferAccess(Instance& instance,
                 config->robustBufferAccess = VK_TRUE;
             }
         }
+
         if (disableRobustness)
         {
-            if(!config->robustBufferAccess)
+            if (!config->robustBufferAccess)
             {
                 LAYER_LOG("Device feature already disabled: robustBufferAccess");
             }

layer_gpu_support/source/instance.cpp

@@ -35,13 +35,19 @@
 static std::unordered_map<void*, std::unique_ptr<Instance>> g_instances;
 
 /* See header for documentation. */
-const APIVersion Instance::minAPIVersion {1, 1};
+const APIVersion Instance::minAPIVersion { 1, 1 };
 
 /* See header for documentation. */
-const std::vector<std::string> Instance::extraExtensions {
+const std::vector<std::string> Instance::requiredDriverExtensions {
     VK_EXT_DEBUG_UTILS_EXTENSION_NAME,
 };
 
+/* See header for documentation. */
+const std::vector<std::pair<std::string, uint32_t>> Instance::injectedInstanceExtensions {};
+
+/* See header for documentation. */
+std::vector<std::pair<std::string, uint32_t>> Instance::injectedDeviceExtensions {};
+
 /* See header for documentation. */
 void Instance::store(VkInstance handle, std::unique_ptr<Instance>& instance)
 {