Getting Started with the Windows Vulkan SDK
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:
- Vulkan API usage validation thanks to the Khronos Validation layer.
- Vulkan Layers configuration thanks to Vulkan Configurator.
- SPIR-V Shader compilation, optimization and validation thanks to DXC, SPIR-V Tools and SPIR-V Cross.
- Vulkan API capture and replay for Vulkan debugging thanks to GFXReconstruct.
- Vulkan Capabilities Viewer. The new and perfered way to identify your devices capabilities, and contribute to an open source database of GPU capabilities.
- Vulkan system report thanks to Vulkan Installation Analyzer (VIA), Vulkan Hardware Capability Viewer, and Vulkan Info.
- Note: The Vulkan Installation Analyzer may be deprecated at some point in the future. The Vulkan loader debugging output has been expanded to replace this tool.
- Vulkan demos code.
- Third-party libraries and tools such as GLM, SDL, Volk, and VMA.
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
Vulkan development using the Vulkan SDK requires a Windows development system to meet specific hardware and software requirements. These specifications are as follows:
- Windows 10 64-bit OS
- Note: 32-bit and 64-bit versions of layers and libraries are delivered
- Note: only 64-bit versions of SDL2
.cmakefiles are delivered
- Vulkan Installable Client Driver (ICD) from your GPU hardware vendor; the Vulkan Loader is delivered with the vendor's driver package
- 8 GB memory
- Sufficient free disk space to install the Vulkan SDK (approximately 1 GB)
In addition, to build the demos, one must install the following programs:
- CMake 3.10.2 is recommended
- Python 3.0 or newer
- Visual Studio 2019 or later
- Note: All Windows Vulkan SDK binaries are built with Visual Studio 2019, and are compatible across Visual Studio 2019 and later.
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:
- "v" is the Vulkan major version
- "w" is the Vulkan minor version
- "xx" is the Vulkan patch version (e.g., 24)
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.
- 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. - For each physical device, there is an
apiVersion. TheapiVersionis the version of your Vulkan driver. You can find theapiVersionfor each physical device from yourvulkaninfooutput 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.
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
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 |
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 (Note: This folder is not present on 32-bit Windows installs) |
Bin32 |
32-bit binaries of executables including layers and JSON manifest files that belong in the system path |
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 |
Include |
Header files required to compile Vulkan applications |
Lib |
64-bit libraries for layers and tools |
Lib32 |
32-bit libraries for layers and tools |
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:
- Vulkan Installation Analyzer (VIA) with the command:
C:\> vkvia
- Vulkan Info with the command:
`C:\> vulkaninfoSDK
- Vulkan Cube with the command:
`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. |
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 |
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
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
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.