第 2 章 VSG 整体架构概览
本章定位：建立「模块 → 职责」的地图，知道每类功能该去哪个目录/哪个库找。后续章节会逐个深入。
2.1 本章目标
- 理解 VSG 的「单一核心库 + 外部组件库」分层；
- 认识核心库
vsg的子模块目录及其职责； - 分清哪些能力已并入核心、哪些需要额外安装组件库。
2.2 前置准备
在深入各模块之前，先通过一张总体框架图建立全局认知。下图展示了 VSG 的整体架构以及核心库与外部组件库之间的协作关系：
图中各模块的关系可概括为：核心库vsg是渲染引擎的主体，其中core提供引用计数与内存管理等基础设施，nodes负责组织场景图，state与commands描述渲染状态与命令录制，app层的Viewer负责把场景图编译并提交到vk封装的 Vulkan 对象，最终呈现到窗口；外部组件库则通过工厂函数（如vsg::read()）或集成接口，在场景构建或窗口嵌入等环节与核心库协作。
建议先读完第 1 章，理解 VSG 的设计理念。本章以源码目录（include/vsg/）为线索讲解，可对照本仓库阅读。
2.3 单一核心库vsg
VSG 的核心是一个C++ namespacevsg，对应一个 CMake targetvsg（安装后导出为vsg::vsg）。它不是由多个独立库（如vsgCore、vsgPlatform…）组合而成——所有子模块都编译进同一个vsg库，通过子目录组织代码：
include/vsg/ ├── core/ 引用计数(ref_ptr)、Object、Allocator、内存管理 ├── nodes/ Node / Group / MatrixTransform / Switch / LOD / Geometry / StateGroup / … ├── state/ Pipeline、Descriptor、ShaderModule、VertexInputState、ViewportState、… ├── commands/ Draw* / Bind* / Commands 等可录制命令对象 ├── app/ Viewer / Window / Camera / View / RenderGraph / CommandGraph ├── io/ 序列化、文件读写、DatabasePager（异步分页加载） ├── platform/ Window 的窗口系统后端（Win32 / Xcb / MacOS / Android / headless） ├── maths/ 矩阵/向量/四元数（dmat4, dvec3, quat 等） ├── text/ 文字渲染（⚠️ 已并入核心，不是外部库） ├── raytracing/ 光线追踪（⚠️ 已并入核心） ├── lighting/ 光照相关类型（方向光、点光源等） ├── threading/ 线程与任务封装 ├── ui/ 事件、UI 事件（PointerEvent / KeyEvent / WindowEvent） ├── utils/ ShaderSet / GraphicsPipelineConfigurator 等便捷工具 ├── vk/ Vulkan 对象轻量封装（Device / Buffer / Image / RenderPass …） ├── animation/ Animation / AnimationGroup / AnimationManager 及各类 Sampler └── meshshaders/ 网格着色器支持记忆要点：
#include <vsg/all.h>会引入全部核心头；日常开发也可按需只引子模块头（如<vsg/app/Viewer.h>）。
2.4 外部组件库（独立仓库）
核心保持精简，复杂或特定领域的能力放在独立仓库，需额外find_package并链接：
| 组件库 | 职责 | 典型用途 |
|---|---|---|
vsgXchange | 模型与图像格式加载（glTF、OBJ、KTX2、PNG…） | 第 13 章加载 3D 模型 |
vsgImGui | 集成 Dear ImGui 调试界面 | 第 22 章实时参数调节 |
vsgQt | 嵌入 Qt 窗口/控件 | 桌面应用集成 |
vsgUnity | 与 Unity 互操作 | 跨引擎 |
vsgVR | VR/AR 支持 | 头显渲染 |
组件库通过 CMake 的
find_package(vsgXchange REQUIRED)引入，导出目标如vsgXchange::vsgXchange。
2.5 ⚠️ 已并入核心的模块（易踩坑）
根据旧版文档，vsgText与vsgRayTracing曾是独立库，但在当前版本它们已并入核心仓库：
- 文字渲染 →
include/vsg/text/（第 17 章） - 光线追踪 →
include/vsg/raytracing/（进阶）
因此不要再去find_package(vsgText)——直接#include <vsg/text/Text.h>即可，且无需额外链接。
2.6 一条数据的流向
你的代码 └─ 构造场景图(Node/Group/Geometry/StateGroup) └─ Viewer::compile() 把场景图编译成 ├─ RenderGraph (渲染通道组织) └─ CommandGraph (命令缓冲录制) └─ 提交到 Vulkan Device → 呈现到 Window组件库（如vsgXchange）通常在「构造场景图」这一步提供vsg::read()等工厂，把文件解析成vsg::Node子树；其余流程与核心一致。
2.7 小结
- VSG =一个核心库
vsg（单 namespace + 单 CMake targetvsg::vsg）+若干外部组件库； - 核心代码按
nodes / state / commands / app / io / …子模块目录组织，职责清晰； vsgText、vsgRayTracing已并入核心，无需单独安装；真正外挂的是vsgXchange / vsgImGui / vsgQt / vsgUnity等。
2.8 延伸阅读与下一章预告
- 第 3 章《开发环境搭建》：从零编译安装 VSG 与组件库；
- 第 5 章《第一个 VSG 程序》：亲手把上面的「数据流向」跑一遍；
- 第 2.3 节的目录树是后续每章的「地图」——遇到不熟悉的类，先想它属于哪个子模块。
