Home

Awesome

Vulkan Launchpad :rocket:

A framework by TU Wien targeted at Vulkan beginners. It abstracts some of the hard and overly verbose parts of the Vulkan C API and can help to boost your learning progress early on.

Sections:

Setup Instructions

Vulkan Launchpad runs on Windows, macOS, and Linux. For building you'll need Git, the Vulkan SDK, a C++ compiler, CMake, and optimally an integrated development environment (IDE). In the following, we describe setup instructions for common operating systems and editors/IDEs (click the links in the table of contents to jump to the sections that are relevant to your chosen setup):

Starter Template:
For a quick project setup of an executable that links Vulkan Launchpad, we provide a starter template at github.com/cg-tuwien/VulkanLaunchpadStarter.

Operating Systems

Windows

macOS

Linux

Requirements: C++ Compiler, Git, CMake, Vulkan SDK, X.Org and Vulkan compatible driver.

In case you want to use Ninja or other development tools please install them separately. The instructions below are the minimum dependencies to build Vulkan Launchpad.

Ubuntu and Linux Mint

# Jammy Jellyfish (Ubuntu 22.04/22.10 and Linux Mint 21.0/21.1)
# Add LunarG public key
wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
# Add Vulkan package
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-jammy.list http://packages.lunarg.com/vulkan/lunarg-vulkan-jammy.list
# Focal Fossa (Ubuntu 20.04/20.10 and Linux Mint 20.0/20.1/20.2/20.3)
# Add LunarG public key
wget -qO - http://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo apt-key add -
# Add Vulkan package
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-focal.list http://packages.lunarg.com/vulkan/lunarg-vulkan-focal.list

# Update package manager
sudo apt update
# Install dependencies
sudo apt install git cmake build-essential xorg-dev libvulkan-dev vulkan-headers vulkan-validationlayers

Fedora Workstation

sudo dnf install cmake gcc-c++ libXinerama-devel vulkan-loader-devel vulkan-headers vulkan-validation-layers-devel
sudo dnf -y groupinstall "X Software Development"

Manjaro

sudo pacman -Sy cmake base-devel vulkan-validation-layers

Editors and IDEs

Visual Studio Code (VS Code)

Visual Studio 2022 Community

Xcode

Other IDEs

Other IDEs (such as CLion or Qt Creator) are usable too as long as they support CMake. Please consider the following remarks for the setup process:

Troubleshooting

Submodule Updates Take a Long Time

In case you experience problems concerning the submodule checkout, i.e. the cloning of the submodules (GLFW, GLM or glslang) takes a long time or seems to be stuck, please try the following approach:

On macOS: CMake cannot find C/CXX compiler

In case you had an existing XCode Command Line Tools installation, this error may occur during cmake generation. You can try: bash xcode-select --reset

On macOS: CMake cannot find Vulkan

This may be the case, if you forgot to select System Global Installation during the Vulkan SDK installation, leading to errors during cmake generation, as the location of the Vulkan libraries cannot be found. You can install it retroactively by executing the MaintenanceTool.app in the VulkanSDK folder and selecting System Global Installation as a component to add.

Documentation

Documentation sections:

Structure

Naming Conventions

The following naming conventions are used by Vulkan Launchpad:

Functionality

Initialization and Destruction

Vulkan Launchpad needs to be initialized by calling vklInitFramework.
Subsequently, it needs to be destroyed via vklDestroyFramework.

Consistent with the Vulkan API, custom configuration structs should best be zero-initialized, although they do not require to expilictly set their instance's type:

VklSwapchainConfig swapchain_config = {};

Extensions

Required extensions can be queried by vklGetRequiredInstanceExtensions.

Note: GLFW will require further extensions. These are not included yet in the array that is returned by vklGetRequiredInstanceExtensions.

Render Loop

Vulkan Launchpad provides functionality needed during a typical render loop:

    vklWaitForNextSwapchainImage();
    vklStartRecordingCommands();
		
    // Your commands here

    vklEndRecordingCommands();
    vklPresentCurrentSwapchainImage();

Graphics Pipelines

For testing purposes, Vulkan Launchpad will automatically create a basic pipeline, which takes only vertex positions, maps them to their locations in world space without any transformation or projection, and colours them red. This pipeline can be retrieved using vklGetBasicPipeline.

For creating custom pipelines, the following functionality is provided:

To bind a single VkDescriptorSet to a VkPipelineLayout, the framework offers a convenience function vklBindDescriptorSetToPipeline, which will take a VkDescriptorSet and a VkPipeline.

Buffers

Vulkan Launchpad can help with buffer management in different memory types, and provides some utility functions for transfering data into a buffer.

The memory types are reflected in function naming:

The appropriate destruction functions are the following:

Utility functions:

Images

Vulkan Launchpad provides some utility functions for images as well:

Resource Loading (3D Models, Textures)

For loading 3D Models, Vulkan Launchpad provides the following utility functions:

For loading DDS images, Vulkan Launchpad provides the following utility functions:

Logging and Error Checking

The following macros are defined for logging purposes:

Additionally, Vulkan Launchpad offers several possibilities to process a VkResult, which is returned by many Vulkan operations:

Camera

The following functions are provided for creating and using an orbit/arcball-style camera:

Example of intended/correct usage:

GLFWwindow* window = glfwCreateWindow(...);
VklCameraHandle camera = vklCreateCamera(window);
// ...
while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    vklUpdateCamera(camera);
    glm::mat4 view_proj_matrix = vklGetCameraViewProjectionMatrix(camera);
    // ...
}
vklDestroyCamera(camera);

Vulkan Memory Allocator (VMA)

Vulkan Launchpad provides support for VMA. To enable it, you'll have to ensure that Vulkan Launchpad can find its header, namely <vma/vk_mem_alloc.h>, which can be accomplished by:

After installing it and rebuilding Vulkan Launchpad, you should see an additional vklInitFramework overload, which accepts a VmaAllocator-type parameter (as its last parameter).
Create a VmaAllocator, e.g., like follows:

VmaAllocatorCreateInfo vma_allocator_create_info = {};
vma_allocator_create_info.instance = // TODO: Assign instance handle
vma_allocator_create_info.physicalDevice = // TODO: Assign physical device handle
vma_allocator_create_info.device = // TODO: Assign device handle
VmaAllocator vma_allocator;
VkResult result = vmaCreateAllocator(&vma_allocator_create_info, &vma_allocator);

and pass it to vklInitFramework to let Vulkan Launchpad do all internal memory allocations via VMA henceforth.

Further information about VMA can be found in VMA's documentation.

Pipeline Hot-Reloading

Pipeline hot-reloading (also known as "shader hot-reloading") is a feature which can be very handy especially during shader development. It allows to reload existing graphics pipelines (referred to through VkPipeline handles) during application runtime, without the need to restart the application. Pipeline hot-reloading in Vulkan Launchpad can be configured to be triggered through a keyboard shortcut, such as F5 or Ctrl+R.

To enable pipeline hot-reloading in code:

Note: The call to vklEnablePipelineHotReloading is optional. Pipeline hot-reloading can also be triggered manually through vklHotReloadPipelines.