# 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.
- 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 (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:

- 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 `.cmake` files 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)

### 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:

- Windows 11 ARM 64-bit OS
- 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)
- Note: All Windows Vulkan SDK binaries are built with Visual Studio 2022.

## 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.

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
`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:

- 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] (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_object`VK_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 (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

### 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.