《OGRE 3D 渲染引擎原理与架构》1.1 插件接口

插件接口是 OGRE 一切扩展的入口:Plugin 定义五个纯虚方法 getName/install/initialise/shutdown/uninstall,形成「安装/系统初始化」与「系统关停/卸载」两对钩子;Root::installPlugin 注册,loadPlugin 从 DLL 触发 dllStartPlugin。lab 复现插件生命周期调用顺序。

1.1 插件接口

OGRE 从第一行源码起就为插件设计:根对象、场景管理器、渲染后端、粒子特效、编解码器,几乎每一项「自定义能力」都要通过插件这个入口进入引擎。卷一讲过 Root::installPlugin 怎么把插件装进 mPlugins 列表,这一节换到插件那一侧——看写一个插件的人必须实现什么。Plugin 是 OgreMain 里最薄也最关键的抽象类之一:五个纯虚方法,定义了一个扩展从装进引擎到被踢出去的完整生命周期。

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

卷一 3.x 从 Root 的视角讲了插件系统(Root::loadPlugin、mPlugins 管理、dllStartPlugin 入口);本卷第 1 章换到插件作者视角。卷一讲「Root 怎么装插件」,这里讲「插件要长什么样、被装时按什么顺序收到哪些回调」,并一直延伸到第 2、3 章的自定义对象与资源。

Plugin:五个虚方法

OgrePlugin.h 里的 Plugin 抽象类干净利落——纯虚方法五个,注释把每个钩子的时机讲得很细:

// OgreMain/include/OgrePlugin.h:Plugin(v14.6.3 源码摘录,已删减)
    class _OgreExport Plugin : public PluginAlloc
    {
    public:
        Plugin() {}
        virtual ~Plugin() {}

        /** Get the name of the plugin. 
        @remarks An implementation must be supplied for this method to uniquely
            identify the plugin.
        */
        virtual const String& getName() const = 0;

        /** Perform the plugin initial installation sequence. 
        @remarks An implementation must be supplied for this method. It must perform
            the startup tasks necessary to install any rendersystem customisations 
            or anything else that is not dependent on system initialisation, ie
            only dependent on the core of Ogre. It must not perform any
            operations that would create rendersystem-specific objects at this stage,
            that should be done in initialise().
        */
        virtual void install() = 0;

        /** Perform any tasks the plugin needs to perform on full system
            initialisation.
        @remarks An implementation must be supplied for this method. It is called 
            just after the system is fully initialised (either after Root::initialise
            if a window is created then, or after the first window is created)
            and therefore all rendersystem functionality is available at this
            time. You can use this hook to create any resources which are 
            dependent on a rendersystem or have rendersystem-specific implementations.
        */
        virtual void initialise() = 0;

        /** Perform any tasks the plugin needs to perform when the system is shut down.
        @remarks An implementation must be supplied for this method.
        This method is called just before key parts of the system are unloaded, 
        such as rendersystems being shut down. You should use this hook to free up 
        resources and decouple custom objects from the OGRE system, whilst all the
        instances of other plugins (e.g. rendersystems) still exist.
        */
        virtual void shutdown() = 0;

        /** Perform the final plugin uninstallation sequence. 
        @remarks An implementation must be supplied for this method. It must perform
            the cleanup tasks which haven't already been performed in shutdown()
            (e.g. final deletion of custom instances, if you kept them around in case
            the system was reinitialised). At this stage you cannot be sure what other
            plugins are still loaded or active. It must therefore not perform any
            operations that would reference any rendersystem-specific objects - those
            should have been sorted out in the 'shutdown' method.
        */
        virtual void uninstall() = 0;
    };

五个钩子按时间轴可以画成两对:install/uninstall 是一对「注册级」操作,initialise/shutdown 是一对「系统级」操作。

钩子时机能做什么
install()插件被装进引擎注册只依赖 OGRE 核心的东西:新的 SceneManagerFactory、MovableObjectFactory、RenderSystem 实例
initialise()系统完全初始化后(第一个窗口创建后)创建依赖渲染系统的资源,此时渲染后端完全可用
shutdown()系统关停、渲染系统卸载之前解耦自定义对象、释放依赖其他插件的资源,其他插件实例还在
uninstall()插件被彻底移除做 shutdown() 没做完的收尾(如删除自定义实例),此时不确定其他插件是否还在

注释特意强调:install 阶段不能创建渲染系统专属对象——渲染后端那时还没起来;那些工作推迟到 initialise。反过来 uninstall 阶段不能引用渲染系统专属对象——它们在 shutdown 已经处理了。这两个约束把「注册」和「用渲染系统」严格隔开。

Root 怎么驱动这五个钩子

插件不会自己跑,是 Root 在装/卸时调用。OgreRoot.h 把四个入口方法排在一起:

// OgreMain/include/OgreRoot.h:loadPlugin / unloadPlugin / installPlugin / uninstallPlugin(v14.6.3 教学示意,参照上游同名实现,已删减)
        void loadPlugin(const String& pluginName);

        /** Manually unloads a Plugin contained in a DLL / DSO.
        ...
        */
        void unloadPlugin(const String& pluginName);

        /** Install a new plugin.
        ...
            You should only call this method directly
            if your plugin is not in a DLL that could otherwise be loaded with
            loadPlugin, since the DLL function dllStartPlugin should call this
            method when the DLL is loaded.
        */
        void installPlugin(Plugin* plugin);

        /** Uninstall an existing plugin.
        ...
        */
        void uninstallPlugin(Plugin* plugin);

两条进引擎的路:

  • 静态链接:你在程序里 new 一个 Plugin 子类,直接 Root::installPlugin(plugin)。
  • 动态链接(DLL/DSO):Root::loadPlugin(name) 加载动态库后,调用库导出的 dllStartPlugin();这个全局函数内部实例化插件并调用 Root::installPlugin。卸载对称:unloadPlugin → dllStopPlugin() → uninstallPlugin。

Root::installPlugin 的实现会先把插件塞进 mPlugins 列表,然后依次调 install() 与 initialise()(install 立刻调,initialise 若系统未初始化则等到窗口创建后)。Root 析构时自动 uninstallPlugin 所有还挂着的插件——前提是插件实例在那一刻仍然有效,这正是头文件注释里那句「Plugin instance must remain valid until the Plugin is uninstalled」的含义。

源码定位

  • OgreMain/include/OgrePlugin.h :Plugin 类(79-131)、getName(89)、install(99)、initialise(110)、shutdown(119)、uninstall(130)
  • OgreMain/include/OgreRoot.h :loadPlugins(163)、loadPlugin(625)、unloadPlugin(636)、installPlugin(648)、uninstallPlugin(658)、getInstalledPlugins(661)

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

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

下面用纯 C++ 复现插件生命周期:抽象 Plugin 接口的五个钩子、Root 的 installPlugin/uninstallPlugin 对钩子的驱动顺序。它与 src/01-1-plugin-interface.cpp 逐字节一致:

// file: src/01-1-plugin-interface.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-1-plugin-interface.cpp -o bin/01-1-plugin-interface && ./bin/01-1-plugin-interface
//
// 复现插件接口生命周期(对应 OgreMain/include/OgrePlugin.h 79-131 的 Plugin、
//   OgreMain/include/OgreRoot.h 648/658 的 installPlugin/uninstallPlugin):
//   Plugin 定义 getName/install/initialise/shutdown/uninstall 五个钩子;
//   Root::installPlugin 调 install() 再 initialise();uninstallPlugin 调 shutdown() 再 uninstall();
//   install 只能做核心级注册、initialise 才有渲染系统资源(由阶段标记模拟)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 OgrePlugin.h 79-:Plugin 抽象接口
class Plugin {
 public:
  virtual ~Plugin() {}
  virtual const std::string& getName() const = 0;
  virtual void install() = 0;       // 核心级注册,无渲染系统
  virtual void initialise() = 0;    // 系统初始化后,可碰渲染系统
  virtual void shutdown() = 0;      // 系统关停前,其他插件还在
  virtual void uninstall() = 0;     // 彻底卸载,不碰渲染系统对象
};

// 记录调用序的假插件
class FakePlugin : public Plugin {
 public:
  explicit FakePlugin(std::string name) : mName(std::move(name)) {}
  const std::string& getName() const override { return mName; }
  void install() override { mCalls.push_back("install"); }
  void initialise() override { mCalls.push_back("initialise"); }
  void shutdown() override { mCalls.push_back("shutdown"); }
  void uninstall() override { mCalls.push_back("uninstall"); }

  std::string mName;
  std::vector<std::string> mCalls;
};

// 对应 OgreRoot.h 648/658:简化 Root,驱动生命周期
class SimpleRoot {
 public:
  void installPlugin(Plugin* p) {
    mPlugins.push_back(p);
    p->install();
    p->initialise();  // 简化:假定系统已初始化
  }
  void uninstallPlugin(Plugin* p) {
    p->shutdown();
    p->uninstall();
    for (auto it = mPlugins.begin(); it != mPlugins.end(); ++it)
      if (*it == p) { mPlugins.erase(it); break; }
  }
  std::vector<Plugin*> mPlugins;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  FakePlugin p("SamplePlugin");
  SimpleRoot root;

  // 未安装前:插件列表为空
  CHECK_EQ(root.mPlugins.size(), size_t(0));
  CHECK_EQ(p.mCalls.size(), size_t(0));

  // installPlugin:注册 + install + initialise(两阶段钩子都触发)
  root.installPlugin(&p);
  CHECK_EQ(root.mPlugins.size(), size_t(1));
  CHECK_EQ(root.mPlugins[0]->getName(), "SamplePlugin");
  CHECK_EQ(p.mCalls.size(), size_t(2));
  CHECK(p.mCalls[0] == "install");
  CHECK(p.mCalls[1] == "initialise");

  // uninstallPlugin:shutdown + uninstall,并从列表移除
  root.uninstallPlugin(&p);
  CHECK(p.mCalls[2] == "shutdown");
  CHECK(p.mCalls[3] == "uninstall");
  CHECK_EQ(p.mCalls.size(), size_t(4));
  CHECK_EQ(root.mPlugins.size(), size_t(0));

  // 再次安装同名插件:OGRE 不查重,列表累加(v14.6.3 语义),钩子照常触发
  root.installPlugin(&p);
  CHECK_EQ(root.mPlugins.size(), size_t(1));
  CHECK_EQ(p.mCalls.size(), size_t(6));
  CHECK(p.mCalls[4] == "install");
  CHECK(p.mCalls[5] == "initialise");

  // 一个从未安装的插件也能 uninstall:shutdown/uninstall 照常触发(源码不校验)
  FakePlugin q("GhostPlugin");
  root.uninstallPlugin(&q);
  CHECK_EQ(q.mCalls.size(), size_t(2));
  CHECK(q.mCalls[0] == "shutdown");
  CHECK(q.mCalls[1] == "uninstall");

  // 生命周期顺序不可逆:install 必在 initialise 前,shutdown 必在 uninstall 前
  CHECK(p.mCalls[0] != p.mCalls[3]);

  return lab::report("1.1 插件接口");
}

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

小结

  • Plugin 五个纯虚方法定义插件生命周期:getName + install/initialise/shutdown/uninstall。
  • 两对钩子语义不同:install/uninstall 是注册级,initialise/shutdown 是系统级。
  • install 阶段不能创建渲染系统专属对象,uninstall 阶段不能引用它们。
  • 静态链接走 installPlugin,动态链接走 loadPlugin → dllStartPlugin → installPlugin。
  • Root 析构自动卸载所有还挂着的插件,插件实例须在卸载前保持有效。

阅读导航:上一节:卷三目录 · 下一节:1.2 动态库加载 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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