《OGRE 3D 渲染引擎原理与架构》15.1 最小的 Root 启动

最小的 OGRE 程序从 Root 开始:Root 构造时自动创建 LogManager 与默认日志,把版本号拼成字符串;initialise 要求先选渲染系统,通过 OgreAssert(mActiveRenderer) 断言并置 mIsInitialised。createSceneManager 转发到工厂注册表创建场景管理器。lab 用 C++ 复现这组启动序。

15.1 最小的 Root 启动

前十四章拆完了 OGRE 的各类机制。这一章把它们装回一个最小程序:能启动、能建场景、能转起来。起点是 Root——它的构造和 initialise 定义了引擎从无到有的第一条链。

本章与站内既有内容的分工

helio 系列讲「从零实现引擎」的装配;这里讲真实 OGRE 的装配序。14.3 的 LogManager、12 章的 FrameListener 会在这一章被串进一个完整程序。

Root 构造:自动建日志,拼版本号

Root::Root 构造函数做的事比想象中多——它不只是初始化成员,还顺手搭好了日志与工作队列:

// OgreMain/src/OgreRoot.cpp:Root::Root(v14.6.3 源码摘录,已删减)
    Root::Root(const String& pluginFileName, const String& configFileName,
        const String& logFileName)
      : mQueuedEnd(false)
      , mCurrentSceneManager(NULL)
      , mNextFrame(1)
      ...
      , mIsInitialised(false)
    {
        // superclass will do singleton checking

        // Init
        mActiveRenderer = 0;
        mVersion = StringConverter::toString(OGRE_VERSION_MAJOR) + "." +
            StringConverter::toString(OGRE_VERSION_MINOR) + "." +
            StringConverter::toString(OGRE_VERSION_PATCH) +
            OGRE_VERSION_SUFFIX + " " +
            "(" + OGRE_VERSION_NAME + ")";
        mConfigFileName = configFileName;

        // Create log manager and default log file if there is no log manager yet
        if(!LogManager::getSingletonPtr())
        {
            mLogManager = std::make_unique<LogManager>();
            mLogManager->createLog(logFileName, true, true);
        }
        ...
    }

三个要点:

  • 成员初始化表里 mIsInitialised(false)——构造完还没初始化,这是后续 initialise 的职责;
  • 版本号是拼出来的:mVersion = 大.小.补丁 + 后缀 + "(" + 版本名 + ")"。OGRE v14.6.3 的版本名是 “Tsathoggua”,所以 mVersion 形如 "14.6.3 (Tsathoggua)";
  • 日志自动创建:if(!LogManager::getSingletonPtr())——只有不存在 LogManager 时才新建(对应 14.3 的启动序约定:应用可先建 LogManager 接管日志,Root 检测到就不再覆盖)。

构造函数还有一段创建 WorkQueue 的代码:默认 2 个 worker 线程(Math::Clamp(threadCount, 1, 2)),并在 OGRE_THREAD_SUPPORT 关闭时禁止 worker 访问渲染系统。这些先记住,卷二会展开。

initialise:先选渲染系统

Root::initialise 是真正的「开机」。它的第一步是断言:

// OgreMain/src/OgreRoot.cpp:Root::initialise(v14.6.3 源码摘录,已删减)
    RenderWindow* Root::initialise(bool autoCreateWindow, const String& windowTitle)
    {
        OgreAssert(mActiveRenderer, "Cannot initialise");

        if (!mControllerManager)
            mControllerManager = std::make_unique<ControllerManager>();

        PlatformInformation::log(LogManager::getSingleton().getDefaultLog());
        mActiveRenderer->_initialise();

        // Initialise timer
        mTimer->reset();

        // Init pools
        ConvexBody::_initialisePool();

        mIsInitialised = true;

        if (autoCreateWindow)
        {
            LogManager::getSingleton().logWarning(
                "Root::initialise: autoCreateWindow is deprecated, use createRenderWindow instead");
            auto desc = mActiveRenderer->getRenderWindowDescription();
            desc.name = windowTitle;
            mAutoWindow = createRenderWindow(desc);
        }

        return mAutoWindow;

    }

顺序很讲究:

  1. OgreAssert(mActiveRenderer, "Cannot initialise")——渲染系统必须在先。选渲染系统是 Root 构造之后、initialise 之前由应用/插件完成的(卷一第 3 章讲过插件注册)。
  2. mActiveRenderer->_initialise()——真正的渲染后端初始化(GL/Vulkan/Metal 各做各的)。
  3. mTimer->reset()——计时器归零,帧时间从此刻起算。
  4. mIsInitialised = true——状态翻转。此后 isInitialised() 返回 true,addFrameListener 等 API 才允许调用(头文件里标注「must be called after Root::initialise」)。
  5. autoCreateWindow 已 deprecated——源码注释直接建议改用 createRenderWindow。新程序不会靠 initialise 顺带建窗口,而是自己调用 createRenderWindow。

返回值是自动创建的窗口指针(可能为 NULL)。

createSceneManager:转发到工厂枚举

Root::createSceneManager 本身极薄——真正干活的是内部的 mSceneManagerEnum 工厂枚举:

// OgreMain/src/OgreRoot.cpp:Root::createSceneManager(v14.6.3 源码摘录,已删减)
    SceneManager* Root::createSceneManager(const String& typeName, const String& instanceName)
    {
        return mSceneManagerEnum->createSceneManager(typeName, instanceName);
    }

注意 OgreRoot.h 里的无参重载 createSceneManager() 返回 createSceneManager(SMT_DEFAULT)——即创建「默认场景管理器」。工厂枚举按 typeName 查找已注册的 SceneManagerFactory 并创建实例。这个「枚举 + 工厂」模式是 OGRE 可扩展性的骨架:第三方插件注册自己的工厂,Root 就能创建自定义场景管理器(卷四第 1 章展开)。

源码定位

  • OgreMain/src/OgreRoot.cpp :Root::Root(成员初始化表、mVersion 拼接、if(!LogManager::getSingletonPtr()) 自动建日志)、Root::initialise(OgreAssert(mActiveRenderer)、mIsInitialised=true、autoCreateWindow deprecated)、Root::createSceneManager(转发 mSceneManagerEnum)
  • OgreMain/include/OgreRoot.h :createSceneManager() 无参重载、isInitialised()、initialise(bool, const String&) 声明

上游引用固定到 OGRE v14.6.3 源码 。

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

下面复现 Root 的启动序:自动建日志、initialise 前置断言、场景工厂创建。它与 src/15-1-root-startup.cpp 逐字节一致:

// file: src/15-1-root-startup.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/15-1-root-startup.cpp -o bin/15-1-root-startup && ./bin/15-1-root-startup
//
// 复现 Root 启动序:
//   Root 构造时自动创建 LogManager 与默认日志(对应 OgreRoot.cpp Root::Root);
//   Root::initialise 要求已选渲染系统并置 mIsInitialised(对应 OgreRoot.cpp 492-521);
//   Root::createSceneManager 转发到场景工厂注册表(对应 OgreRoot.cpp 540-543)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <stdexcept>
#include <string>
#include <vector>

namespace ogre_repro {

class Log;

// 对应 LogManager:全引擎单例(简化:只持默认日志)
class LogManager {
 public:
  static LogManager& getSingleton() {
    static LogManager instance;
    return instance;
  }
  Log* defaultLog = nullptr;
};

class Log {
 public:
  std::string mContent;
  void logMessage(const std::string& msg) { mContent += msg + "\n"; }
};

// 场景管理器:类型 + 实例名
class SceneManager {
 public:
  SceneManager(const std::string& typeName, const std::string& name)
      : mTypeName(typeName), mName(name) {}
  std::string mTypeName, mName;
};

// 对应 Root:启动序 + 场景工厂注册表
class Root {
 public:
  Root() : mIsInitialised(false), mActiveRenderer(false) {
    // 对应 Root::Root:若无 LogManager 则自动创建默认日志
    if (LogManager::getSingleton().defaultLog == nullptr)
      LogManager::getSingleton().defaultLog = new Log();
    mLog = LogManager::getSingleton().defaultLog;
  }

  // 对应 Root::initialise:必须先选渲染系统
  void initialise() {
    if (!mActiveRenderer) throw std::runtime_error("no RenderSystem");
    mIsInitialised = true;
    log("OGRE Initialise");
  }
  bool isInitialised() const { return mIsInitialised; }

  // 对应 Root::createSceneManager:按类型从工厂创建
  SceneManager* createSceneManager(const std::string& typeName, const std::string& name) {
    SceneManager* sm = new SceneManager(typeName, name);
    mSceneManagers.push_back(sm);
    return sm;
  }
  SceneManager* getSceneManager(const std::string& name) const {
    for (auto* sm : mSceneManagers)
      if (sm->mName == name) return sm;
    return nullptr;
  }

  void log(const std::string& msg) { mLog->logMessage(msg); }
  const std::string& logContent() const { return mLog->mContent; }

  bool mIsInitialised;
  bool mActiveRenderer;  // 简化:是否已选渲染系统
  std::vector<SceneManager*> mSceneManagers;
  Log* mLog = nullptr;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 构造时自动建默认日志(对应 Root::Root)
  Root root;
  CHECK(root.logContent().empty());

  // 未选渲染系统前 initialise 抛错
  bool threw = false;
  try { root.initialise(); } catch (const std::runtime_error&) { threw = true; }
  CHECK(threw);
  CHECK(!root.isInitialised());

  // 选中渲染系统后再 initialise
  root.mActiveRenderer = true;
  root.initialise();
  CHECK(root.isInitialised());
  CHECK(root.logContent().find("OGRE Initialise") != std::string::npos);

  // createSceneManager 建出场景并可按名取回
  SceneManager* sm = root.createSceneManager("DefaultSceneManager", "Main");
  CHECK(root.getSceneManager("Main") == sm);
  CHECK(sm->mTypeName == "DefaultSceneManager");
  CHECK(root.getSceneManager("Nope") == nullptr);

  return lab::report("15-1 装配:最小的 OGRE 程序(Root 启动)");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 8/8 通过。

小结

  • Root::Root 成员初始化表置 mIsInitialised=false,拼版本号,if(!LogManager::getSingletonPtr()) 自动建日志。
  • Root::initialise 以 OgreAssert(mActiveRenderer, "Cannot initialise") 开始,随后 _initialise() → mTimer->reset() → mIsInitialised=true。
  • autoCreateWindow 已 deprecated,新程序用 createRenderWindow 建窗口。
  • createSceneManager 转发到工厂枚举,无参重载默认建 SMT_DEFAULT。

阅读导航:上一节:14.3 LogManager 单例与监听 · 下一节:15.2 建场景 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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