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

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

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

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

1. Build the demo programs as described in the `Build the Demos Programs` section above.

2. 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'.

3. The generated trace file, `cube_trace.vktrace`, is created in the current directory.

4. 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 trace

   The `-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.

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

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

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