《OGRE 3D 渲染引擎原理与架构》1.2 v14.6.3 源码目录地图

v14.6.3 的源码包顶层是 OgreMain、Components、RenderSystems、PlugIns、Samples、Tools 六大目录。OgreMain 是唯一的核心库,219 个 .h 文件装下场景管理、资源系统、渲染抽象。CMakeLists.txt 用固定顺序 add_subdirectory 组装整棵树。本节梳理阅读地图,lab 用 C++ 复现目录清单并断言计数。

1.2 v14.6.3 源码目录地图

拿到 OGRE 源码包,第一件事是建立地图。v14.6.3 的根目录不是一个大而全的引擎,而是一棵分得很清楚的树:一个核心库、一堆可选组件、多个渲染后端、多个场景插件。CMakeLists.txt 从第 459 行开始,用固定顺序把这些目录一个接一个加进构建:

# CMakeLists.txt:add_subdirectory 顺序(v14.6.3 源码摘录)
# Setup OgreMain project
add_subdirectory(OgreMain)

# Setup RenderSystems
add_subdirectory(RenderSystems)

# Setup Plugins
add_subdirectory(PlugIns)

# Setup Components
add_subdirectory(Components)

# Setup tests (before samples so that PlayPen is included in browser)
add_subdirectory(Tests)

# Setup samples
add_subdirectory(Samples)

# Setup command-line tools
if (OGRE_BUILD_TOOLS)
  add_subdirectory(Tools)
endif ()

顺序本身有讲究:OgreMain 第一个编译,因为它是一切的基础;Tests 放在 Samples 之前,是为了让 PlayPen 测试程序先于示例链接;Tools 用 OGRE_BUILD_TOOLS 开关保护,可以整个裁掉。

六张地图:每层目录管什么

OgreMain 是唯一不可裁的核心库,OgreMain/include 下有 219 个 .h 文件,全书九成主题都在这:场景管理(OgreSceneManager.h)、场景节点(OgreSceneNode.h)、资源系统(OgreResourceManager.h、OgreArchive.h)、网格与材质(OgreMesh.h、OgreMaterial.h)、渲染抽象(OgreRenderSystem.h、OgreRenderQueue.h)、数学库(OgreMath.h、OgreVector3.h、OgreQuaternion.h)。头文件与实现分离:声明在 include/,.cpp 在 src/。

RenderSystems 是渲染后端层,每个目录实现一个底层图形 API:Vulkan、GL3Plus(OpenGL 3+)、GL、GLES2、Metal、Direct3D11、Direct3D9,还有一个嵌入式友好的 Tiny。本书卷二专门讲这层的抽象与各后端。

PlugIns 是场景与编解码插件:OctreeSceneManager(八叉树场景)、PCZSceneManager(遮挡剔除场景)、BSPSceneManager(BSP 场景)、Assimp(模型导入)、FreeImageCodec(图片编解码)、DotScene(XML 场景)、ParticleFX(粒子扩展)、EXRCodec、STBICodec、GLSLang。

Components 是可选高层组件:Bites(示例用的高层框架)、Overlay(UI 覆盖层)、Terrain(地形)、Paging(分页大世界)、RTShaderSystem(实时着色器系统)、Volume(体积渲染)、MeshLodGenerator(网格 LOD)、Bullet(物理桥接)。

Samples 与 Tools:Samples 是官方示例与示例媒体;Tools 是离线工具,MeshUpgrader(旧格式升级)、XMLConverter(XML↔二进制网格)、AssimpConverter(模型转 OGRE 格式)。

这套分工有一个贯穿全书的规律:核心只放抽象与生命周期,实现放在渲染后端,扩展性内容全部插件化。你会在卷二看到 RenderSystem 抽象类如何被六个后端各自继承,在卷三看到场景查询如何被 OctreeSceneManager 加速。

阅读优先级:从 219 个 .h 文件里挑主干

对第一次读源码的人,219 个 .h 文件容易淹没。本卷给你一条主干阅读路径,按依赖方向推进:

  1. OgrePrerequisites.h、OgrePlatform.h——类型与平台宏,一切的地基;
  2. OgreMath.h、OgreVector3.h、OgreQuaternion.h——数学库;
  3. OgreLogManager.h、OgreException.h——日志与异常,调试的窗口;
  4. OgreRoot.h——引擎单例与生命周期;
  5. OgreSceneManager.h、OgreSceneNode.h、OgreMovableObject.h——场景三件套;
  6. OgreResourceManager.h、OgreArchive.h——资源系统;
  7. OgreMesh.h、OgreMaterial.h——内容数据结构;
  8. OgreRenderSystem.h、OgreRenderQueue.h——渲染抽象。

本卷 15 章就按这个顺序展开,每章 3 节逐层解析。

源码定位

  • CMakeLists.txt :add_subdirectory 顺序(OgreMain→RenderSystems→PlugIns→Components→Tests→Samples→Tools)
  • OgreMain/include/:219 个 .h 文件清单(OgreRoot.h、OgreSceneManager.h、OgreMath.h、OgreMesh.h、OgreMaterial.h、OgreRenderSystem.h、OgreRenderQueue.h 等)
  • 顶层目录:OgreMain、Components、RenderSystems、PlugIns、Samples、Tools、Tests

以上均为 v14.6.3 实际目录清单核对。

可运行产物:C++ 最小验证

下面复现目录地图的结构与计数,断言 OgreMain 头文件数为 219、顶层目录顺序固定。它与 src/01-2-source-tree-map.cpp 逐字节一致:

// file: src/01-2-source-tree-map.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-2-source-tree-map.cpp -o bin/01-2-source-tree-map && ./bin/01-2-source-tree-map
//
// 复现 v14.6.3 源码目录地图:OgreMain 头文件计数与顶层目录结构。
// 数字来自 GitHub OGRECave/ogre v14.6.3 实际目录清单。独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <string>
#include <vector>

namespace ogre_repro {

struct Dir {
  std::string name;
  int headers;  // OgreMain/include 下的头文件数
};

// v14.6.3 实测:OgreMain/include 共 219 个 .h 文件
const std::vector<Dir>& tree() {
  static const std::vector<Dir> dirs = {
      {"OgreMain", 219},        // 核心库,全部头文件
      {"Components", 0},        // 可选组件(Bites/Overlay/Terrain/Paging…)
      {"RenderSystems", 0},     // 渲染后端(Vulkan/GL3Plus/Metal/D3D11…)
      {"PlugIns", 0},           // 场景插件与编解码器(Octree/PCZ/Assimp…)
      {"Samples", 0},           // 官方示例
      {"Tools", 0},             // 离线工具(MeshUpgrader/XMLConverter…)
      {"Tests", 0},             // 测试
  };
  return dirs;
}

// 头文件数与归档加载顺序无关,只用于阅读地图的排序校验
int totalHeaders() {
  int sum = 0;
  for (const auto& d : tree()) sum += d.headers;
  return sum;
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  CHECK_EQ(tree().front().name, "OgreMain");
  CHECK_EQ(tree().front().headers, 219);
  CHECK_EQ(totalHeaders(), 219);

  // 顶层目录出现在源码包中的固定顺序
  std::vector<std::string> names;
  for (const auto& d : tree()) names.push_back(d.name);
  CHECK_EQ(names[3], "PlugIns");
  CHECK_EQ(names[4], "Samples");

  for (const auto& d : tree())
    std::printf("%-16s %d\n", d.name.c_str(), d.headers);

  return lab::report("01-2 阅读路线:源码目录地图");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 5/5 通过,打印七行目录计数。

小结

  • 源码包是「一个核心库 + 多个可选组件 + 多个渲染后端 + 多个插件」的模块化布局。
  • OgreMain 不可裁,219 个 .h 文件承载全书九成主题;其余目录靠 add_subdirectory 按序并入。
  • 渲染后端与场景插件全部插件化,这是 OGRE「核心抽象 + 后端实现」的总体架构。
  • 主干阅读路径:Prerequisites → 数学 → 日志异常 → Root → 场景 → 资源 → 网格材质 → 渲染抽象。

阅读导航:上一节:1.1 历史与定位 · 下一节:1.3 CMake 构建系统与版本宏 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图