逐行读懂 HowToVulkan:单文件 700 行 main.cpp 的 8 大核心模块拆解

原创2026-11-02 14:33:442,604 阅读

逐行读懂 HowToVulkan:单文件 700 行 main.cpp 的 8 大核心模块拆解

如果你正在学习 Vulkan,却常被冗长的样板代码劝退,那么 HowToVulkan 项目值得一读。它是一份面向 2026 年的极简 Vulkan 教程:整个可运行示例就写在单文件 source/main.cpp 里,约 700 行代码,从零搭建 Vulkan 实例到渲染出带光照、带纹理、可用鼠标旋转的 3D 模型,没有抽象层、没有面向对象套路,完全可以自上而下逐行读懂。下面我们把 main.cpp 拆成 8 大核心模块,快速带你走通整个程序。

HowToVulkan 教程运行效果:Vulkan 渲染出的三个 Phong 光照 3D 模型

上图是教程的最终成果:三个 suzanne 模型用 Phong 光照着色,按住鼠标左键可旋转,滚轮缩放视角,+/- 键切换高亮模型。完整图文教程见 tutorial/docs/index.md。

模块 1:全局状态与 chk 错误检查(第 1~108 行)

程序开头集中声明了几乎所有全局变量:VkInstance、VkDevice、VkSwapchainKHR、VmaAllocator、纹理数组、同步对象等,一眼就能看清程序需要哪些资源。

值得先记住的是两个小工具函数(main.cpp#L87-L108):

  • chk(VkResult):Vulkan 调用失败立即打印错误码并退出;
  • chkSwapchain:对 swapchain 相关的 VK_ERROR_OUT_OF_DATE_KHR 不退出,而是标记"待重建"——这是窗口缩放重建交换链的标准做法。

这种"最小化错误处理"策略让初学者能专注流程本身,而不被异常处理淹没。

模块 2:Vulkan 实例、设备选择与队列(第 110~179 行)

这一模块完成"连接 GPU"的三件事:

  1. 创建 Instance(L121-L131):应用信息声明 Vulkan 1.3;平台相关扩展交给 SDL 自动提供(SDL_Vulkan_GetInstanceExtensions),不用手写 Windows/Linux 分支。
  2. 选择物理设备与队列(L132-L157):枚举所有设备,支持命令行参数指定显卡编号,再找出支持 VK_QUEUE_GRAPHICS_BIT 的队列族。
  3. 创建逻辑设备(L158-L175):通过 pNext 链一次性启用关键核心特性——Vulkan 1.2 的 descriptor indexing、buffer device address,Vulkan 1.3 的 dynamic rendering、synchronization2。这正是本教程"用现代特性简化 Vulkan"的核心思想:少写扩展检查,少写 render pass。

紧接着初始化 VMA(Vulkan Memory Allocator,L176-L179),后续所有显存分配都由它代劳,省去大量内存类型选择代码。

模块 3:窗口、Surface 与 Swapchain(第 180~243 行)

SDL 三行代码完成平台相关的窗口与 surface 创建(L181-L183),随后:

  • 查询 surface 能力,兼容 Wayland 下 currentExtent.width == 0xFFFFFFFF 的情况;
  • 用 VK_FORMAT_B8G8R8A8_SRGB + FIFO 呈现模式创建 swapchain(L192-L206)——这是"保证所有设备可用"的最稳组合;
  • 交换链图片不归应用所有,需向 swapchain 查询获取,并为每张图创建 VkImageView。

注意这里的 imageFormat 变量后面还会复用于 pipeline 的 dynamic rendering 配置,是全文件贯穿性较强的常量之一。

模块 4:深度贴图与模型缓冲(第 216~270 行)

深度贴图(L216-L243):先在 D32_SFLOAT_S8_UINT / D24_UNORM_S8_UINT 中探测设备支持的格式,再用 VMA 分配专用内存。深度图只有 GPU 访问,所以不需要像 CPU-GPU 共享资源那样做双缓冲。

模型加载(L244-L270):用 single-header 库 tinyobj 加载 assets/suzanne.obj 对应模型,把位置、法线、UV 交错(interleaved)进 Vertex 结构,注意 y 轴与纹理 v 坐标的翻转是为适配 Vulkan 坐标系。顶点与索引数据写入同一个 VMA 缓冲,靠 HOST_ACCESS_ALLOW_TRANSFER_INSTEAD 标志直接映射到显存,一次 memcpy 完成上传——省掉了传统的 staging buffer 三步拷贝。

模块 5:Shader 数据缓冲、同步对象与命令池(第 270~293 行)

这是理解"CPU 与 GPU 并行"的关键模块:

  • 双缓冲的 ShaderData 缓冲(L270-L277):maxFramesInFlight = 2,CPU 更新第 n+1 帧矩阵时,GPU 还在读第 n 帧。每个缓冲通过 vkGetBufferDeviceAddress 拿到设备地址,shader 里像指针一样直接用,完全绕开了 descriptor——这是 buffer device address 特性的最大红利。
  • 同步对象(L278-L288):每帧一个 fence(GPU→CPU)+ 一个 imageAcquired 信号量;渲染完成信号量数量则与 swapchain 图片数一致,为"提交-呈现"解耦做准备。
  • 命令池与命令缓冲(L289-L293):按帧数分配,供渲染循环每帧重置录制。

模块 6:纹理加载与描述符集合(第 294~403 行)

纹理走的是"传统但完整"的上传流程,也是初学者理解图像布局(image layout)的绝佳样本:

  1. 用 KTX-Software 加载 GPU 原生格式的 suzanne0.ktx(含完整 mip 链,无需解压转换);
  2. 创建 optimal tiling 图像 + view + 临时上传 buffer;
  3. 一次性命令缓冲中:barrier 转到 TRANSFER_DST_OPTIMAL → 逐 mip 级 vkCmdCopyBufferToImage → barrier 转到 READ_ONLY_OPTIMAL;fence 等待后释放临时资源;
  4. 创建开启 8x 各向异性的 VkSampler。

之后(L389-L403)借助 descriptor indexing 搭建"bindless"描述符:单个可变长度 binding 装下全部纹理的 COMBINED_IMAGE_SAMPLER,shader 里按实例下标直接索引采样,纹理数量扩展无需改绑定代码。

模块 7:Slang 着色器编译与渲染管线(第 404~464 行)

2026 年写 Vulkan 不必再用 GLSL:本例在运行时调用 Slang 编译器,把 source/assets/shader.slang 直接编译成 SPIR-V(L404-L417)。shader 本身不到 60 行,实现了顶点侧 MVP 变换 + 片元侧 Phong 光照。

管线创建(L418-L464)展示了两处现代化简化:

  • 用 VkPipelineRenderingCreateInfo 声明颜色/深度附件格式,配合 dynamic rendering,不再需要单独创建 VkRenderPass——老教程里最臭名昭著的繁琐环节被彻底移除;
  • 只把 viewport 和 scissor 设为 dynamic state(窗口尺寸会变),其余状态固化进管线;
  • push constant 传一个 VkDeviceAddress,即把 shader 数据缓冲地址递给顶点着色器。

模块 8:渲染主循环、窗口缩放与资源销毁(第 465~687 行)

这是整篇教程的高潮,每帧按固定顺序执行:

  1. 同步(L469-L472):等 fence → 重置 fence → 取交换链图片;
  2. 更新 CPU 数据:用 glm 重算 projection/view/model 矩阵并 memcpy 进映射内存;
  3. 录制命令缓冲(L481-L562):barrier 准备颜色与深度附件 → vkCmdBeginRendering 动态开启渲染 → 绑管线、绑描述符、绑顶点/索引缓冲、push 数据地址 → vkCmdDrawIndexed 一次画出 3 个实例 → 收尾 barrier 转 PRESENT_SRC_KHR;
  4. 提交与呈现(L563-L585):提交等 imageAcquired 信号量、信号"本图片渲染完成"信号量,随后 present 只等后者——渲染下一帧与呈现当前帧互不阻塞;
  5. 事件轮询:鼠标旋转选中模型、滚轮推拉相机、+/- 切换选中项;
  6. swapchain 重建(L616-L650):窗口缩放或图片过期时,vkDeviceWaitIdle 后重建交换链与深度贴图;
  7. 优雅退出(L652-L687):vkDeviceWaitIdle 后按依赖逆序销毁全部资源。

快速上手:如何构建这个项目

构建配置在 source/CMakeLists.txt,推荐先安装 Vulkan SDK(勾选 GLM、Volk、SDL3、VMA 组件),然后在 source 目录下运行:

cmake -B build -G "Visual Studio 17 2022"

Linux 下 CMake 会自动通过 FetchContent 拉取 glm,并定义 VK_USE_PLATFORM_WAYLAND_KHR;外部依赖(KTX、tinyobjloader)已随仓库放在 source/external/ 目录,KTX 以静态库方式编译。运行程序前确保工作目录下存在 assets 文件夹(程序启动时会检查)。

💡 学习建议:开发时始终启用 Vulkan 验证层(validation layers),再对照 tutorial/docs/index.md 中官方教程的逐段讲解,配合 RenderDoc 观察 GPU 侧行为,这 700 行代码基本就是"2026 年现代 Vulkan 写法"的一份完整地图。

登录后查看全文
HowToVulkan