vk-bootstrap/README.md

vk-bootstrap

A utility library meant to jump start developing a Vulkan Application

This library simplifies the tedious process of:

• Instance creation
• Physical Device selection
• Device creation
• Getting queues
• Swapchain creation

It also adds several conveniences for:

• Enabling validation layers
• Adding a debug callback messenger
• Enabling extensions on a physical device
• Select a gpu based on a set of criteria like features, extensions, memory, etc

Read the Getting Started guide for a quick start on using vk-bootstrap

Basic Usage

#include "VkBootstrap.h"

void init_vulkan () {
    vkb::InstanceBuilder builder;
    auto inst_ret = builder.set_app_name ("Example Vulkan Application")
                        .request_validation_layers ()
                        .use_default_debug_messenger ()
                        .build ();
    if (!inst_ret) {
        printf("Failed to create Vulkan instance. Cause %s\n", 
            instance_builder_return.error().message());
        return;
    }
    vkb::Instance vkb_inst = inst_ret.value ();

    vkb::PhysicalDeviceSelector selector{ vkb_inst };
    auto phys_ret = selector.set_surface (/* from user created window*/)
                        .set_minimum_version (1, 1) // require a vulkan 1.1 capable device
                        .require_dedicated_transfer_queue ()
                        .select ();
    if (!phys_ret) {
        printf("Failed to select Vulkan Physical Device. Cause %s\n", 
            phys_ret.error().message());
        return;
    }

    vkb::DeviceBuilder device_builder{ phys_ret.value () };
    // automatically propagate needed data from instance & physical device
    auto dev_ret = device_builder.build ();
    if (!dev_ret) {
        printf("Failed to create Vulkan device. Cause %s\n", 
            dev_ret.error().message());
        return;
    }
    vkb::Device vkb_device = dev_ret.value ();

    // Get the VkDevice handle used in the rest of a vulkan application
    VkDevice device = vkb_device.device;

    // Get the graphics queue with a helper function
    auto graphics_queue_ret = vkb_device.get_queue (vkb::QueueType::graphics);
    if (!graphics_queue_ret) {
        printf("Failed to get graphics queue. Cause %s\n", 
            graphics_queue_ret.error().message());
        return;
    }
    VkQueue graphics_queue = graphics_queue_ret.value ();

    // Turned 400-500 lines of boilerplate into less than fifty.
}

See example/triangle.cpp for an example that renders a triangle to the screen.

Setting up vk-bootstrap

Simple

This library has no external dependencies beyond C++11 and the standard library.

Simply copy the src/VkBootstrap.h and src/VkBootstrap.cpp files into your project, include them, compile as you normally would.

With git-submodule + CMake

Add this project as a git-submodule

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

With CMake, add the project as a subdirectory

add_subdirectory(vk-bootstrap)

target_link_libraries(your_application_name vk-bootstrap)

Manually Building

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

Testing

Testing requires GLFW and Catch2 but are acquired automatically using cmake. Tests will be enabled if you open this project standalone. If you include this project as a subdirectory, you can force enable tests by setting the option VK_BOOTSTRAP_TEST to ON, otherwise it won't be built.

cmake ../path/to/your_project/ -DVK_BOOTSTRAP_TEST=ON