VKFL

VKFL is a dynamic command function pointer loader and dispatch table for Vulkan.

While there are plenty of other ways to achieve this I prefer VKFL because:

• VKFL doesn't introduce any global state and namespaces all symbols.
• VKFL doesn't depend directly on libvulkan or the Vulkan headers.
• VKFL doesn't require any special compile time configuration of Vulkan.
• VKFL's generator can generate relatively small files compared to other similar tools.
• VKFL's generator can generate files for specific API versions and extensions (e.g., Vulkan 1.3 with only VK_KHR_surface, VK_KHR_xcb_surface, and VK_KHR_swapchain).
• VKFL is easy to use as a Meson subproject.

Setup

Before VKFL can be generated you need to have Mako and defusedxml installed. You can install these modules automatically with:

pip3 install -r requirements.txt

I recommend setting up and using a virtual environment prior to installing dependencies.

Usage

Once dependencies are installed, the easiest way to include VKFL in a project is as a Meson subproject. This can be done by placing a copy of this repository under your subprojects/ directory and adding the following to your build file. If you're using C++ simply add the following to your meson.build:

vkfl_proj = subproject('vkfl')
vkfl_dep = vkfl_proj.get_variable('vkfl_cpp_dep')

If you'd like to use the C implementation instead add:

vkfl_proj = subproject('vkfl')
vkfl_dep = vkfl_proj.get_variable('vkfl_c_dep')

Afterward, just include vkfl_dep as a dependency of your project.

VKFL can also be used by generating vkfl.hpp and vkfl.cpp directly to do this just build the meson project as follows:

meson setup build
meson compile -C build

Then copy the resulting files (build/include/vkfl.hpp and build/src/vkfl.cpp for C++ or build/include/vkfl.h and build/src/vkfl.c for C) into your project.

Finally, you can use the generator script manually. To do this run tools/generate.py as follows:

# Generates C++ files
mkdir -p build
tools/generate.py include/vkfl.hpp.in build/vkfl.hpp
tools/generate.py src/vkfl.cpp.in build/vkfl.cpp

# Generates C files
mkdir -p build
tools/generate.py include/vkfl.h.in build/vkfl.h
tools/generate.py src/vkfl.c.in build/vkfl.c

Then, simply copy the resulting files as above.

For examples of usage in source code see examples.

Generator Usage

VKFL's generator can be found in tools/generate.py. The usage is as follows:

usage: generate.py [-h] [--spec SPEC] [--extensions EXTENSIONS] [--api API] [--api-version API_VERSION] [--no-enable-deprecated-features] [--no-generate-disabled-defines] INPUT OUTPUT

positional arguments:
  INPUT                 A path to an input template file.
  OUTPUT                A path to an output file.

options:
  -h, --help            show this help message and exit
  --spec SPEC           A file path to an XML specification of the Vulkan API. If this isn't provided, the script will default to searching a set of standard paths for vk.xml.
  --extensions EXTENSIONS
                        A comma separated list of Vulkan extensions to include in the loader. This may also be the special value "all". Defaults to "all".
  --api API             The Vulkan API to include in the loader (e.g., "vulkan", "vulkansc"). Defaults to "vulkan".
  --api-version API_VERSION
                        The latest Vulkan API version to include in the loader (e.g., 1.0, 1.1, 1.2, etc.). This may also be the special value "latest". Defaults to "latest".
  --no-enable-deprecated-features
                        Disable the generation of deprecated features (i.e., extensions). Deprecated features are marked as disabled.
  --no-generate-disabled-defines
                        Disable the generation of symbols indicating that an extension or API version is disabled (i.e., don't generate VKFL_X_ENABLED if it would be defined as 0).

If a specification path is not explicitly provided, the following locations are searched.
Unix-like systems:
  $VULKAN_SDK/share/vulkan/registry/vk.xml
  $HOME/.local/share/vulkan/registry/vk.xml
  /usr/local/share/vulkan/registry/vk.xml
  /usr/share/vulkan/registry/vk.xml
Windows systems:
  %VULKAN_SDK%/share/vulkan/registry/vk.xml
  %VULKAN_SDK_PATH%/share/vulkan/registry/vk.xml

It's possible to use the generator with any input file. However, include/vkfl.hpp.in and src/vkfl.cpp.in are intended to generate the canonical C++ implementation. Similarly, include/vkfl.h.in and src/vkfl.c.in should be used to generate the canonical C implementation.

C and C++ Implementations

VKFL provides both a C18 (i.e., C11) and a C++20 (although it will probably compile with previous standards too) implementation. While these are largely the same they are not necessarily related. You probably shouldn't use both implementations at the same time. In any case, vkfl::loader and vkfl_loader are not guaranteed to be binary compatible. Don't assume you can safely memcpy between them even if it works.

By default both C and C++ implementations are built. To disable one or the other you can configure meson with -Dbuild_c=disabled or -Dbuild_cpp=disabled respectively.

Building Tests and Examples

By default test targets and example targets are disabled. To enable tests ensure that you have a build directory configured and then run:

meson configure build -Dbuild_tests=enabled

To enable examples run:

meson configure build -Dbuild_examples=enabled

The example/global_use.cpp and example/global_use.c files require dlfcn.h, dlopen, dlclose, and dlsym to compile (i.e., they won't compile on Windows).

Building Documentation

HTML documentation requires Doxygen and can be built with the following:

meson compile -C build documentation

Acknowledgments

In earlier versions of VKFL, parts of generate.py were based on the equivalent file from Volk. If you don't like VKFL you should give Volk a try instead. Much of the current implementation was inspired by similar dispatch table generation scripts found in Mesa.