Skip to content

Introduced unified vk::DispatchLoader and removed dispatcher templating#2497

Draft
M2-TE wants to merge 13 commits intoKhronosGroup:mainfrom
M2-TE:dispatcher-begone
Draft

Introduced unified vk::DispatchLoader and removed dispatcher templating#2497
M2-TE wants to merge 13 commits intoKhronosGroup:mainfrom
M2-TE:dispatcher-begone

Conversation

@M2-TE
Copy link
Contributor

@M2-TE M2-TE commented Feb 21, 2026

This PR aims to massively reduce the templating required for most functions and reduce dispatcher complexity by offering only a single unified dispatcher interface. Blocked by #2495, #2496 and #2502. Resolves #2490.

Summary of changes:

  1. Unified dispatch loader under the new vk::DispatchLoader, which is provided in vulkan_dispatch_loader.hpp and is able to handle both dynamic dispatching (ProcAddr), as well as static dispatching (vulkan-1). The former works just as the previous dynamic dispatcher, while the latter simply default-assigns to the Vulkan C functions. This is done for core and WSI functions only (see vulkan-1 symbols).
  2. The vk::DispatchLoader is in the normal vk namespace. Only the vk::detail::DynamicLoader should be an implementation detail.
  3. Removed static and dynamic dispatchers, without breaking compatibility (all macros still work as expected).
  4. Removed the forward-declaration of the dispatcher that was previously used for the dynamic one. The header can be included at the very start of vulkan.hpp. The init functions using vk::Instance and vk::Device are simply forward declared and defined later (they are very small as the bulk init uses VkInstance and VkDevice).
  5. Removed dispatcher templating from functions and handles that used them. This simplifies their interface and helps compilation times. Biggest offender is still vulkan_structs.hpp, but it's a start.
  6. Removed getVkHeaderVersion() from the dispatcher, as the version comparison check is handled by the header itself. Besides, using a dispatcher from a slightly outdated header should be allowed (e.g. when it is placed in a dynamic libary).

There are some downsides that might warrant discussion:

  1. With dispatcher templates gone, the intended way to create "custom" dispatchers is to simply inherit from vk::DispatchLoader. You will have storage for all the function pointers, but can implement your own init() functions to only load what you need. Can also override the static dispatcher portion (though that likely won't ever be needed).
  2. What goes into the static dispatcher is not really standardized. There is not much we can do about that, except adhere to the default vulkan-1 list of symbols. To be honest though, dynamic dispatching should probably be the standard as that is what most people use.

Current issue:

The vk::UniqueHandles are broken. This is not due to my PR specifically, but because the templating is gone from some of the functions, resulting in the compiler actually checking them for validity. This is further explained in #2496. Because of this, I temporarily disabled tests using the smart handles, as well as samples in general.
Another similar issue blocks progress, as described in #2502.

ETC:

Another one of my goals was to try and merge the normal dispatching with raii dispatching, but that is a bit more challenging. The raii dispatchers are three separate ones; one for context, one for instance and another for device functions.

However, this raii setup transparently handles dynamic dispatching in a very clean way, even automatically handling per-device functions perfectly. It might be worth discussing a VULKAN_HPP_* flag that allows normal vk::Instance and vk::Device handles to each store their own dispatcher. Even with careless C<->C++ handle casting, this should be fine and actually make things much easier for users, especially beginners! No more explicit dynamic dispatch storage or anything.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make vk::detail::... reachable but not visible in the C++ module

1 participant