Getting Started with the Vulkan SDK

Getting Started with the Vulkan SDK

Windows版使用教程

LunarG Vulkan SDK提供了构建，运行和调试Vulkan应用程序所需的开发和运行时组件。此SDK基于Khronos Vulkan API标头，其版本反映在Vulkan SDK版本号中（例如，SDK版本1.0.21.0表示SDK使用Vulkan标头版本1.0.21）。 SDK还包括用于窗口系统集成和调试扩展的某些Vulkan扩展（有关详细信息，请参阅发行说明）。

此SDK不包括Vulkan驱动程序。请联系您的GPU硬件供应商以获取Vulkan可安装客户端驱动程序（ICD）。这个SDK将允许您构建Vulkan应用程序，但是您需要一个Vulkan驱动程序（ICD）来执行它们。

该指南介绍了LunarG Vulkan SDK在Windows平台下的安装要求和步骤。还包括用于演示Vulkan应用程序的编译和运行时指令。关于最新的SDK信息，请查阅Vulkan.LunarG.com网站上的LunarG Vulkan SDK，文档及已知问题。

Vulkan API 是一种低CPU开销，易于理解的，跨平台的图形API，为应用程序提供了对GPU的直接控制，并最大化地提高应用程序的性能。有关Vulkan规范和API的更多信息，请查阅Khronos.org网站。与教程相关的内容，请参考LunarG的Vulkan教程，该教程位于SDK的Documentation\Tutorial目录以及LunarXchange网站上。

LunarG Vulkan SDK提供了构建，运行和调试Vulkan应用程序所需要的开发和运行时组件。该SDK基于Khronos Vulkan API的文件头，其版本反映在Vulkan SDK版本号中（比如，SDK版本1.0.21.0表示SDK所使用的Vulkan版本为1.0.21）。SDK中还包含一些用于窗口系统集成的Vulkan扩展，以及用于调试的扩展（有关进一步的详细描述请参考发布说明）。

Terminology（专业术语）

Term	Description
ICD	可安装的客户端驱动程序 — Vulkan兼容的显示驱动程序
GLSL	OpenGL着色语言
Layer	一个被设计成作为Loader的插件库，通常用于向应用程序提供校验和调试功能
Loader	一个实现了Vulkan API入口点的库，负责管理Layers（插件），扩展及驱动程序。该库位于SDK中，并独立于硬件供应商的驱动程序进行安装
SPIR-V	标准可移植的中间形式 — 一种跨API的中间语言，原生地表示并行计算和图形程序
Vulkan	由Khronos组织及相关的成员公司开发出的一套低CPU开销，高性能的图形API
WSI	窗口系统集成

System Requirements（系统需求）

使用LunarG Vulkan SDK进行Vulkan开发，需要一个满足特定的硬件和软件要求的Windows开发系统。系统规格如下：

• Windows 7, 8, 8.1, or 10 (64-bit)（SDK中同样包括有支持Windows 32位系统的文件，但是32位的功能还没有进行测试）。
• 支持Vulkan的显卡和ICD。 有关Vulkan的支持信息，请与您的图形硬件供应商联系。
• 8 GB内存
• 安装Vulkan SDK所需要的足够的磁盘空间（大约300 MB）

此外，要构建示例和演示应用程序，必须安装以下程序：

• CMake 3.0或更高版本（仅限示例）
• Python 3.0或更高版本（仅限示例）
• Visual Studio 2013 Update 4（Visual Studio 2015也可以，但没有得到官方的支持）

Download the SDK（下载SDK）

通过从vulkan.lunarg.com/点击“Download Vulkan Tools for Windows”按钮下载LunarG Vulkan SDK。下载的SDK文件名为VulkanSDK-version-Installer.exe，并记录文件所在的目录。

Install the SDK（安装SDK）

LunarG Vulkan SDK For Windows是一个自解压的安装程序。运行下载的.exe文件以完成SDK的安装。默认的安装位置为C:\VulkanSDK\version。

在LunarG Vulkan SDK的安装过程中会把SDK的安装目录设置为系统环境变量VULKAN_SDK的值，该目录类似于C:\VulkanSDK\1.0.0.0，但是版本号为实际安装的SDK版本。在些过程中还会把$$VULKAN_SDK\Bin（对应的32位Windows系统为$VULKAN_SDK\Bin32）添加到系统环境变量$PATH中。另外，系统环境变量VK_SDK_PATH设置为与VULKAN_SDK相同的值，以用于兼容之前的版本。需要注意的是，在安装过程中处于运行状态的程序和命令shell可能需要重新启动才能识别到更新的环境变量。

Vulkan Loader（加载程序）即vulkan-1.dll，被安装在C:\Windows\System32系统目录中。在32位Windows系统中为32位DLL，在64位Windows系统中则为64位DLL。而在64位系统中还会把32位的Vulkan加载程序（文件名相同）安装到C:\Windows\SysWOW64系统目录中。 Vulkan应用程序将会默认查找并使用该加载程序库。

SDK Contents（SDK包含的文件内容）

LunarG Vulkan SDK提供了开发和运行时组件用于创建，跟踪及回放Vulkan应用程序。该SDK还包括用于加载和运行Vulkan应用程序的校验和调试插件的运行时组件。SDK的安装进程会按照下表所示安装相关的内容。这些内容所有的路径都是相对于SDK的安装目录。

Directory	Description
Bin	64位Relase版可执行文件，以及加载程序，插件和工具库。注意：在32位Windows安装目录下没有该文件夹
Bin32	64位Relase版可执行文件，以及加载程序，插件和工具库
Config	插件示例程序
Demos	cube示例和vulkaninfo程序的源码及MS Visual Studio工程文件
Documentation	发布说明，入门指南，教程，Vulkan规范和其他文档
glslang	glslang的源文件和头文件; 由Samples目录中的示例程序使用
Include	编译Vulkan应用程序所需要的头文件
RunTimeInstaller	Vulkan运行时库安装程序;此安装程序可以包含在Vulkan应用程序或驱动程序中，并在安装应用程序或驱动程序时安装Vulkan运行时库；详细信息请查看文件README.txt。
Samples	Vulkan C++示例集合
Source\layers	用于调试插件库的源代码；支持对插件库进行源码级别的调试
Source\lib	Vulkan组件的64位预构建调试库; 用于示例程序在debug构建模式下进行调试。注意：在32位Windows安装目录下没有该文件夹
Source\lib32	Vulkan组件的32位预构建调试库; 用于示例程序在debug构建模式下进行调试
Source\loader	用于调试Vulkan加载库（vulkan-1.dll）的源代码; 支持对加载库进行源码级别的调试
spirv-tools	spirv-tools的头文件和源文件；用于Samples目录的示例程序中
Templates	Visual Studio的Vulkan工程模板
Third-Party	包含一些SDK中未使用的，但开发人员可能会用到以及工程模板中用到的第三方库。目前，包括GLM和SDL库。

Set up the Runtime Environment（运行时环境设置）

确保您已经安装了含有支持Vulkan的ICD的图形驱动程序。请与您的图形硬件供应商联系以获取相应的驱动程序。

Run with Alternate SDK（使用不同的SDK版本）

如果系统上安装了多个版本的SDK，在系统环境变换$PATH中会先引用最新安装的SDK版本的Bin目录的路径。要想在不同版本的SDK之间进行切换，只需重新安装要使用的SDK版本即可；在重新安装另一个版本之前不需要删除原有的SDK。

ICD and Layer Configuration（配置ICD及插件）

Vulkan加载库vulkan-1.dll会根据Windows注册表中的字符串值确定ICD库的位置，插件库的位置以及哪些插件是可用的。

Verify the Installation（验证安装）

通过运行Vulkan的演示程序验证LunarG Vulkan SDK是否安装完成。

在SDK中提供了一个 vulkaninfo 应用程序，运行该程序可以输出各种类型的vulkan信息，比如：

• 已标识的GPUs的设备属性
• 每个GPU支持的Vulkan扩展
• 识别出的插件
• 支持的图像格式和格式属性

通过选择开始菜单->Vulkan SDK ->vulkaninfo运行vulkaninfo程序，输出结果如下样例所示：

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

你还可以选择开始菜单->Vulkan SDK (version)，并选择cube程序来运行cube演示程序。

Build the Demo Programs（构建示例程序）

LunarG Vulkan SDK中包含两个演示程序的源代码：vulkaninfo和cube。其中cube程序有两个版本：一个是包含头vulkan.h使用C语言编写的，另一个包含vulkan.hpp头文件使用C++11编写的。vulkan.hpp头文件包含了使用Vulkan的底层C++11 API。

Vulkan演示程序使用了Microsoft Visual Studio的解决方案文件。要构建该演示程序，只需要直接打开（InstallPath\Demos）\DEMOS.sln文件。这将会启动Microsoft Visual Studio，并使用默认的构建配置选项Debug/Win32打开解决方案。然后选择所需的构建配置（即Debug/x64）。构建解决方案将会构建所有的演示程序。之后就可以使用Visual Studio调试器运行每个应用程序，并单步调试源代码，包括加载库源码以及任何已加载的插件源码。

Trace and Replay（跟踪并回放程序）

LunarG Vulkan SDK支持跟踪和回放Vulkan应用程序。有关Vulkan跟踪和回放的详细信息，请参阅Vulkan Trace and Replay Tools指南。

1.按照上一节Build the Demos Programs部分描述的内容，构建示例程序。

2.通过从命令提示符中运行以下命令来跟踪cube示例程序：

cd C:\VulkanSDK\<Version>\Demos\x64\Debug
vktrace -p cube.exe -o cube_trace.vktrace

运行几秒钟之后使用窗口的关闭按钮关闭程序。注意不要使用命令 ctrl+c 终止程序，因为这样做会导致生成中断的trace文件。上述的trace命令中使用了两个选项。

-p, --Program <string> — 跟踪的程序名
-o, --OutputTrace <string> — 生成的trace文件的文件名 — 文件名中必须包括后缀'.vktrace'。

3.生成的trace文件cube_trace.vktrace会创建到当前目录中。

4.回放刚刚生成的cube示例程序的trace文件。

vkreplay -t cube_trace.vktrace -l 2

注意该命令中所使用的参数选项

-t, --TraceFile  — 要执行回放的trace文件名
-l, --NumLoops  — 执行回放的次数

其中 -l 2 选项表示对该trace文件执行两次回放。

Enable Validation Layers（启用校验插件）

LunarG Vulkan SDK中包含了对调试和校验插件库的运行时支持。通过将VK_INSTANCE_LAYERS环境变量以分号分隔列表的形式保存到插件库的manifest文件中，在应用程序运行或跟踪回放时就可以启用这些插件。有关插件的manifest文件的更多信息，请参阅Vulkan Validation and Debugging Layers文档。

LunarG Vulkan SDK中包含有以下插件：

Layer Name	Description
VK_LAYER_GOOGLE_unique_objects	在创建时对所有的Vulkan对象命名一个唯一的句柄。在校验期间将会使用该句柄，以保证重复的对象句柄能被正确跟踪。注意，为了达到最优的效率，该插件层必须位于链中最后一层（最接近于显示驱动器）
VK_LAYER_LUNARG_api_dump	输出API调用及其参数和值
VK_LAYER_LUNARG_core_validation	输出并验证描述集，管线状态和动态状态；验证SPIR-V模块和图形管线之间的接口；跟踪并验证GPU显存及其与对象和命令缓冲区的绑定
VK_LAYER_LUNARG_image	验证texture格式及render target格式
VK_LAYER_LUNARG_object_tracker	输出创建/使用/销毁对象的过程，按类别跟踪对象
VK_LAYER_LUNARG_parameter_validation	校验API参数
VK_LAYER_LUNARG_swapchain	校验窗口系统集成“交换链”的扩展使用
VK_LAYER_GOOGLE_threading	检查多线程API使用的有效性

除了这些插件层之外，还有一种内置的meta-layer definition，这种元插件会以最优的顺序加载一组标准的校验插件：

VK_LAYER_LUNARG_standard_validation

加载meta-layer definition等同于按以下顺序加载指定的插件：

• VK_LAYER_GOOGLE_threading
• VK_LAYER_LUNARG_parameter_validation
• VK_LAYER_LUNARG_object_tracker
• VK_LAYER_LUNARG_image
• VK_LAYER_LUNARG_core_validation
• VK_LAYER_LUNARG_swapchain
• VK_LAYER_GOOGLE_unique_objects

要获取插件库的详细信息，请参阅Vulkan Validation and Debugging Layers分档。

例如，您可以启用api_dump插件层来检查在某个应用程序中调用的Vulkan API。VK_LAYER_LUNARG_api_dump插件是一个调试插件，会输出API调用，参数和值。

1.如下所示，通过显示设置Windows环境变量来显示启动VK_LAYER_LUNARG_api_dump。然后你就可以在上一节构建的应用程序中使用该插件。

VK_LAYER_LUNARG_standard_validation

2.运行 cube 示例程序：

cd C:\VulkanSDK\<Version>\Demos\x64\Debug
.\cube > api_dump.txt

注意要把该程序的输出重定向到一个文件中（因为cube.exe不是一个控制台程序）。几秒钟后终止程序并检查文件以查看使用api_dump插件产生的输出。VK_LAYER_LUNARG_api_dump插件将会输出API调用，参数和值。

3.停用刚刚显式启用的插件

set VK_INSTANCE_LAYERS=

Create a New Visual Studio Project（创建一个新VS工程）

Vulkan SDK中包含了Visual Studio示例模板，使得编程人员可以在不重新设置包含路径和依赖库的情况下就可以轻松创建Vulkan工程。这些工程模样位于SDK安装目录下的“Templates”子目录中。为了在Visual Studio开始页面中显示这些模板工程，需要将它们复制到Visual Studio能够识别的C++模板目录中。默认情况下，该目录位于：

C:\Users\username\Documents\Visual Studio 201x\Templates\ProjectTemplates\Visual C++ Project

Vulkan SDK中包含了单独用于Visual Studio 2013和2015的工程模板。将SDK Templates 目录中的zip文件复制到上面给出的Visual Studio路径中就可以启用这些模板。另外，也可以把Visual Studio的默认目录指定为SDK的模板目录，而不进行任何复制，但这样做意味着必须将任何其他的工程模板也放入Vulkan SDK安装目录中。因此，建议把模板文件复制出来。

复制完成后，现在你就可以使用这些模板创建新的工程或解决方案。通过点击菜单项File -> New -> Project 打开新建工程对话框。然后在该对话框的左侧栏上选择Templates -> Visual C++。在对话框的中间你会看到内置模板的列表，列表的最下面就是Vulkan模板了。SDK中包含的模板描述如下：

Layer Name	Description
Vulkan Program	一个简单的Vulkan程序，除了Vulkan加载库和校验插件外不依赖任何其他的库。此程序使用Vulkan的C接口API创建并随后销毁一个简单的Vulkan实例。
Vulkan Windowed Program	一个依赖于SDL和GLM库的Vulkan程序。该程序创建一个空白窗口，然后在该窗口上初始化一个Vulkan表面，然后等待用户关闭窗口。该模板使用Vulkan的C接口API。
Vulkan C++ Program	一个简单的Vulkan程序，除了Vulkan加载库和校验插件外不依赖任何其他的库。此程序使用Vulkan的C++接口API创建并随后销毁一个简单的Vulkan实例。
Vulkan C++ Windowed Program	一个依赖于SDL和GLM库的Vulkan程序。该程序创建一个空白窗口，然后在该窗口上初始化一个Vulkan表面，然后等待用户关闭窗口。该模板使用Vulkan的C++接口API。

选择“Vulkan Windowed Program”，并输入工程名，然后点击“OK”。 就会在Visual Studio中打开一个新的解决方案和工程。然后构建并运行该工程。之后你就会看到弹出一个空白的窗口，并且在关闭窗口时程序会返回代码0。然后，将配置改为x64，再次运行该工程。你应该会看到两样的结果，只是这一次是构建了一个64位的程序。

花一些时间仔细查看该工程的源代码。如果是在调试模式构建工程，则会启用校验插件。该程序在窗口上创建了一个Vulkan表面，但没有在屏幕上渲染任何东西。

现在你已经有了一个可以正常运行的Vulkan工程。可以在此基础上创建一个更大型的项目。有关如何使用Vulkan的其他信息，请务必仔细查看LunarG Vulkan示例，或者在网上查找更多可用的示例程序。

RenderDoc Debugger

RenderDoc图形调试工具作为Vulkan Windows SDK的一部分，是随着SDK一起进行安装的。有关RenderDoc的详细信息，请查看网站https://RenderDoc.org。但是需要注意的是卸载SDK时不会卸载此组件。

Examine Vulkan Sample Code

在Vulkan SDK安装目录的Samples文件夹中包含有Vulkan示例程序。这些示例代码部分还处于开发中。关于如何构建和运行示例程序，请查看Vulkan Samples指南。

如果你有兴趣贡献更多的示例，请联系LunarG。

Next Steps

本指南介绍了LunarG Vulkan SDK中的主要组件和工具。有关最新的SDK信息以及完整的SDK文档，请查看Vulkan.LunarG.com。