|
| 1 | +# Extension support in a layer |
| 2 | + |
| 3 | +It might be useful for some layers to implement an extension, such as |
| 4 | +`VK_EXT_frame_boundary`, even if the underlying driver does not support it. |
| 5 | +This page explains the general approach that needs to be taken, and the |
| 6 | +specific API modifications that need to be applied for specific extensions. |
| 7 | + |
| 8 | +Note that the core framework allows you to expose additional extensions via |
| 9 | +the default `vkEnumerate*ExtensionProperties()` implementation, but per-layer |
| 10 | +code must implement the API modifications to other functions as needed. |
| 11 | + |
| 12 | +## Exposing a new extension |
| 13 | + |
| 14 | +New extensions are advertised to applications by adding the extension string to |
| 15 | +the list returned by `vkEnumerate*ExtensionProperties()`. This functionality |
| 16 | +is provided in the common framework default functions. Layer implementations |
| 17 | +add the new extension information that they want to expose to either: |
| 18 | + |
| 19 | +* `Instance::injectedInstanceExtensions` for instance extensions. |
| 20 | +* `Instance::injectedDeviceExtensions` for device extensions. |
| 21 | + |
| 22 | +Device extensions will be removed from this list if we can detect that the |
| 23 | +underlying device already supports them, which means we can just pass through. |
| 24 | + |
| 25 | +### Handling extended API entry points |
| 26 | + |
| 27 | +All entrypoints that are touched by an extension need to be intercepted with |
| 28 | +a `user_tag` version of a function, which will implement the functionality that |
| 29 | +the layer requires. |
| 30 | + |
| 31 | +If the driver beneath the layer actually supports the extension, the extended |
| 32 | +API parameters can be passed down to the driver without modification. This |
| 33 | +scenario can be detected by checking that the extension name is no longer in |
| 34 | +the `injectedExtensions` list, although the layer will probably want to cache |
| 35 | +this check to reduce performance overhead. |
| 36 | + |
| 37 | +If the driver beneath the layer does not support the extension, the extended |
| 38 | +API parameters must be rewritten to remove the extension before passing down |
| 39 | +to the driver. User structure inputs to the Vulkan API are usually marked as |
| 40 | +`const`, so we must take a safe-struct copy which we can modify and pass |
| 41 | +that copy to the driver. |
| 42 | + |
| 43 | +## Common extension notes |
| 44 | + |
| 45 | +This section is a set of brief notes about extensions that we have implemented, |
| 46 | +summarizing the changes needed and referencing where you can find an example |
| 47 | +of the changes if you need something similar. |
| 48 | + |
| 49 | +### VK_EXT_frame_boundary |
| 50 | + |
| 51 | +This extension allows applications to annotate arbitrary submit calls to |
| 52 | +indicate which frame the submitted work belongs to, instead of relying on |
| 53 | +`vkQueuePresent()`. This can be useful for multi-threaded applications, |
| 54 | +where CPU processing for frames can overlap, and for applications which |
| 55 | +do not have frames, but that want to use tools such as RenderDoc that |
| 56 | +require them. |
| 57 | + |
| 58 | +#### Exposing extension |
| 59 | + |
| 60 | +Adding exposure handling: |
| 61 | + |
| 62 | +* Add `VK_EXT_frame_boundary` to device extension list. |
| 63 | +* Add `VkPhysicalDeviceFrameBoundary` to `VkPhysicalDeviceFeatures2.pNext` list |
| 64 | + returned by `vkGetPhysicalDeviceFeatures2()`, or force existing structure to |
| 65 | + `VK_TRUE`, if not supported by driver. |
| 66 | +* Query `VkPhysicalDeviceFrameBoundary` in `VkDeviceCreateInfo.pNext` to see if |
| 67 | + application enabled the extension. Strip if not supported by the driver. |
| 68 | + |
| 69 | +#### Implementing extension |
| 70 | + |
| 71 | +Adding implementation handling: |
| 72 | + |
| 73 | +* Add `VkFrameBoundaryEXT` extension struct handling to: |
| 74 | + * `vkQueueSubmit()` |
| 75 | + * `vkQueueSubmit2()` |
| 76 | + * `vkQueuePresent()` |
| 77 | + * `vkQueueBindSparse()` |
| 78 | + |
| 79 | +#### Implementation notes |
| 80 | + |
| 81 | +Most applications using this that I have seen are using it to demarcate frames |
| 82 | +when using a single submitting render thread for off-screen rendering or |
| 83 | +compute use cases that do not use `vkQueuePresent()`. In these systems just |
| 84 | +detecting a change in frame ID is enough to indicate "frame changed", much |
| 85 | +how we would use `vkQueuePresent()` to do the same without this extension. |
| 86 | + |
| 87 | +It is possible for applications to have multiple concurrent frames being |
| 88 | +submitted in an overlapping manner, which can be handled by tagging work with |
| 89 | +the frame ID found in the extension structure for each `vkQueue*()` call. This |
| 90 | +will require downstream data handling to cope with overlapping frame |
| 91 | +submissions, which most of our layers do not handle, as it is rarely |
| 92 | +encountered. |
| 93 | + |
| 94 | +- - - |
| 95 | + |
| 96 | +_Copyright © 2025, Arm Limited and contributors._ |
0 commit comments