vk-bootstrap

vk-bootstrap uses a builder pattern to construct Vulkan objects. You configure the desired settings using various set_* methods and then call .build() to finalize the creation. The result is typically returned as a vkb::Result<T>, which you must check for errors before accessing the underlying wrapper or Vulkan handle.

vkb::Result<vkb::Wrapper> result = vkb::WrapperBuilder()
                                            .set_thing()
                                            .more_things()
                                            .build();

if (!result) { /* handle error */ }

// The result also holds the vk-bootstrap wrapper
vkb::Wrapper wrapper = result.value();

// The underlying Vulkan handle can easily be acquired
VkObject object = wrapper.object;

While vk-bootstrap automatically enables the necessary windowing extensions during VkInstance creation, it does not create the VkSurfaceKHR handle itself, as this is the responsibility of your windowing library. You must use your library's specific functions (like glfwCreateWindowSurface or SDL_Vulkan_CreateSurface) after creating the vkb::Instance.

If your application needs to present but cannot create a VkSurfaceKHR handle before physical device selection, call defer_surface_initialization() on your instance builder to prevent the no_surface_provided error.

// GLFW
VkResult err = glfwCreateWindowSurface (vkb_instance.instance, window, NULL, &surface);
if (err != VK_SUCCESS) { /* handle error */ }

// SDL2
SDL_bool err = SDL_Vulkan_CreateSurface(window, vkb_instance.instance, &surface);
if (!err){ /* handle error */ }

To build the library standalone using CMake:

git clone https://github.com/charles-lunarg/vk-bootstrap
cd vk-bootstrap
mkdir build
cd build
cmake ..

To properly shut down your application, destroy resources in the reverse order of their creation. Use the following vkb utility functions:

1. vkb::destroy_swapchain(swapchain)
2. vkb::destroy_device(device)
3. vkb::destroy_surface(instance, surface)
4. vkb::destroy_instance(instance)

vkb::Instance instance;
VkSurfaceKHR surface;
vkb::Device device;
vkb::Swapchain swapchain;

// ... renderer logic ...

vkb::destroy_swapchain(swapchain);
vkb::destroy_device(device);
vkb::destroy_surface(instance, surface);
vkb::destroy_instance(instance);

Add the repository as a git submodule and use add_subdirectory in your CMake configuration.

1. Add the submodule:

git submodule add https://github.com/charles-lunarg/vk-bootstrap

2. Configure CMake:

add_subdirectory(vk-bootstrap)
target_link_libraries(your_application_name vk-bootstrap::vk-bootstrap)

For a simple integration, copy the following files directly into your project and include them in your build process. Note that vk-bootstrap is not a header-only library.

Required files:

• src/VkBootstrap.h
• src/VkBootstrapDispatch.h
• src/VkBootstrap.cpp

Linux Specific Requirement: On Unix platforms, the library loads symbols at runtime. You must link against the system dynamic linker. If using CMake, link with ${CMAKE_DL_LIBS}.

For fine-grained control, you can provide a list of vkb::CustomQueueDescription objects to the device builder. You can obtain queue family information from the vkb::PhysicalDevice using get_queue_families().

std::vector<vkb::CustomQueueDescription> queue_descriptions;
auto queue_families = phys_device.get_queue_families ();
for (uint32_t i = 0; i < static_cast<uint32_t>(queue_families.size ()); i++) {
    if (queue_families[i].queueFlags & VK_QUEUE_GRAPHICS_BIT) {
        // Find the first queue family with graphics operations supported
        queue_descriptions.push_back (vkb::CustomQueueDescription (
            i, std::vector<float> (queue_families[i].queueCount, 1.0f)));
    }
}
// These descriptions would then be used in the DeviceBuilder

If using CMake 3.12 or higher, you can use FetchContent to automatically download and build the library.

include(FetchContent)
FetchContent_Declare(
    fetch_vk_bootstrap
    GIT_REPOSITORY https://github.com/charles-lunarg/vk-bootstrap
    GIT_TAG        BRANCH_OR_TAG # Use a specific tag to ensure stability
)
FetchContent_MakeAvailable(fetch_vk_bootstrap)
target_link_libraries(your_application_name vk-bootstrap::vk-bootstrap)

include(FetchContent)
FetchContent_Declare(
    fetch_vk_bootstrap
    GIT_REPOSITORY https://github.com/charles-lunarg/vk-bootstrap
    GIT_TAG        BRANCH_OR_TAG #suggest using a tag so the library doesn't update whenever new commits are pushed to a branch
)
FetchContent_MakeAvailable(fetch_vk_bootstrap)
target_link_libraries(your_application_name vk-bootstrap::vk-bootstrap)

By default, calling .use_default_debug_messenger() on the InstanceBuilder provides a standard callback. To control how validation layer messages are logged (e.g., to redirect to a file or a custom UI), use .set_debug_callback() with a lambda or function matching the Vulkan debug callback signature.

instance_builder.set_debug_callback ( 
    [] (VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity, 
        VkDebugUtilsMessageTypeFlagsEXT messageType, 
        const VkDebugUtilsMessengerCallbackDataEXT* pCallbackData, 
        void *pUserData) 
        -> VkBool32 { 
            auto severity = vkb::to_string_message_severity(messageSeverity);
            auto type = vkb::to_string_message_type(messageType);
            printf ("[%s: %s] %s\n", severity, type, pCallbackData->pMessage);
            return VK_FALSE;
        }
    );