May 14 2018 Simple and efficient Vulkan loading with flextGL

How?

Flex­t­GL con­tains a built­in Vulkan tem­plate that you can use to gen­er­ate a ba­sic load­er. In ad­di­tion you need Py­thon 3 and Wheezy Tem­plate:

pip3 install wheezy.template
git clone git://github.com/mosra/flextGL --branch vulkan

De­sired Vulkan ver­sion, ex­ten­sions and an op­tion­al func­tion white- or black­list is spe­cified us­ing a pro­file file:

version 1.0 vulkan

# Extensions to include on top of the core functionality. The VK_ prefix
# is omitted.
extension KHR_swapchain optional
extension KHR_maintenance1 optional
# ...

# Function whitelist. If you omit this section, all functions from the
# above version and extensions will be pulled in. The vk prefix is omitted.
begin functions
    CreateInstance
    EnumeratePhysicalDevices
    GetPhysicalDeviceProperties
    GetPhysicalDeviceQueueFamilyProperties
    GetPhysicalDeviceMemoryProperties
    # ...
end functions

# You can also choose to have a function blacklist instead, delimited by
# begin functions blacklist and end functions blacklist.

With a pro­file file you can then gen­er­ate the Vulkan load­er head­er + source file like this. The generated/ dir­ect­ory will then con­tain a pair of flextVk.h and flextVk.cpp files:

./flextGLgen.py -D generated -t vulkan profile.txt

Now you can just in­clude it and use. The ac­tu­al func­tion point­er load­ing is done by call­ing flextVkInit() and after that all Vulkan func­tions are avail­able glob­ally:

#include "flextVk.h"

int main() {
    /* Create an instance, load function pointers */
    VkInstance instance;
    {
        VkInstanceCreateInfo info{};
        info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
        vkCreateInstance(&info, nullptr, &instance);
    }
    flextVkInit(instance);

    VkPhysicalDevice physicalDevices[5];
    std::uint32_t count = 5;
    vkEnumeratePhysicalDevices(instance, &count, &physicalDevice);
    ...
}

Why both­er?

Com­pared to OpenGL, Vulkan is still do­ing baby steps, how­ever the amount of avail­able ex­ten­sions is grow­ing at an alarm­ing rate and soon the size of stock “all you can eat” head­ers will have a sig­ni­fic­ant im­pact on your build times. Be­cause Vulkan API is more about vari­ous types than just func­tion point­ers, flex­t­GL en­sures that only the struc­tures, enums and defines that are ac­tu­ally ref­er­enced by func­tions are pulled in, to shrink head­er sizes even fur­ther.

So, let’s have some meas­ure­ments!

wc -l /path/to/header

echo "#include <header>" | g++ -std=c++11 -E -x c++ - | wc -l

Vulkan load­ing in Mag­num

As of mosra/mag­num@b137703, Mag­num ships flex­t­GL-gen­er­ated Vulkan head­ers. To save on del­eg­a­tion over­head, the de­cision was to load per-device func­tion point­ers in­stead of go­ing through per-in­stance func­tion point­ers for everything — that’s also what Volk does with great suc­cess, sav­ing as much as 5% to 10% of driver over­head, de­pend­ing on the work­flow.

Be­sides that, loaded Vulkan func­tions are not glob­al by de­fault in or­der to sup­port mul­tiple co­ex­ist­ing Vulkan in­stances:

#include <MagnumExternal/Vulkan/flextVk.h>

int main() {
    /* Create an instance */
    VkInstance instance;
    {
        VkInstanceCreateInfo info{};
        info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
        // ...
        vkCreateInstance(&info, nullptr, &instance);
    }

    /* Load per-instance function pointers */
    FlextVkInstance i;
    flextVkInitInstance(instance, &i);

    /* Create a device */
    VkPhysicalDevice physicalDevice;
    {
        uint32_t count = 1;
        i.EnumeratePhysicalDevices(instance, &count, &physicalDevice);
    }
    VkDevice device;
    {
        VkDeviceCreateInfo info{};
        info.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO;
        // ...
        i.CreateDevice(physicalDevice, &info, nullptr, &device);
    }

    /* Load per-device function pointers */
    FlextVkDevice d;
    flextVkInitDevice(device, &d, i.GetDeviceProcAddr);

    // ...
}

In the above snip­pet, the i and d struc­tures con­tain all loaded func­tion point­ers. So in­stead of vkCreateBuffer(device, ...) you’d write d.Createbuffer(device, ), for ex­ample. While this is prop­erly de­coupled, it might get in the way when just play­ing around or ad­apt­ing sample code. For that reas­on, Mag­num provides opt-in glob­al func­tion point­ers as well — just in­clude flextVkGlobal.h in­stead of flextVk.h and load your point­ers glob­ally:

#include <MagnumExternal/Vulkan/flextVkGlobal.h>

int main() {
    /* Create an instance */
    VkInstance instance;
    {
        VkInstanceCreateInfo info{};
        info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
        // ...
        vkCreateInstance(&info, nullptr, &instance);
    }

    /* Load per-instance function pointers globally */
    flextVkInitInstance(instance, &flextVkInstance);

    /* Create a device */
    VkPhysicalDevice physicalDevice;
    {
        uint32_t count = 1;
        vkEnumeratePhysicalDevices(instance, &count, &physicalDevice);
    }
    VkDevice device;
    {
        VkDeviceCreateInfo info{};
        info.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO;
        // ...
        vkCreateDevice(physicalDevice, &info, nullptr, &device);
    }

    /* Load per-device function pointers globally */
    flextVkInitDevice(device, &flextVkDevice, vkGetDeviceProcAddr);

    // ...
}

In this case flextVkInitInstance() and flextVkInitDevice() will load the point­ers in­to glob­al flextVkInstance and flextVkDevice struc­tures, which then are ali­ases to glob­al vk*() func­tions.

Both ap­proaches can co­ex­ist, just be sure that you call in­stance-/device-spe­cif­ic func­tions on the in­stance/device that they were quer­ied from and everything will work well.

~ ~ ~

And that’s it! Check Vulkan sup­port in flex­t­GL out and please re­port bugs, if you find any. Thanks for read­ing, I’ll be back soon!