Getting Started with the Vulkan SDK
Version for Windows
Copyright © 2015-2017 LunarG, Inc.
This guide describes the requirements and procedure for installing the LunarG Vulkan SDK for Windows. It also includes compilation and runtime instructions for demo Vulkan applications. Refer to the LunarG Vulkan SDK, Documentation and Known Issues at Vulkan.LunarG.com 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 LunarG's Vulkan tutorial, which can be found in the SDK in the
Documentation\Tutorial
directory and on the LunarXchange website.
The LunarG 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 1.0.21.0 indicates that the SDK uses Vulkan header revision 1.0.21). The SDK also includes certain Vulkan extensions for window system integration and debug extensions (refer to the release notes for further details).
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 driver (ICD) to execute them.
Terminology
Term | Description |
---|---|
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 |
System Requirements
Vulkan development using the LunarG 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 300 MB)
In addition, to build the samples and demos, one must install the following programs:
- CMake 3.0 or newer (samples only)
- Python 3.0 or newer (samples only)
- Visual Studio 2015, or newer (Visual Studio 2013 may work in a limited fashion)
- NOTE:
- Starting with Vulkan SDK 1.0.54.0, 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 that you upgrade to using Visual Studio 2015, or newer.
- Starting with Vulkan SDK 1.0.54.0, all binaries in the SDK are generated using Visual Studio 2015.
- NOTE:
Download the SDK
Download the LunarG Vulkan SDK from Vulkan.LunarG.com by clicking on the 'Download Vulkan Tools for Windows' button. The SDK download file is named VulkanSDK-
version
-Installer.exe
. Make note of the directory to which the file was downloaded.
Install the SDK
The LunarG Vulkan SDK For Windows is a self-extracting installer. Run the downloaded .exe
file to install the SDK. The default SDK install location is C:\VulkanSDK\
version
.
Installing the LunarG 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 LunarG Vulkan SDK also prepends %VULKAN_SDK%\Bin
(%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 that 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.
SDK Contents
The LunarG 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.
Directory | Description |
---|---|
Bin | 64-bit Release build of executables that belong in the system path. NOTE: This folder is not present on 32-bit Windows installs |
Bin32 | 32-bit Release build of executables that belong in the system path |
Config | Sample layer settings file |
Demos | Source and MS Visual Studio project files for the cube and vulkaninfo programs |
Documentation | Release notes, getting started guide, tutorial, Vulkan specifications and other documentation |
glslang | Source and header files for glslang; used by the programs in Samples |
Include | Header files required to compile Vulkan applications |
Lib | 64-bit libraries for loader, layers and tools. NOTE: This folder is not present on 32-bit Windows installs |
Lib32 | 32-bit libraries for loader, layers and tools |
RunTimeInstaller | 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 README.txt for more information. |
Samples | A collection of Vulkan C++ samples |
shaderc | The source code for shaderc, a command line tool and library to compile shaders |
Source\layers | Source code for the debug layers libraries; enables source level debugging of layers |
Source\lib | 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 |
Source\lib32 | 32-bit pre-built debug libraries for selected Vulkan components; used by Demos debug build |
Source\loader | Source code for the debug loader library (vulkan-1.dll); enables source level debugging of the loader |
spirv-tools | Source and header files for spirv-tools; used by the programs in Samples |
Templates | Visual Studio Vulkan project templates |
Third-Party | 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. |
Tools | 64-bit binaries for tools that do not belong in the system path. NOTE: This folder is not present on 32-bit Windows installs |
Tools32 | 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 System32
and SysWOW64
. These PDB files should not be confused with the PDB files for the debug build, which are located in Source\loader
.
Set up the Runtime Environment
Be sure that 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 LunarG Vulkan SDK by running a few things:
- Run LunarG's Vulkan Installation Analyzer (VIA) to determine if it believes everything can execute properly.
- VIA can be found as a shortcut under the Start Menu
Start Menu->Vulkan SDK <version>->via
- More information on VIA can be found in the VIA.html doc found in this SDK's Documentation section.
- Run a demo Vulkan application like
vulkaninfo
- VulkanInfo can be found as a shortcut under the Start Menu
Start Menu->Vulkan SDK <version>->vulkaninfo
vulkaninfo
is a program provided in the SDK that outputs various types of Vulkan information such as:
- device properties of identified GPUs
- Vulkan extensions supported by each GPU
- recognized layers
- supported image formats and format properties
Sample vulkaninfo
output follows:
Instance Extensions count = 2
DEBUG_REPORT : extension revision 1
VK_EXT_KHR_swapchain : extension revision 17
Instance Layers count = 11
VK_LAYER_LUNARG_object_tracker (LunarG Validation Layer) Vulkan version 1.0.0.0, layer version 1.0.0.0
ObjectTracker Extensions count = 0
VK_LAYER_LUNARG_api_dump (LunarG debug layer) Vulkan version 1.0.0.0, layer version 1.0.0.0
VK_LAYER_LUNARG_api_dump Extensions count = 0
...
Device Extensions and layers:
=============================
GPU0
VkPhysicalDeviceProperties:
===========================
apiVersion = 696322
driverVersion = 1
vendorId = 0x10de
deviceId = 0x1183
deviceType = DISCRETE_GPU
deviceName = GTX 660 Ti
VkPhysicalDeviceLimits:
-----------------------
maxImageDimension1D = 0x4000
maxImageDimension2D = 0x4000
...
Device Extensions count = 1
VK_EXT_KHR_device_swapchain : extension revision 53
...
You can also run the cube demo program by selecting the program in Start Menu->Vulkan SDK <version>
.
Build the Demo Programs
The LunarG Vulkan SDK includes the source for two demo applications: vulkaninfo
and cube
. There are two versions of the cube example: one written in C using vulkan.h, and another written in C++11 using vulkan.hpp. The 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 <InstallPath>\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. It is now possible to run each of the applications using the Visual Studio debugger, and to step through their source code including the loader library source and the source of any layer libraries you have enabled.
Trace and Replay
The LunarG 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.
-
Build the demo programs as described in the
Build the Demos Programs
section above. -
Trace the
cube
demo program by running the following commands from a command prompt:cd C:\VulkanSDK\<Version>\Demos\x64\Debug vktrace -p cube.exe -o cube_trace.vktrace
Close the program after a few seconds, using the window's close button. Do not stop the program by using
ctrl+c
as doing so may result in a corrupted 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'. -
The generated trace file,
cube_trace.vktrace
, is created in the current directory. -
Replay the cube trace file you just generated:
vkreplay -o cube_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 traceThe
-l 2
option replays the trace twice.
Enable Validation Layers
The LunarG Vulkan SDK includes runtime support for Debugging and Validation 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 Debugging Layers document for more information on layer manifest files.
The LunarG Vulkan SDK includes the following layers:
Layer Name | Description |
---|---|
VK_LAYER_GOOGLE_unique_objects | Alias all Vulkan objects with a unique handle at create time. This is used during validation to ensure that duplicate object handles are correctly tracked. Note that for optimal efficiency, this layer must be last in the chain (closest to the display driver) |
VK_LAYER_LUNARG_api_dump | Print API calls and their parameters and values |
VK_LAYER_LUNARG_core_validation | Print and validate the descriptor set, pipeline state, and dynamic state; validate the interfaces between SPIR-V modules and the graphics pipeline; track and validate GPU memory and its binding to objects and command buffers; validate texture formats and render target formats |
VK_LAYER_LUNARG_object_tracker | Print object create/use/destroy, tracking objects by category |
VK_LAYER_LUNARG_parameter_validation | Validate API parameters |
VK_LAYER_GOOGLE_threading | Check validity of multi-threaded API usage |
VK_LAYER_LUNARG_monitor | Monitor the framerate of a program |
In addition to these layers, there is a built-in meta-layer definition which will load a standard set of validation layers in the optimal order:
VK_LAYER_LUNARG_standard_validation
Loading this layer definition is equivalent to specifying the following layers in this order:
- VK_LAYER_GOOGLE_threading
- VK_LAYER_LUNARG_parameter_validation
- VK_LAYER_LUNARG_object_tracker
- VK_LAYER_LUNARG_core_validation
- VK_LAYER_GOOGLE_unique_objects
Refer to the Vulkan Validation and Debugging Layers documentation for detailed information on layers.
As an example, you can turn on the api_dump layer to examine the Vulkan API calls from an application. The VK_LAYER_LUNARG_api_dump layer is a debug layer which will print API calls, parameters, and values.
-
Explicitly activate VK_LAYER_LUNARG_api_dump by setting Windows environment variables as shown below. You'll use this layer with an application that was built in a previous section.
set VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_api_dump
-
Run the
cube
program:cd C:\VulkanSDK\<Version>\Demos\x64\Debug .\cube > api_dump.txt
Note that you must redirect the output to a file (as cube.exe is not a console application). Stop the program after a few seconds and examine the file to see the api_dump layer output. The VK_LAYER_LUNARG_api_dump debug layer will print API calls, parameters, and values.
-
Deactivate the explicit layer just enabled.
set VK_INSTANCE_LAYERS=
Create a New Visual Studio Project
The Vulkan SDK includes Visual Studio templates so that a programmer can easy 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. Note that 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.
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
. On the left bar select Templates -> Visual C++
. Now, in the center 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 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. |
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 LunarG Vulkan samples, or find the many samples available online.
RenderDoc Debugger
The RenderDoc graphics debugger is installed as part of the Windows SDK. For information about RenderDoc, see https://RenderDoc.org Note that this component is NOT uninstalled as part of uninstalling the SDK.
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.
Contact LunarG if you are interested in contributing to this effort.
Next Steps
This guide provided an introduction to the main components and tools in the LunarG Vulkan SDK. Refer to Vulkan.LunarG.com for the most up to date SDK information, including the complete set of SDK documentation.