VulkanSceneGraph学习教程（二十六）

第 26 章　常见问题与调试技巧

摘要：本章汇总了 VSG 开发中最常见的调试技巧与问题排查方法，包括 Vulkan 验证层开启、RenderDoc 抓帧分析、内存泄漏排查、全教程高频坑速查表、构建期常见问题以及系统化的调试工作流建议，可作为 VSG 开发的排错速查手册。

本章定位：把整套教程里最容易踩的坑集中到一页，并给出验证层、RenderDoc、内存排查的实用方法。建议作为「排错速查」常备。

26.1 开启 Vulkan 验证层

验证层能在开发期抓出绝大多数 API 误用（绑定不完整、布局不匹配、图像布局错误等）。

auto traits = vsg::WindowTraits::create(800, 600, "VSG Debug");
traits->debugLayer = true;          // 开启验证层（在 Window::create 之前设置）
traits->apiDump = false;            // 可选：打印每个 Vulkan 调用
auto window = vsg::Window::create(traits);

或在 CMake 定义：

target_compile_definitions(my_app PRIVATE VSG_DEBUG)

验证层需要 Vulkan SDK 安装且 VK_LAYER_PATH 指向 SDK 的 bin 层目录。用 vulkaninfo 确认驱动与层可用。

验证层错误示例：VUID-VkDescriptorSetLayoutBinding-descriptorType-00344

开启验证层后，常见的错误之一是 描述符绑定类型不匹配。以下是一个典型的验证层错误日志：

Validation Error: [ VUID-VkDescriptorSetLayoutBinding-descriptorType-00344 ] 
Object 0: handle = 0x1f3a5c0, type = VK_OBJECT_TYPE_DEVICE; | MessageID = 0x12345678 | 
vkCreateDescriptorSetLayout: binding #0 (index 0) is a VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 
but shader expects VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER. 
The Vulkan spec states: descriptorType must match the shader's declared descriptor type.

错误含义：

• VUID：Vulkan 验证层唯一错误标识符，用于定位规范条款。
• 核心问题：在 DescriptorSetLayout 的绑定 #0 处，你声明的是 VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER（Uniform 缓冲区），但着色器中对应的绑定点（layout(binding = 0) uniform sampler2D tex;）期望的是 VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER（采样器纹理）。
• 根本原因：VSG 的 DescriptorSetLayout 配置与 GLSL 着色器的 layout(binding=...) 声明不匹配。

VSG 代码修正方法：

1. 检查着色器声明（GLSL）：

// 错误声明（期望 Uniform Buffer，但实际是采样器）
layout(binding = 0) uniform MyUniform {
    vec4 color;
} ubo;

// 正确声明（匹配 Uniform Buffer）
layout(binding = 0) uniform MyUniform {
    vec4 color;
} ubo;

2. 修正 VSG 的 DescriptorSetLayout 创建：

// 错误配置：使用了 CombinedImageSampler 但着色器期望 UniformBuffer
auto sampler = vsg::Sampler::create();
auto imageInfo = vsg::ImageInfo::create(sampler, textureView, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
auto descriptor = vsg::DescriptorImage::create(imageInfo, 0, 0, VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER);

// 正确配置：使用 UniformBuffer 类型
auto bufferInfo = vsg::BufferInfo::create(uniformBuffer);
auto descriptor = vsg::DescriptorBuffer::create(bufferInfo, 0, 0, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER);

3. 确保 PipelineLayout 与 DescriptorSetLayout 一致：

auto descriptorSetLayout = vsg::DescriptorSetLayout::create({
    vsg::DescriptorSetLayoutBinding(0, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER, 1, VK_SHADER_STAGE_VERTEX_BIT)
});

auto pipelineLayout = vsg::PipelineLayout::create(
    vsg::DescriptorSetLayouts{descriptorSetLayout}, 
    vsg::PushConstantRanges{}
);

调试建议：

• 验证层会精确指出哪个绑定（binding #）类型不匹配，对照检查该绑定的 VSG 代码与 GLSL 声明。
• 使用 vsg::ShaderStage::create() 时，确保传入的 GLSL 代码与 DescriptorSetLayout 的 binding 和 descriptorType 完全对应。
• 如果使用 vsg::GraphicsPipelineConfigurator，检查 config->descriptorSetLayout 是否与着色器匹配。

提示：验证层错误信息通常包含 VUID- 前缀，可在 Vulkan 规范 中搜索该 VUID 查看详细说明。

26.2 用 RenderDoc 抓帧

RenderDoc 是 Vulkan 调试利器：

1. 用 RenderDoc 启动你的程序（或注入）；
2. 捕获一帧（F12 或 UI 触发）；
3. 在捕获里检查：

• Render Passes：是否就是第 12 章的 RenderGraph（每个 Pass 对应一个 RenderGraph）；
• Pipeline / Vertex Input：VertexInputState 的 binding/attribute 是否与着色器一致（第 7 章坑）；
• Descriptors：绑定是否到位、DescriptorImage 纹理是否正常（第 10 章）；
• Textures / Buffers：离屏 Pass 的中间结果（第 20 章后处理）。

抓帧前建议开 traits->debugLayer=true，这样 RenderDoc 事件浏览器会显示验证层错误，直接定位问题 Draw。

RenderDoc 实战截图示例

一张典型的 RenderDoc 捕获界面通常包含以下几个关键信息区域：

1. 事件浏览器（Event Browser）

   • 位于界面左侧，按时间顺序列出所有 Vulkan API 调用（Draw、Dispatch、Copy 等）。
   • VSG 对应：每个 vkCmdDraw* 对应 VSG 的一个 Command 节点执行。如果开启了 debugLayer=true，验证层错误会直接显示在对应事件旁，可快速定位问题 Draw。

2. 管线状态（Pipeline State）

   • 位于界面中部或右侧，展示当前选中 Draw 的完整管线配置。
   • 关键检查点：
     • Vertex Input：核对 binding、attribute 与 VSG 的 VertexInputState 是否一致（第 7 章常见坑）。
     • Descriptor Sets：查看绑定的 DescriptorSet 布局、绑定的 Buffer/Image 资源是否正确。
     • Shader Modules：确认着色器代码、push constant 范围与 VSG 的 ShaderStage 配置匹配。

3. 纹理查看器（Texture Viewer）

   • 显示当前绑定的纹理、渲染目标（Render Target）内容。
   • VSG 应用：
     • 检查离屏渲染的中间结果（如第 20 章的后处理 Pass）是否正确生成。
     • 确认 DescriptorImage 绑定的纹理格式、尺寸与着色器采样器期望的一致。

4. Render Pass 与帧缓冲（Render Pass & Framebuffer）

   • 展示当前 Render Pass 的附件（Attachments）、子通道（Subpasses）依赖关系。
   • 与 VSG 关联：这里的每个 Render Pass 通常对应 VSG 的一个 RenderGraph（第 12 章）。可验证：
     • 附件数量、格式是否与 RenderGraph 的 attachments 配置一致。
     • 子通道依赖是否与 RenderGraph 的 dependencies 匹配。

如何结合截图定位 VSG 渲染问题：

• 黑屏/花屏：先选中出问题的 Draw，在「Pipeline State」中检查：

  1. Vertex Input → 确认 location、format 与 GLSL 着色器声明一致。
  2. Descriptor Sets → 查看绑定的纹理/缓冲区是否为空或格式错误。
  3. Shader Modules → 确认着色器编译成功，无 undefined identifier 错误。

• 纹理显示异常：在「Texture Viewer」中选中对应的纹理：

  • 检查纹理内容是否正确（如全黑、全白可能表示渲染未成功）。
  • 核对纹理尺寸、格式是否与 DescriptorImage 创建时一致。

• 性能瓶颈：在「Event Browser」中观察 Draw Call 数量与分布：

  • 过多的 Draw 可能源于未合批（第 25 章优化建议）。
  • 单个 Draw 耗时过长可检查绑定的纹理尺寸是否过大、着色器是否复杂。

提示：捕获前务必开启 traits->debugLayer = true，这样 RenderDoc 会直接显示验证层警告/错误，帮你快速定位到具体的 API 调用位置。

26.3 内存泄漏排查

• CPU 侧：vsg::Allocator::instance()->report(std::cout) 看内存块是否只涨不跌（第 23 章）；切 ALLOCATOR_TYPE_NEW_DELETE + AddressSanitizer 抓越界/重复释放；
• ref_ptr 循环引用：两个对象互相 ref_ptr 持有 → 永不释放。反向/缓存指针用 vsg::observer_ptr 打破环；
• GPU 侧：RenderDoc 看Texture/Buffer 数量与大小；避免每帧重建 Buffer/Image；大场景用 DatabasePager 限量（第 18 章）。

26.4 全教程「高频坑」速查表

26.5 构建期常见问题

26.6 调试工作流建议

1. 开发期常开验证层（debugLayer / VSG_DEBUG），把错误消灭在编译/启动阶段；
2. 黑屏先查绑定：着色器 location ↔ VertexInputState ↔ DescriptorSetLayout 三者对齐；
3. 仍不行抓一帧：RenderDoc 看 Pass / Pipeline / Descriptor / Texture；
4. 性能问题先量化：Instrumentation + RenderDoc 看 Draw Call 与显存，再按第 25 章优化。

26.7 小结

• 验证层（debugLayer / VSG_DEBUG）是第一步防线；
• RenderDoc 看 Pass/Pipeline/Descriptor/Texture，定位绑定与后处理问题；
• 内存分 CPU（Allocator + observer_ptr）与 GPU（RenderDoc + 限量）两条线；
• 全教程坑已汇总成速查表，遇到异常先来这查。

26.8 延伸阅读

• 第 25 章《性能优化指南》：用工具量化后再优化；
• 第 12 章《RenderGraph 与 CommandGraph》：RenderDoc 里看到的 Pass 从何而来；
• 第 23 章《内存管理》：分配器与泄漏排查细节。

26.9 常见问题快速解答（FAQ）

1. 开启 debugLayer 后程序崩溃或报层找不到错误，如何解决？

步骤排查：

1. 确认 Vulkan SDK 安装：运行 vulkaninfo 或 vulkaninfo --summary，确保能正常输出设备信息。
2. 检查环境变量：设置 VK_LAYER_PATH 指向 Vulkan SDK 的层目录（如 C:\VulkanSDK\1.3.xxx.x\Bin 或 /usr/share/vulkan/explicit_layer.d）。
3. 验证层可用性：在 vulkaninfo 输出的 “Layers” 部分查看 VK_LAYER_KHRONOS_validation 是否列出。
4. VSG 编译选项：若使用 CMake 定义 VSG_DEBUG，确保编译时 Vulkan SDK 头文件路径正确。
5. 降级尝试：若仍失败，可尝试关闭 apiDump（设 traits->apiDump = false）或仅开启部分验证层特性。

2. RenderDoc 捕获不到我的 VSG 应用程序怎么办？

检查清单：

1. 以 RenderDoc 启动：从 RenderDoc UI 的 “Launch Application” 标签页启动你的可执行文件，不要直接双击运行。
2. 确认 Vulkan 渲染：RenderDoc 仅支持 Vulkan、D3D 等图形 API，确保程序使用 Vulkan 后端（VSG 默认即是）。
3. 检查捕获热键：RenderDoc 默认捕获热键是 F12，可在设置中修改。确保程序窗口焦点在捕获瞬间未被其他窗口抢占。
4. 验证层干扰：若开启 debugLayer 后 RenderDoc 无法注入，可临时关闭验证层（traits->debugLayer = false）再尝试捕获。
5. 管理员权限：在 Windows 上，以管理员身份运行 RenderDoc 可能解决注入权限问题。

3. 如何确认内存泄漏是 CPU 侧还是 GPU 侧？

诊断步骤：

1. CPU 侧检查：

   • 在程序运行期间定期调用 vsg::Allocator::instance()->report(std::cout)，观察 Allocated blocks 数量是否持续增长。
   • 使用 AddressSanitizer（Linux/macOS）或 Visual Studio 内存诊断工具（Windows）检测越界访问、重复释放。
   • 检查 ref_ptr 循环引用：将非拥有关系的指针改为 observer_ptr。

2. GPU 侧检查：

   • 使用 RenderDoc 捕获一帧，在 “Resource Manager” 标签页查看 Texture、Buffer 的数量和总大小。如果每帧都新增且不释放，则存在 GPU 泄漏。
   • 避免每帧创建新的 vsg::Buffer、vsg::Image 或 vsg::DescriptorSet，尽量复用。
   • 对于动态数据（如 Uniform Buffer），使用 vsg::BufferInfo 配合 vsg::CopyAndReleaseBuffer 进行更新，而非重建。

3. 综合判断：

   • 若 CPU 内存持续增长而 GPU 资源稳定 → 重点排查 ref_ptr 持有、容器未清理、静态变量累积。
   • 若 GPU 资源每帧增加 → 检查渲染循环中是否有未释放的 vsg::createBuffer、vsg::createImage 调用。
   • 二者均增长 → 可能为同一资源在 CPU/GPU 两端均未释放（如 vsg::Buffer 连带其 GPU 内存）。

教程完。本套教程从环境搭建、核心概念、场景实战、高级特性到完整项目，所有 API 均对照本仓库 include/vsg/ 源码核实。祝你用 VSG 写出高性能的 Vulkan 应用！