逐行读懂 HowToVulkan:单文件 700 行 main.cpp 的 8 大核心模块拆解
逐行读懂 HowToVulkan:单文件 700 行 main.cpp 的 8 大核心模块拆解
如果你正在学习 Vulkan,却常被冗长的样板代码劝退,那么 HowToVulkan 项目值得一读。它是一份面向 2026 年的极简 Vulkan 教程:整个可运行示例就写在单文件 source/main.cpp 里,约 700 行代码,从零搭建 Vulkan 实例到渲染出带光照、带纹理、可用鼠标旋转的 3D 模型,没有抽象层、没有面向对象套路,完全可以自上而下逐行读懂。下面我们把 main.cpp 拆成 8 大核心模块,快速带你走通整个程序。
上图是教程的最终成果:三个 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"的三件事:
- 创建 Instance(L121-L131):应用信息声明 Vulkan 1.3;平台相关扩展交给 SDL 自动提供(
SDL_Vulkan_GetInstanceExtensions),不用手写 Windows/Linux 分支。 - 选择物理设备与队列(L132-L157):枚举所有设备,支持命令行参数指定显卡编号,再找出支持
VK_QUEUE_GRAPHICS_BIT的队列族。 - 创建逻辑设备(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)的绝佳样本:
- 用 KTX-Software 加载 GPU 原生格式的 suzanne0.ktx(含完整 mip 链,无需解压转换);
- 创建 optimal tiling 图像 + view + 临时上传 buffer;
- 一次性命令缓冲中:barrier 转到
TRANSFER_DST_OPTIMAL→ 逐 mip 级vkCmdCopyBufferToImage→ barrier 转到READ_ONLY_OPTIMAL;fence 等待后释放临时资源; - 创建开启 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 行)
这是整篇教程的高潮,每帧按固定顺序执行:
- 同步(L469-L472):等 fence → 重置 fence → 取交换链图片;
- 更新 CPU 数据:用 glm 重算 projection/view/model 矩阵并
memcpy进映射内存; - 录制命令缓冲(L481-L562):barrier 准备颜色与深度附件 →
vkCmdBeginRendering动态开启渲染 → 绑管线、绑描述符、绑顶点/索引缓冲、push 数据地址 →vkCmdDrawIndexed一次画出 3 个实例 → 收尾 barrier 转PRESENT_SRC_KHR; - 提交与呈现(L563-L585):提交等 imageAcquired 信号量、信号"本图片渲染完成"信号量,随后 present 只等后者——渲染下一帧与呈现当前帧互不阻塞;
- 事件轮询:鼠标旋转选中模型、滚轮推拉相机、
+/-切换选中项; - swapchain 重建(L616-L650):窗口缩放或图片过期时,
vkDeviceWaitIdle后重建交换链与深度贴图; - 优雅退出(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 写法"的一份完整地图。
