Getting Started with the Vulkan SDK
Version for Windows
This guide describes the requirements and procedure for installing the Vulkan SDK for Windows. It also includes compilation and runtime instructions for demo Vulkan applications. Refer to the Vulkan SDK, Documentation, and Known Issues at the Vulkan SDK Download Site for the most up to date SDK 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, which can be found in the SDK in the
Documentation\Tutorial\html directory and 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.
The Vulkan SDK provides the development and runtime components required to build, run, and debug Vulkan applications. This SDK is based on the Khronos Vulkan API header, whose version is reflected in the Vulkan SDK version number (for example, SDK version 184.108.40.206 indicates the SDK uses Vulkan header revision 1.1.70). The SDK also includes certain Vulkan extensions for window system integration and debug extensions (refer to the release notes for further details).
Note: This version number does not indicate an application cannot be developed for earlier Vulkan versions. As such, a 1.1 SDK can still be used to develop Vulkan 1.0 applications but cannot be used to develop applications for future versions of Vulkan. Furthermore, the presence of a 1.1 SDK does not necessarily indicate a system can actually run Vulkan 1.1. A Vulkan 1.1 driver is required for applications to use most Vulkan 1.1 functionality. For more information on how to query Vulkan versions programmatically, see the 1.1 samples in the SDK.
|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 can be found in the SDK as well as 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: For Windows, CMake 3.12.2 is recommended.
- Python 3.0 or newer (samples only)
- Visual Studio 2015 or newer (Visual Studio 2013 may work in a limited capacity)
- Starting with Vulkan SDK 220.127.116.11, all binaries in the SDK are generated using Visual Studio 2015
- This change was made to allow building the Runtime with Control Flow Guard protection
- If you continue to use Visual Studio 2013, you may encounter the following issues:
- Linking a project built with Visual Studio 2013 to the static Vulkan runtime library or shaderc included in the SDK may no longer succeed
- Attempting to debug an executable or library included with this SDK may not provide all debug information available
- If either of these is important to you, we suggest you upgrade to Visual Studio 2015 or newer
- Starting with Vulkan SDK 18.104.22.168, all binaries in the SDK are generated using Visual Studio 2015
Download the SDK
Download the Vulkan SDK from the Vulkan SDK Download Site by clicking on the "Download Vulkan Tools for Windows" button. The SDK download file is named
-Installer.exe. 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.
The Vulkan loader,
vulkan-1.dll, is installed in
C:\Windows\System32. This will be a 32-bit DLL on 32-bit Windows targets and a 64-bit DLL on 64-bit Windows targets. 64-bit targets will also have the 32-bit Vulkan loader (of the same name) installed in
C:\Windows\SysWOW64. Vulkan applications will find and use the appropriate library by default.
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|
||Release notes, Getting Started Guide, tutorial, Vulkan specifications, and other documentation|
||Source and header files for glslang; used by the programs in Samples|
||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 loader, layers, and tools (Note: This folder is not present on 32-bit Windows installs)|
||32-bit libraries for loader, layers, and tools|
||Vulkan runtime installer; this installer can be included by a Vulkan application or driver installer to install the Vulkan runtime libraries during an application or driver install; see
||A collection of Vulkan C++ samples|
||The source code for shaderc, a command line tool and library to compile shaders|
||Source code for the debug layers libraries; enables source level debugging of layers|
||64-bit pre-built debug libraries for selected Vulkan components; used by Demos debug build (Note: This folder is not present on 32-bit Windows installs)|
||32-bit pre-built debug libraries for selected Vulkan components; used by Demos debug build|
||Source code for the debug loader library (
||Source and header files for spirv-tools; used by the programs in Samples|
||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|
Note: To aid in debugging, the SDK includes PDB files for the Vulkan loader. The PDB files for the loader shipped in the Vulkan runtime are located in
Lib (64-bit) and
Lib32 (32-bit). These PDB files correspond to
vulkan-1.dll, found in
SysWOW64. These PDB files should not be confused with the PDB files for the debug build, which are located in
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.
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 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.
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 2013, 2015, and 2017. 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.
Using Vulkan in CMake Projects
As an alternative to starting with Visual Studio templates you can also define a Vulkan project with CMake.
Recent CMake versions ship with a
FindVulkan.cmake module that uses the
VULKAN_SDK environment variable to locate the Vulkan include files and libraries
needed for building Vulkan applications.
This module makes it easy to add the Vulkan support files to your application.
For example, this
CMakeLists.txt file can be used to build the Vulkan Info
project(vulkaninfo) find_package(Vulkan REQUIRED) add_executable(vulkaninfo vulkaninfo.c) target_compile_definitions(vulkaninfo PRIVATE VK_USE_PLATFORM_WIN32_KHR) target_link_libraries(vulkaninfo Vulkan::Vulkan)
CMakeLists.txt file with the above contents and
vulkaninfo.c from the SDK into the same location as the
Generate the build files for the project:
mkdir build cd build cmake ..
cmake -A x64 .. for 64-bit builds.
You can open the
vulkaninfo.sln Visual Studio solution file that was generated by
this step with Visual Studio and build the application from there.
Or you can build the application from the command line with:
cmake --build .
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.