Khronos Vulkan

Getting Started with the Ubuntu Vulkan SDK

Creative Commons

Vulkan SDK Introduction

This guide describes the content, the requirements and procedure for getting started with the Vulkan SDK.

The Khronos Vulkan API is an explicit, low-overhead, cross-platform graphics and compute API. Vulkan provides applications with control over the system execution and the system memory to maximize application efficiency on a wide variety of devices from PCs and consoles to mobile phones and embedded platforms.

The Vulkan SDK enables developers to develop Vulkan applications. It includes:

All documentation for the SDK can be found and downloaded online at vulkan.lunarg.com.

Important: This SDK does not install Vulkan drivers!! It only provides tools and libraries for application development and debugging. If you are looking for drivers, please refer to your system GPU vendor's website.

Looking for Validation Layer Binaries for Android?

With each SDK release, a release of the Khronos Validation Layer binaries for Android are released on the Validation layer Repository. The Android binaries are not included in this SDK.

Terminology

Term Description
DXC Microsoft's Open Source DirectX Shader Compiler
ICD Installable Client Driver: A Vulkan compatible display driver
GLSL OpenGL Shading Language
HLSL DirectX High-Level Shading Language
SPIR-V Standard Portable Intermediate Representation is a cross-API intermediate language (IL) that natively represents parallel compute and graphics programs
VMA The Vulkan Memory Allocator library provided by AMD.
Vulkan Instance The Vulkan API object that stores all per-application states
Vulkan Layer A library designed to work as a plug-in for the loader. It usually serves to provide validation and debugging functionality to applications
Vulkan Loader A library which implements the Vulkan API entry points and manages layers, extensions, and drivers. It is found in the independent hardware vendor driver installs

System Requirements

Your Ubuntu development and host systems must meet specific hardware and software requirements to install the Vulkan SDK and create Vulkan applications. You will need a Vulkan ICD to execute Vulkan applications.

The Vulkan SDK supports versions 22.04 (64-bit) and 24.04 (64-bit) of Ubuntu.

Administrator privileges are required to install the SDK.

For other distributions of Linux, we recommend you search your distribution's package repository for Vulkan development libraries. Otherwise you may download and build from publicly available repositories.

You will find instructions to build all of the above in their respective repositories.

Use the Vulkan SDK

SDK Versioning

The components in this SDK are built with a specific version of Khronos Vulkan API header, whose version is reflected in the SDK's version number. For example, SDK version v.w.xx.0 indicates the SDK uses the Vulkan header revision where:

The last number in the SDK version indicates the revision of an SDK for the given Vulkan header revision. It is used in case it is necessary to release multiple SDKs for the same version of Vulkan.

For example, SDK version 1.1.70.0 indicates the SDK uses Vulkan header revision 1.1.70.

Note: A more recent SDK version number does not indicate an application cannot be developed for earlier Vulkan versions. As well, an older SDK version can not be used to develop applications for a newer version of Vulkan. For example, the 1.1.130.0 SDK can be used to develop Vulkan 1.0 applications but cannot be used to develop applications for Vulkan 1.2. Furthermore, the presence of a 1.2.xx SDK does not necessarily indicate a system can actually run Vulkan 1.2. A Vulkan 1.2 driver is required for applications to use most Vulkan 1.2 functionality.

Once you have installed a Vulkan driver on your system, there is a version for your Vulkan Loader, and a version for each physical device.

  1. Vulkan Instance Version. This is the version of your Vulkan Loader. If you run vulkaninfo, the Vulkan Instance Version is the first item reported.

  2. For each physical device, there is an apiVersion. The apiVersion is the version of your Vulkan driver. You can find the apiVersion for each physical device from your vulkaninfo output under the section labeled "Device Properties and Extensions".

Install the SDK

Before you begin, always make sure you system is up to date prior to installing any package.

Please follow the instructions below that corresponds to your Ubuntu version:

Ubuntu 24.04 (Noble Numbat)

wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-noble.list http://packages.lunarg.com/vulkan/lunarg-vulkan-noble.list
sudo apt update
sudo apt install vulkan-sdk

Ubuntu 22.04 (Jammy Jellyfish)

wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-jammy.list http://packages.lunarg.com/vulkan/lunarg-vulkan-jammy.list
sudo apt update
sudo apt install vulkan-sdk

If you need a specific version of the Ubuntu SDK, the installation instructions are at the Vulkan SDK Download Site. Once there, you may install the packages by performing the following:

System Locations

If you have installed a Vulkan driver from a GPU vendor, you may wish to verify there is a JSON file installed in one of the following locations:

Directory Description
/etc/vulkan/icd.d/ or /usr/share/vulkan/icd.d Vulkan driver JSON manifest file, which is not modified by the SDK installer.

Refer to the Vulkan Loader guide, Linux section, for detailed information on ICD and layer library search paths and order for this platform.

Uninstalling the SDK

To remove the packages that are installed from LunarG's vulkan-sdk package:

sudo apt purge vulkan-sdk
sudo apt autoremove

To remove LunarG's repository, remove the ".list" file that is in the /etc/apt/source.list.d/ directory. For example:

```shell
sudo rm /etc/apt/sources.list.d/lunarg-vulkan-jammy.list
sudo apt update
```

Note: this will not uninstall the vulkan loader (libvulkan1) since it is dependent on various other packages and uninstalling could leave you machine in an unusable state. The loader can be reverted to a previous version with sudo apt install libvulkan1=<version> where "" is replaced with what is available on the system which can be listed with apt-cache madison libvulkan1.

Verify the SDK Installation

Verify the installation of the Vulkan SDK by running:

~$ vkvia

`~$ vulkaninfo

`~$ vkcube

Vulkan SDK Layers

Vulkan Layers aim at helping Vulkan developers building Vulkan applications by providing Vulkan API usage validation and Vulkan debugging tools.

A Vulkan Layer can intercept all or any subset of Vulkan API entry points. Multiple layers can be chained together to cascade their functionality in the appearance of a single, larger layer.

Vulkan SDK Layers list

The Vulkan SDK includes the following layers:

Layer Name Description
VK_LAYER_KHRONOS_validation Vulkan API validation and error checking.
VK_LAYER_LUNARG_gfxreconstruct Capturing application Vulkan commands for GFXReconstruct.
VK_LAYER_LUNARG_api_dump Print API calls and their parameters and values.
VK_LAYER_KHRONOS_profiles Helps test across a wide range of hardware capabilities without physical access to every device.
VK_LAYER_LUNARG_monitor Outputs the frames-per-second of the target application in the applications title bar.
VK_LAYER_LUNARG_screenshot Outputs specified frames to an image file as they are presented.
VK_LAYER_KHRONOS_synchronization2 Implements the VK_KHR_synchronization2 extension, for use on systems without a driver that implements it.
VK_LAYER_KHRONOS_shader_object Implements the VK_EXT_shader_objectVK_EXT_shader_object extension, for use on systems without a driver that implements it.
VK_LAYER_LUNARG_crash_diagnostic The Crash Diagnostic Layer (CDL) is a Vulkan layer to help track down and identify the cause of GPU hangs and crashes.

Use Vulkan Layers

Vulkan Configurator

Vulkan Configurator is a GUI application designed to make Vulkan Layers features and settings more accessible and intuitive to use, and to improve development iteration time.

A Vulkan application may configure layers when creating a Vulkan Instance. This layers configuration may be overridden using Vulkan Configurator globally or for a selected list of Vulkan applications.

Finally Vulkan Configurator allows using Vulkan Layers from user-defined directories.

Main window Layers window
Main window Layers window

Note: This is the recommended approach to use or override Vulkan Layers.

VK_INSTANCE_LAYERS environment variable

The Vulkan Layers can be enabled by setting the VK_INSTANCE_LAYERS environment variable to a colon-separated list of layer names, as found in the Vulkan SDK Layers list or within the manifest files.

$ export VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation:VK_LAYER_LUNARG_gfxreconstruct

Debug Vulkan applications

Vulkan API Validation with Khronos Validation layer

By design, minimal error checking is done inside a Vulkan driver to avoid API overhead. Applications have full control and responsibility for correct operation. Any errors in how Vulkan is used can result in a crash. The Khronos Validation layer VK_LAYER_KHRONOS_validation can be enabled to assist development by enabling developers to verify their applications' correct use of the Vulkan API.

Vulkan API Capture and Replay with GFXReconstruct

The GFXReconstruct project provides tools for the capture and replay of Vulkan API calls. The VK_LAYER_LUNARG_gfxreconstruct layer allows recording to a file the graphics commands executed by a Vulkan application that may later be replayed with gfxrecon-replay to reconstruct the graphics-specific behavior of the captured application.

Debug a Vulkan application with gdb

The Vulkan SDK includes debug libraries and source code for the loader and layer providing a rudimentary gdb debug environment for Vulkan applications. Note: The code shown in the sample debugger session below may not exactly match the code you see in your session.

Follow these steps to debug the Vulkan Cube example application.

First be sure to install the Debian package development tools

sudo apt install dpkg-dev

Install the debugging symbols for the Vulkan loader and tools.

sudo apt install libvulkan1-dbgsym vulkan-tools-dbgsym

Install the source for the Vulkan Loader and vulkan-tools. The following command will download to your current directory.

apt source vulkan-loader vulkan-tools

Start the debugger, specifying the source directories:

# vulkan-loader-<version> is the source package for libvulkan1.
gdb -d vulkan-loader-<version>/loader -d vulkan-tools_<version>/cube vkcube

Set a breakpoint at the vkCreateDevice() function and begin execution. The debugger stops at the breakpoint in the loader.

Note: gdb may display a message saying the breakpoint needs to be deferred because it is being set in a shared library that is not yet loaded. If such a prompt appears, respond "y" to continue.

(gdb) b vkCreateDevice
Breakpoint 1 at 0x402940
(gdb) r
Starting program: /usr/bin/vkcube
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1, vkCreateDevice (physicalDevice=0x647520, pCreateInfo=pCreateInfo@entry=0x7fffffffd5f0,
    pAllocator=pAllocator@entry=0x0, pDevice=pDevice@entry=0x7fffffffd7f8)
    at /build/vulkan-loader-1.1.97.0~rc1/loader/trampoline.c:754
754                                                             const VkAllocationCallbacks *pAllocator, VkDevice *pDevice) {

Examine the backtrace and source.

(gdb) bt
#0  vkCreateDevice (physicalDevice=0x647520, pCreateInfo=pCreateInfo@entry=0x7fffffffd5f0,
    pAllocator=pAllocator@entry=0x0, pDevice=pDevice@entry=0x7fffffffd7f8)
    at /build/vulkan-loader-1.1.97.0~rc1/loader/trampoline.c:754
#1  0x0000000000403e42 in demo_create_device (demo=0x7fffffffd780)
    at /build/vulkan-tools-1.1.97.0~rc1/cube/cube.c:3324
#2  demo_init_vk_swapchain (demo=0x7fffffffd780) at /build/vulkan-tools-1.1.97.0~rc1/cube/cube.c:3442
#3  main (argc=<optimized out>, argv=<optimized out>)
    at /build/vulkan-tools-1.1.97.0~rc1/cube/cube.c:3943
(gdb) list
749     disp = loader_get_instance_layer_dispatch(physicalDevice);
750     disp->GetPhysicalDeviceMemoryProperties(unwrapped_phys_dev, pMemoryProperties);
751 }
752
753 LOADER_EXPORT VKAPI_ATTR VkResult VKAPI_CALL vkCreateDevice(VkPhysicalDevice physicalDevice, const VkDeviceCreateInfo *pCreateInfo,
754                                                             const VkAllocationCallbacks *pAllocator, VkDevice *pDevice) {
755     VkResult res;
756     struct loader_physical_device_tramp *phys_dev = NULL;
757     struct loader_device *dev = NULL;
758     struct loader_instance *inst = NULL;

This shows you are stopped in the loader at the vkCreateDevice() function.

Finish execution of the current stack frame and return to the caller:

(gdb) finish
Run till exit from #0  vkCreateDevice (physicalDevice=0x647520,
    pCreateInfo=pCreateInfo@entry=0x7fffffffd5f0, pAllocator=pAllocator@entry=0x0,
    pDevice=pDevice@entry=0x7fffffffd7f8)
    at /build/vulkan-loader-1.1.97.0~rc1/loader/trampoline.c:754
demo_create_device (demo=0x7fffffffd780) at /build/vulkan-tools-1.1.97.0~rc1/cube/cube.c:3325
3325            queues[1].queueFamilyIndex = demo->present_queue_family_index;
Value returned is $1 = VK_SUCCESS
(gdb) list
3320            .pEnabledFeatures = NULL,  // If specific features are required, pass them in here
3321        };
3322        if (demo->separate_present_queue) {
3323            queues[1].sType = VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO;
3324            queues[1].pNext = NULL;
3325            queues[1].queueFamilyIndex = demo->present_queue_family_index;
3326            queues[1].queueCount = 1;
3327            queues[1].pQueuePriorities = queue_priorities;
3328            queues[1].flags = 0;
3329            device.queueCreateInfoCount = 2;

This shows the call to vkCreateDevice() was successful, and displays the next few lines of the Vulkan Cube program.

To continue execution:

(gdb) c

Exit the debugger (press CTRL-C to return to the gdb prompt) and enter "q" to quit.

Next Steps

This guide provided an introduction to the main components and tools in the Vulkan SDK. Refer to the Vulkan SDK Download Site for the most up-to-date SDK information, including the complete set of SDK documentation.