Vulkan C++ 示例集上手指南：从克隆仓库到跑通三角形只需四步

Vulkan C++ 示例集上手指南：从克隆仓库到跑通三角形只需四步

【免费下载链接】VulkanC++ examples for the Vulkan graphics API项目地址: https://gitcode.com/gh_mirrors/vu/Vulkan

用 Vulkan 画一个三角形并不简单——你需要自己写满一整套样板代码：创建 instance、选设备、建 swap chain、配 pipeline，任何一步出错都只能靠调试层慢慢排查。Vulkan C++ 示例集（仓库内即Vulkanexamples 项目）把这些样板都替你写好了，而且每个功能点都有独立示例。本文带你从零完成克隆、编译，跑到第一个可交互 demo，顺带说明常见坑怎么绕。

项目速览：一份跨平台的 Vulkan 学习参考库

这个仓库是面向 Khronos Vulkan 图形与计算 API 的开源 C++ 示例合集，目标只有一个：让你在每个 API 特性上都能找到一个可运行、可运行的参考实现。它覆盖 Windows、Linux、macOS、iOS、Android 和 OpenHarmony，包含约 70 个示例，从最基础的 examples/triangle/ 一直排到硬件加速光线追踪。

核心能力拆解：它能替你解决的四类问题

本节逐个说明这个仓库的四个能力点，每个点讲清楚"它能做什么"和"对你意味着什么"。

完整样板代码：你能看到"裸 Vulkan"长什么样。triangle示例刻意不省略任何步骤，从vkCreateInstance到第一帧提交全部展开。这意味着你可以把它当逐行注释教材用；等你读明白了，后面所有示例复用的 base/ 公共代码（设备、交换链、缓冲区、glTF 加载等封装）也就看得懂了。反过来，trianglevulkan13用 Vulkan 1.3 的 dynamic rendering 简化了同一件事，两个版本放一起读，API 演进一目了然。

同一示例三种着色语言：GLSL、HLSL、Slang 并排对比。大多数示例在 shaders/glsl/、shaders/hlsl/、shaders/slang/ 三个目录下都有对应源码，且仓库已附带预编译好的 SPIR-V（.spv）字节码（Vulkan 实际加载的就是这种机器可读的着色器格式）。对你意味着：不用改 C++ 代码，运行时加一个-s hlsl参数就能切换着色器语言版本，三种写法差异随手可查。

特性全覆盖：每个 Vulkan 高级主题都有独立示例。计算着色器（粒子、N-body、布料、GPU 剔除）、硬件光线追踪（阴影、反射、callable shader）、延迟渲染、PBR 光照、几何/曲面细分着色器、mesh shader，以及几十条扩展（dynamic rendering、descriptor heap、timeline semaphore 等）各占一个目录。你卡在某个特性上时，不用翻 API 文档猜，直接找到对应目录读源码即可。

跨平台与无头运行：没有显示器也能验证逻辑。仓库内置了 android/（Gradle 工程）、apple/（Xcode 工程）和 openharmony/ 三套平台工程。另有renderheadless、computeheadless两个无窗口示例，把渲染结果读回内存存盘、或纯跑计算任务。这意味着你可以在 CI 环境或服务器上验证 Vulkan 代码逻辑，不必依赖图形界面。

上手路径：四步从克隆到跑通

照下面四步做即可，全程无需手动配置依赖——所需第三方库（glm、imgui、tinygltf 等）都已放在 external/。

1. 克隆仓库（务必带--recursive），因为模型资源和部分依赖通过 submodule 管理：

   git clone --recursive https://gitcode.com/gh_mirrors/vu/Vulkan

2. 准备 Vulkan 驱动。Windows 和 Linux 上安装官方 Vulkan SDK 即可（它同时提供驱动和头文件）；macOS 没有原生 Vulkan，需要安装 MoltenVK 驱动，详见 BUILD.md。

3. 用 CMake 构建。要求 CMake 3.10+ 和支持 C++20 的编译器，两条命令完成：

   cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build

4. 运行示例。构建产物在bin目录，直接启动：

   ./triangle -v

   -v打开 validation layers（官方验证层，会在日志里指出 API 误用，新手强烈建议常开）。想看全部参数（窗口尺寸、选 GPU、benchmark 模式、切换着色器语言等），任意示例加--help查看。

效果展示：示例跑起来长这样

上面是基础三角形的结果。下面是另外两个有代表性的示例运行画面，说明这套示例的覆盖广度。

computeshader示例用一条独立的计算队列对整张图做卷积运算（如浮雕效果），窗口左上角实时显示每帧耗时和帧率。它演示了"非渲染类 GPU 负载"的标准写法：计算队列、图像 barrier、结果回读。

gltfscenerendering从磁盘加载 Crytek Sponza 场景的 glTF 2.0 模型，按材质拆分 pipeline 并做法线贴图渲染。如果你的目标是"加载真实 3D 资产并显示"，这是最值得精读的示例之一，源码在 examples/gltfscenerendering/。

常见坑与对策

这三个问题新手最常遇到，先说清楚可以避免不少排查时间。

克隆后资源目录是空的

如果你没带--recursive克隆，assets/会是空目录，示例运行时找不到模型和贴图。补救办法是对现有仓库执行git submodule init && git submodule update，或者删掉重新用--recursive克隆。

运行 Slang 版示例报扩展不支持

Slang 编译出的 SPIR-V 要求更高：选 Slang 后，所有示例的最低要求提升到 Vulkan 1.1 + SPIR-V 1.4 扩展（见 shaders/README.md）。如果你的驱动较旧，-s slang会启动失败。对策：要么升级驱动，要么默认用 GLSL 版本跑；重新编译 Slang 着色器时请使用较新版本的slangc，脚本入口是 shaders/slang/compileshaders.py。

光线追踪等示例在多 GPU 机器上跑不起来

部分示例依赖特定硬件特性（光追扩展、mesh shader 等），多 GPU 系统下默认选中的显卡可能不支持。先跑任意示例 -gl列出所有 Vulkan 设备，再用-g 编号指定支持对应特性的 GPU，而不是以为示例写错了。

不同目标，不同的切入示例

如果你是以下某种情况，建议按对应路径开始，而不是从第一个示例线性读下去：

下一步：继续深入的路径

跑通三角形只是起点，仓库内有现成的深入入口：

• 全部 70 个示例的完整清单与逐条说明：README.md 的 Examples 章节（按基础、glTF、高级、性能、PBR、计算、光追等分组）
• 各平台的构建细节（CMake 选项、WSI 选择、Android/Apple/OpenHarmony 工程）：BUILD.md
• 着色器编译规则与工具：shaders/README.md，以及各语言目录下的compileshaders.py
• 想改代码：单示例源码在 examples/ 对应目录，可复用的公共封装（设备、交换链、glTF 模型、UI 叠加层等）都在 base/

建议的下一步动作：挑一个你项目里最接近的示例，先读懂它的main文件，再对照shaders/下同名目录的着色器源码，把"C++ 侧提交什么、着色器侧接收什么"对应起来——对应明白之后，这个仓库对你来说就从"示例集"变成了"可查的参考手册"。

【免费下载链接】VulkanC++ examples for the Vulkan graphics API项目地址: https://gitcode.com/gh_mirrors/vu/Vulkan