Getting Started with the Vulkan SDK
Version for Windows
This guide describes the requirements and procedure for installing the Vulkan SDK for Windows. All documentation for the SDK can be found online at vulkan.lunarg.com, as well as SDK issue tracking and any latest information.
The Vulkan API is a low-overhead, explicit, cross-platform graphics API that provides applications with direct control over the GPU, maximizing application performance. For more information on the Vulkan specification and API, refer to Khronos.org. For tutorial-level information, refer to the Vulkan tutorial at the Vulkan SDK Download Site.
This SDK does NOT include a Vulkan driver. Please contact your GPU hardware vendor for a Vulkan Installable Client Driver (ICD). This SDK will allow you to build Vulkan applications but you will need a Vulkan ICD to execute them.
This SDK does NOT include the Vulkan Loader. The Vulkan Loader is delivered with the GPU hardware vendor's driver package.
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 220.127.116.11 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 18.104.22.168 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. For more information on how to query Vulkan versions programmatically, see the 1.1 samples in the SDK.
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".
|ICD||Installable Client Driver—A Vulkan-compatible display driver|
|GLSL||OpenGL Shading Language|
|Layer||A library designed to work as a plug-in for the loader. It usually serves to provide validation and debugging functionality to applications|
|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|
|SPIR‑V||Standard Portable Intermediate Representation—A cross-API intermediate language that natively represents parallel compute and graphics programs|
|Vulkan||A low-overhead, explicit graphics API developed by the Khronos Group and member companies|
|WSI||Window System Integration|
Vulkan development using the Vulkan SDK requires a Windows development system to meet specific hardware and software requirements. These specifications are as follows:
- Windows 7, 8, 8.1, or 10 (64-bit and 32-bit)
- Note: 64-bit is preferred and better tested
- Graphics card and ICD that support Vulkan. Contact your graphics hardware supplier for information on Vulkan support.
- 8 GB memory
- Sufficient free disk space to install the Vulkan SDK (approximately 1 GB)
In addition, to build the samples and demos, one must install the following programs:
- CMake 3.10.2 is recommended.
- Python 3.0 or newer (samples only)
- Visual Studio 2015, 2017, 2019
- All binaries in the Vulkan SDK are generated using Visual Studio 2015. The runtime libraries and apps compiled by VS 2015 will result in binary compatibility across VS2015, VS2017, and VS2019. See C++ binary compatibility between Visual Studio 2015, 2017, and 2019 for more detail.
Download the SDK
Download the Vulkan SDK from the Vulkan SDK Download Site. The SDK download file is named
-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
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\22.214.171.124, but with the version number being the version that was installed. Installing the Vulkan SDK also prepends the expansion of
%VULKAN_SDK%\Bin32 on 32-bit Windows) 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.
By default, the SDK installer will bring up a window to guide you through the installation. This may be problematic for anyone wishing to install the SDK through an automated mechanism. In order to install the SDK without any prompts, pass the
/S flag to the SDK installer. For example, silently installing an SDK from the command prompt would look like:
The Vulkan SDK provides the development and runtime components to create, trace, and replay Vulkan applications. The SDK also includes the runtime components to load and run Vulkan Application Validation and Debug 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.
||64-bit Release build of executables that belong in the system path (Note: This folder is not present on 32-bit Windows installs)|
||32-bit Release build of executables that belong in the system path|
||Sample layer settings file|
||Source and MS Visual Studio project files for the Vulkan Cube and Vulkan Info programs|
||Header files required to compile Vulkan applications|
||Source files and a Visual Studio project that are necessary to build layers using the Vulkan Layer Factory|
||64-bit libraries for layers and tools (Note: This folder is not present on 32-bit Windows installs)|
||32-bit libraries for layers and tools|
||A collection of Vulkan C++ samples|
||Home of the vk.xml file|
||Visual Studio Vulkan project templates|
||Libraries that are not used by the SDK but which may be useful for developers and which may be required for templates--currently, GLM and SDL are included|
||64-bit binaries for tools that do not belong in the system path. (Note: This folder is not present on 32-bit Windows installs)|
||32-bit binaries for tools that do not belong in the system path|
Set up the Runtime Environment
Be sure you have installed a graphics driver that includes ICD support for Vulkan. Please contact your graphics hardware vendor for the appropriate drivers. The driver package from your graphics hardware vendor also includes the Vulkan Loader which is an essential required piece of the Vulkan Runtime Environment.
Run with Alternate SDK
If more than one version of the SDK is installed on the system, the path to the
Bin directory of the most recently installed SDK version will be referenced first in the
PATH environment variable. To switch between different versions of the SDK simply re-install the SDK version you wish to use; it is not a requirement to remove an SDK before re-installing another.
ICD and Layer Configuration
The Vulkan loader library
vulkan-1.dll, installed by your graphics HW vendor driver package, examines string values in the Windows registry to determine the location of ICD libraries, the location of layer libraries, and which layers are active.
Verify the Installation
Verify the installation of the Vulkan SDK by running a few things:
- Run the Vulkan Installation Analyzer (VIA) to determine if it believes everything can execute properly.
- VIA (executable name
vkvia) can be found as a shortcut under the Start Menu
Start Menu->Vulkan SDK <
- See the VIA page for more information.
- VIA (executable name
- Run a Vulkan application such as Vulkan Info. (See the
vulkaninfowebpage for more information about the Vulkan Info application and how to use it.)
You can also run the Vulkan Cube demo program by selecting the program in
Start Menu->Vulkan SDK <version>.
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++11 using
vulkan.hpp header file is a low-level C++11 API for Vulkan.
The Vulkan demo applications use Microsoft Visual Studio solution files. To build the demo programs, open the
>\Demos\DEMOS.sln file. This will launch Microsoft 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 version of Visual Studio newer than 2015, you will be prompted to update the project files. Doing so should not present any issue.
Trace and Replay
The Vulkan SDK supports tracing and replaying Vulkan applications. Refer to the Vulkan Trace and Replay Tools guide for detailed information on Vulkan trace and replay.
Trace the Vulkan Cube demo program by running the following commands from a command prompt:
cd %VULKAN_SDK%\Bin vktrace -p vkcube.exe -o vkcube_trace.vktrace -a "--c 250"
The program will close on it's own after a few seconds. Do not stop the program by using
ctrl+cas doing so may result in an incomplete trace file. Notice the trace options used in the command above.
-p, --Program <string>: Name of the program to trace
-o, --OutputTrace <string>: Name of the generated trace file—this must have an extension of ".vktrace".
-a, --Arguments <string>: Arguments to pass to the program—in this case we passed the
--c 250arguments to Vulkan Cube, which tells it to exit after 250 frames
The generated trace file,
vkcube_trace.vktrace, is created in the current directory.
Replay the Vulkan Cube trace file you just generated:
vkreplay -o vkcube_trace.vktrace -l 2
Notice the options used in the command above.
-o, --Open <string>: Name of trace file to replay
-l, --NumLoops <uint>: Number of times to replay the trace
-l 2option replays the trace twice.
Enable Validation and Utility Layers
The Vulkan SDK includes runtime support for validation and utility layers. These layers can be enabled for an application run or a trace replay by setting the
VK_INSTANCE_LAYERS environment variable to a semi-colon-separated list of layer or extension names, as found in the layer manifest files. Refer to the Vulkan Validation and Utility Layers document for more information on layer manifest files.
The Vulkan SDK includes the following layers:
|Layer Name||Layer Type||Description|
||utility||print API calls and their parameters and values|
||validation||Main Vulkan validation layer: validates parameter correctness, Vulkan object lifetimes, externally synchronized thread safety, and the core state-tracked Vulkan validation checks|
||utility||allows modification of an actual device's reported features, limits, and capabilities|
||utility||outputs the frames-per-second of the target application in the applications title bar|
||utility||outputs specified frames to an image file as they are presented|
Refer to the Vulkan Validation and Utility Layers documentation for detailed information on layers.
The layers can be enabled either by using the graphical tool, Vulkan Configurator, or by setting environment variables. As an example, this section will show how to enable the API dump layer with Vulkan Configurator. The API dump layer will allow you to examine the Vulkan API calls from an application. More information on Vulkan Configurator can be found here.
- Open the Start Menu, navigate the the Vulkan SDK directory, and click on "Vulkan Configurator".
- Select the "Layer Manager" tab at the top.
- Find the pane labeled "Unset Explicit Layers". One of the layers in that pane should read "LunarG: Api Dump". Select this layer by clicking on it.
- Click the left arrow directly to the left of the "Unset Explicit Layers" pane. The API dump layer should now move to the "Enabled Layers" pane.
- On the pane on the far right, the settings options for API dump should now be visible. Find the option called "Output to File". Set it to true.
- Click the "Save" button at the bottom left of the window, and do not exit the Vulkan Configurator.
Run the Vulkan Cube program from a command prompt:
cd %VULKAN_SDK%\Bin .\vkcube
Stop the program after a few seconds and examine the
vk_apidump.txtfile to see the api dump layer output. This file will be located in the directory you ran the Vulkan Cube program from. The
VK_LAYER_LUNARG_api_dumpdebug layer will print API calls, parameters, and values.
Deactivate the layers you just enabled from Vulkan Configurator by clicking the "Clear" button at the bottom of the window.
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 201x\Templates\ProjectTemplates\Visual C++ Project
The Vulkan SDK includes separate templates for Visual Studio 2015, 2017, and 2019. 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 8.1 and Windows 10 (26624) SDKs to be installed with Visual Studio 2017. If these SDKs are 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.
Note: SDK 26624 was previously referred to as 10240.
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:
|Vulkan Program||A simple Vulkan program with no dependencies, except the Vulkan loader and validation layers. 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 validation layers. 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.|
|Vulkan Layer||A Vulkan layer that is built using the Vulkan Layer Factory framework.|
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 validation layers 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. For additional information on using Vulkan be sure to go through the Vulkan samples or find the many samples available online.
Examine Vulkan Sample Code
The Samples folder in the Vulkan SDK install folder contains Vulkan sample programs. This set of Vulkan code Samples is a work in progress. Refer to the Vulkan Samples guide for information about building and running the sample programs.
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.