Khronos Vulkan

Getting Started with the Windows 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 Vulkan 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 (Intel/AMD CPU's)

Vulkan development using the Vulkan SDK requires a Windows development system to meet specific hardware and software requirements. These specifications are as follows:

In addition, to build the demos, one must install the following programs:

System Requirements (Windows ARM64)

Vulkan development using the Vulkan SDK requires a Windows development system to meet specific hardware and software requirements. These specifications are as follows:

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. The Vulkan Loader is delivered with your driver update package.
  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".

Download the SDK

Download the Vulkan SDK. The SDK download file is named VulkanSDK-version-Installer.exe on the SDK download page. Make note of the directory to which the file was downloaded.

Install the SDK

The Vulkan SDK For Windows is a self-extracting installer. Run the downloaded executable file to install the SDK. The default SDK install location is C:\VulkanSDK\version.

Note: If you have installed one or more newer SDK's (1.2.189.1 or newer), and you wish to install an older SDK prior to 1.2.189.1, you must uninstall the most recently installed SDK first. To uninstall the most recently installed SDK, use the Windows "Add and remove programs feature", or the maintenancetool.exe in the SDK install directory.

Installing the Vulkan SDK sets the system environment variable VULKAN_SDK to the directory in which the SDK is installed, which will look like C:\VulkanSDK\1.0.0.0, but with the version number being the version that was installed. Installing the Vulkan SDK also prepends the expansion of %VULKAN_SDK%\Bin to the system PATH environment variable. The system environment variable VK_SDK_PATH is set to the same value as VULKAN_SDK for compatibility with prior releases.

Note: The programs and command shells that were running during installation may not see the updated environment variables until they are restarted.

Unattended Installation

By default, the SDK installer will bring up a window to guide you through the installation of the core and optional components. This may be problematic for anyone wishing to install the SDK through an automated mechanism. For SDK versions 1.2.189.1 and newer the installer and the maintenance tool have a number of command line options that replaces the old /S command line option to install the SDK silently. The SDK can install multiple optional components, and these can be added and removed individually at any time. The installer uses the Qt installer framework and this supplies a number of useful command line options, but only those shown here are tested and supported by LunarG for the Vulkan SDK.

For completely unattended installation and modifications, the command prompt must be run as administrator. There is an option to only copy the SDK files and not perform any operations to the registry such as setting up new layers, creating shortcuts, and adjustments to the system path. For the copy only option, append copy_only=1 to the end of the command line installer executable.

Basic Default Installation

To reproduce the default behavior of the old /S option, which installs the core Vulkan SDK components (but not the 32-bit components) silently in the default location (C:\VulkanSDK\1.2.X.Y based on the version number), without any user intervention (for these examples we will assume 1.2.182.1 for the SDK version):

VulkanSDK-1.2.182.1-Installer.exe --accept-licenses --default-answer --confirm-command install

Changing The Destination

The destination of the Vulkan SDK can be changed with the --root . If the folder does not exist, it will be created. For example:

VulkanSDK-1.2.182.1-Installer.exe --root D:\SDKs\Vulkan-1.2.182.1 --accept-licenses --default-answer --confirm-command install

Installing Optional Components

The VulkanSDK installer can now automatically download optional components from the cloud and install them as part of the SDK installation (an Internet connection is required for this). Append these component names to the above command and the installer will retrieve the components and install them along with the core SDK. These modules are listed below:

Optional Component Name Description
com.lunarg.vulkan.32bit *Optional 32-bit SDK components
com.lunarg.vulkan.sdl2 SDL2(both 32/64-bit) library
com.lunarg.vulkan.glm GLM (3D Math Library) headers
com.lunarg.vulkan.volk Volk (Vulkan Meta Loader) library
com.lunarg.vulkan.vma Vulkan Memory Allocator library
com.lunarg.vulkan.debug Debuggable shader API libraries
com.lunarg.vulkan.debug32 *32-bit debuggable shader API libraries

'*' These items are not available in the Windows ARM version of the Vulkan SDK

For example to install all optional components silently in the default location:

VulkanSDK-1.2.182.1-Installer.exe --accept-licenses --default-answer --confirm-command install com.lunarg.vulkan.32bit com.lunarg.vulkan.sdl2 com.lunarg.vulkan.glm com.lunarg.vulkan.volk com.lunarg.vulkan.vma com.lunarg.vulkan.debug com.lunarg.vulkan.debug32

Listing Components Programmatically

A list of already installed components can be found using the list command to the maintenance tool:

maintenancetool.exe list

In addition, if the online repository of optional components is available, a list of all available components can be displayed by running the installer with just the search command. For example:

VulkanSDK-1.2.182.1-Installer.exe search

Vulkan SDK contents

The Vulkan SDK provides the development and runtime components to create, capture, and replay Vulkan applications. The SDK also includes the runtime components to load and run Vulkan Layers. The SDK installation process installs contents as described in the table below. Paths are relative to the directory in which the SDK is installed.

Directory Description
Bin 64-bit binaries of executables including layers and JSON manifest files that belong in the system path
Bin32 32-bit binaries of executables including layers and JSON manifest files that belong in the system path (not available for ARM64 SDK)
cmake Sample layers settings file and Vulkan Profiles settings files
Config CMake files for SDL2 library usage
Helpers Helper programs used by the Vulkan SDK installer and maintenance tool. Do not remove these files
Demos Source and Visual Studio project files for the Vulkan Cube and Vulkan Info programs (not available for ARM64 SDK)
Include Header files required to compile Vulkan applications
Lib 64-bit libraries for layers and tools
Lib32 32-bit libraries for layers and tools (not available for ARM64 SDK)
share Home of the vk.xml file
Source Any source code files such as spirv_reflect.c
Templates Visual Studio Vulkan project templates

Run with Alternate SDK****

When you install multiple SDKs, the PATH environment variable is set to point to the SDK that was most recently installed. The HKLM registry, likewise, is set up to point to the most recently installed SDK. This is a departure from behavior from SDK releases prior to 1.2.189.1.

Verify the SDK Installation

Verify the installation of the Vulkan SDK by running:

C:\> vkvia

`C:\> vulkaninfoSDK

`C:\> 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] (not available for ARM64 SDK) (#vulkan-api-capture-and-replay-with-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 application's 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.

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 semi-colon-separated list of layer or extension names, as found in the Vulkan SDK Layers list or within the manifest files.

C:\> set 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 (not available for ARM64 SDK)

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.

Start Vulkan Programming

Build the Demo Programs (Demos not included in ARM64 SDK)

The Vulkan SDK includes the source for two demo applications: Vulkan Info and Vulkan Cube. There are two versions of Vulkan Cube: one written in C using vulkan.h and another written in C++ using vulkan.hpp. The vulkan.hpp header file is a low-level C++ API for Vulkan.

The Vulkan demo applications use Visual Studio solution files. To build the demo programs, open the <InstallPath>\Demos\DEMOS.sln file. This will launch Visual Studio, opening the solution with a default build configuration of Debug/Win32. Select the desired build configuration (i.e., Debug/x64). Building the solution will build all of the demo applications. If you are using a newer version of Visual Studio, you will be prompted to update the project files. Doing so should not present any issue.

Create a New Visual Studio Project

The Vulkan SDK includes Visual Studio templates so a programmer can easily create a Vulkan project without setting up include paths and libraries. The templates are located in SDK install directory, in a subdirectory called "Templates." In order to make these templates appear in Visual Studio they must be copied into the directory where Visual Studio searches for C++ templates. By default this is located at:

C:\Users\username\Documents\Visual Studio YYYY\Templates\ProjectTemplates\Visual C++ Project

The Vulkan SDK includes separate templates for Visual Studio 2019 and 2022. The templates can be enabled by copying the zip files from the SDK template directory into the Visual Studio path given above. You may have to create one or more directories in the path given above.

Note: It is possible to point Visual Studio at the templates in the SDK without any copying but doing so means that any additional templates would have to be put into the Vulkan SDK installation. As a result, copying the files is the recommended approach.

Note: The included templates require the Windows 10 (26624 or later) SDK to be installed with the version of Visual Studio you are using. If the Windows 10 SDK is not installed, you will still be able to use the templates, but any projects created through the templates will need to be retargeted to an installed Windows SDK before they can be built.

Once you have copied the templates you can now create a new project or solution from these templates. Open the project creation dialog by going to File -> New -> Project... Then locate the list of Visual C++ templates. (The exact location of the list depends on your version of Visual Studio but should be easy to find in the New Project dialog.) You should see a list of the built-in templates and at the bottom should be the Vulkan templates. The included templates are described below:

Name Description
Vulkan Program A simple Vulkan program with no dependencies, except the Vulkan loader and the Khronos Validation layer. This program creates and then destroys a simple Vulkan instance using the C Vulkan API.
Vulkan Windowed Program A Vulkan program that depends upon SDL and GLM. This program creates a blank window, initializes a Vulkan surface on that window, and then waits for the user to close the window. This template uses the C Vulkan API.
Vulkan C++ Program A simple Vulkan program with no dependencies, except the Vulkan Loader and the Khronos Validation layer. This program creates and then destroys a simple Vulkan instance using the C++ Vulkan API.
Vulkan C++ Windowed Program A Vulkan program that depends on SDL and GLM. This program creates a blank window, initializes a Vulkan surface on that window, and then waits for the user to close the window. This template uses the C++ Vulkan API.

Choose "Vulkan Windowed Program", enter a name for your project, and click OK. You should see a new solution and project open in Visual Studio. Build and run the project. When you run the project you should see a blank window pop up and when you close the window the program should exit with code 0. Now, change the configuration to x64, build, and run the project again. You should see the same results but now with a 64-bit build.

You should take some time to examine the source code in this project. The project enables the Khronos Validation layer if the project is built in a debug mode. This project is creating a Vulkan surface on the window but does not render anything to the screen.

You now have a working Vulkan project. Feel free to use this as a base for larger projects.

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.