《OGRE 3D 渲染引擎原理与架构》1.3 自定义插件骨架

写一个自定义插件就是实现四个钩子:install 创建工厂对象、initialise 注册进 Root、shutdown 反注册、uninstall 销毁;Root::installPlugin 用 mIsInitialised 决定是否立即调 initialise,loadPlugin 约定取 dllStartPlugin 符号。lab 复现 OctreePlugin 式骨架的注册与生命周期。

1.3 自定义插件骨架

1.1 讲了接口、1.2 讲了动态库,现在把两者接到真实代码上。OGRE 自带的插件——OctreeSceneManager、ParticleFX、GLSLang——都遵循同一个四步骨架:install 创建对象、initialise 注册、shutdown 反注册、uninstall 销毁。这一节解剖 OctreePlugin 这个真实插件,再补上 Root::installPlugin 和 loadPlugin 怎么驱动它。

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

卷一 3.x 讲了 Root 侧的插件加载与注册机制;这里是插件作者侧的最小可写骨架,直接以 OGRE 自带 OctreePlugin 为范本,是第 2、3 章写自定义 MovableObject/Resource 的承接口。

Root 怎么驱动一个插件

Root::installPlugin 的真实实现很短,关键在一个 mIsInitialised 判断——插件被装进引擎时,系统可能还没初始化渲染后端,所以 initialise() 要推迟:

// OgreMain/src/OgreRoot.cpp:Root::installPlugin / uninstallPlugin / loadPlugin(v14.6.3 源码摘录,已删减)
    void Root::installPlugin(Plugin* plugin)
    {
        LogManager::getSingleton().logMessage("Installing plugin: " + plugin->getName());

        mPlugins.push_back(plugin);
        plugin->install();

        // if rendersystem is already initialised, call rendersystem init too
        if (mIsInitialised)
        {
            plugin->initialise();
        }

        LogManager::getSingleton().logMessage("Plugin successfully installed");
    }
    //---------------------------------------------------------------------
    void Root::uninstallPlugin(Plugin* plugin)
    {
        LogManager::getSingleton().logMessage("Uninstalling plugin: " + plugin->getName());
        PluginInstanceList::iterator i =
            std::find(mPlugins.begin(), mPlugins.end(), plugin);
        if (i != mPlugins.end())
        {
            if (mIsInitialised)
                plugin->shutdown();
            plugin->uninstall();
            mPlugins.erase(i);
        }
        LogManager::getSingleton().logMessage("Plugin successfully uninstalled");

    }
    //-----------------------------------------------------------------------
    void Root::loadPlugin(const String& pluginName)
    {
#if OGRE_PLATFORM != OGRE_PLATFORM_EMSCRIPTEN
        // Load plugin library
        DynLib* lib = DynLibManager::getSingleton().load( pluginName );
        // Store for later unload
        // Check for existence, because if called 2+ times DynLibManager returns existing entry
        if (std::find(mPluginLibs.begin(), mPluginLibs.end(), lib) == mPluginLibs.end())
        {
            mPluginLibs.push_back(lib);

            // Call startup function
            ...
            DLL_START_PLUGIN pFunc = (DLL_START_PLUGIN)lib->getSymbol("dllStartPlugin");

            if (!pFunc)
                OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, "Cannot find symbol dllStartPlugin in library " + pluginName,
                    "Root::loadPlugin");

            // This must call installPlugin
            pFunc();
        }
#endif
    }

两个要点:

  1. install() 无条件先跑,initialise() 只在 mIsInitialised 为真时跟着跑。如果插件是在 Root::initialise() 之前安装的,initialise() 会在系统初始化完成时统一补调(Root::_initialisePlugins)。
  2. loadPlugin 用符号名约定:从动态库取 dllStartPlugin 函数,找到就调用;找不到抛 ERR_ITEM_NOT_FOUND。所以任何要动态加载的插件,都必须导出 dllStartPlugin 函数,并且它内部必须调用 Root::installPlugin——否则插件只是被加载,并没有装进引擎。

OctreePlugin:四步骨架范本

PlugIns/OctreeSceneManager 的插件实现只有几十行,是四步骨架的最小范本:

// PlugIns/OctreeSceneManager/src/OgreOctreePlugin.cpp:OctreePlugin(v14.6.3 源码摘录,已删减)
    const String sPluginName = "Octree Scene Manager";
    //---------------------------------------------------------------------
    OctreePlugin::OctreePlugin()
        :mOctreeSMFactory(0)
    {

    }
    //---------------------------------------------------------------------
    const String& OctreePlugin::getName() const
    {
        return sPluginName;
    }
    //---------------------------------------------------------------------
    void OctreePlugin::install()
    {
        // Create objects
        mOctreeSMFactory = OGRE_NEW OctreeSceneManagerFactory();

    }
    //---------------------------------------------------------------------
    void OctreePlugin::initialise()
    {
        // Register
        Root::getSingleton().addSceneManagerFactory(mOctreeSMFactory);
    }
    //---------------------------------------------------------------------
    void OctreePlugin::shutdown()
    {
        // Unregister
        Root::getSingleton().removeSceneManagerFactory(mOctreeSMFactory);
    }
    //---------------------------------------------------------------------
    void OctreePlugin::uninstall()
    {
        // destroy 
        OGRE_DELETE mOctreeSMFactory;
        mOctreeSMFactory = 0;


    }

四个钩子各司其职,恰好落在 1.1 的契约里:

钩子OctreePlugin 做什么时机原则
install()OGRE_NEW OctreeSceneManagerFactory()——创建工厂对象只做依赖核心的事,不碰 Root 的注册表
initialise()Root::addSceneManagerFactory(factory)——注册系统初始化后,注册才安全
shutdown()Root::removeSceneManagerFactory(factory)——反注册系统关停前,其他插件还在
uninstall()OGRE_DELETE factory——销毁最后清理自定义实例

SceneManagerFactory 是插件给场景管理器的入口:注册后 Root::createSceneManager("OctreeSceneManager", ...) 就能造出这个类型的场景管理器。这也解释了为什么 install 不能注册——Root 的 mSceneManagerFactories 注册表要求在系统稳定时改动,而 initialise 正是那个时机。写完插件,dllStartPlugin 入口在另一个文件 OgreOctreeSceneManagerDll.cpp——每个可动态加载的插件都必须导出这对函数,Root::loadPlugin 靠同名符号把它们接进引擎:

// PlugIns/OctreeSceneManager/src/OgreOctreeSceneManagerDll.cpp:dllStartPlugin / dllStopPlugin(v14.6.3 源码摘录,已删减)
    extern "C" void _OgreOctreePluginExport dllStartPlugin( void )
    {
        // Create new scene manager
        octreePlugin = OGRE_NEW OctreePlugin();

        // Register
        Root::getSingleton().installPlugin(octreePlugin);

    }
    extern "C" void _OgreOctreePluginExport dllStopPlugin( void )
    {
        Root::getSingleton().uninstallPlugin(octreePlugin);
        OGRE_DELETE octreePlugin;
    }

这里 octreePlugin 是本文件内一个 static 指针,持有插件实例跨 dllStartPlugin/dllStopPlugin 存活。加载侧:loadPlugin 取 dllStartPlugin 调用 → 实例化 OctreePlugin → installPlugin;卸载侧:unloadPlugin 取 dllStopPlugin 调用 → uninstallPlugin + 删除实例。静态链接则不需要这对 DLL 函数,直接 installPlugin 即可。

加载库、登记工厂与卸载

动态库提供 dllStartPlugin 和 dllStopPlugin。Plugin 对象持有工厂。Root 安装时登记它,SceneManager 通过工厂创建对象。对象实例销毁后,插件注销工厂并释放动态库中的对象。

原生插件样例 验证两次完整安装、创建、销毁、撤销、卸载循环。保留实例会使卸载后的析构调用跨出库的寿命。

原生插件的加载与撤销

sequenceDiagram
  participant H as 宿主
  participant R as Root
  participant P as 动态插件
  participant S as SceneManager
  H->>R: loadPlugin
  R->>P: dllStartPlugin
  P->>R: installPlugin 并登记工厂
  H->>S: createMovableObject
  S->>R: 依据类型查找工厂
  H->>S: destroyMovableObject
  S->>P: 工厂销毁实例
  H->>R: unloadPlugin
  R->>P: dllStopPlugin 撤销工厂
  R->>R: 释放动态库

源码定位

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

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

下面用纯 C++ 复现 OctreePlugin 式骨架:工厂创建/注册/反注册/销毁四步,以及 Root 在 mIsInitialised 两种状态下的驱动差异。它与 src/01-3-plugin-skeleton.cpp 逐字节一致:

// file: src/01-3-plugin-skeleton.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-3-plugin-skeleton.cpp -o bin/01-3-plugin-skeleton && ./bin/01-3-plugin-skeleton
//
// 复现自定义插件骨架(对应 PlugIns/OctreeSceneManager/src/OgreOctreePlugin.cpp 43-74 的
//   OctreePlugin、OgreMain/src/OgreRoot.cpp 1013-1043 的 installPlugin/uninstallPlugin):
//   install 创建工厂、initialise 注册、shutdown 反注册、uninstall 销毁;
//   Root::installPlugin 在 mIsInitialised 为真时才立即调 initialise,否则推迟;
//   uninstallPlugin 若系统已初始化先 shutdown 再 uninstall。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

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

namespace ogre_repro {

// 对应 SceneManagerFactory:一个能造场景管理器的工厂
class SceneManagerFactory {
 public:
  explicit SceneManagerFactory(std::string typeName) : mTypeName(std::move(typeName)) {}
  const std::string& getTypeName() const { return mTypeName; }
  std::string mTypeName;
};

// 对应 OctreePlugin(OgreOctreePlugin.cpp 43-74):四步骨架
class OctreePlugin {
 public:
  explicit OctreePlugin(std::string name) : mName(std::move(name)) {}
  const std::string& getName() const { return mName; }

  // install:创建工厂对象,不注册
  void install() {
    mFactory = new SceneManagerFactory("OctreeSceneManager");
    mCalls.push_back("install");
  }
  // initialise:注册进 Root
  void initialise() {
    mRegistered = true;
    mCalls.push_back("initialise");
  }
  // shutdown:反注册
  void shutdown() {
    mRegistered = false;
    mCalls.push_back("shutdown");
  }
  // uninstall:销毁工厂
  void uninstall() {
    delete mFactory;
    mFactory = nullptr;
    mCalls.push_back("uninstall");
  }

  bool isRegistered() const { return mRegistered; }
  SceneManagerFactory* getFactory() const { return mFactory; }

  std::string mName;
  SceneManagerFactory* mFactory = nullptr;
  bool mRegistered = false;
  std::vector<std::string> mCalls;
};

// 对应 OgreRoot.cpp 1013-:简化 Root,含 mIsInitialised
class SimpleRoot {
 public:
  explicit SimpleRoot(bool initialised) : mIsInitialised(initialised) {}
  void installPlugin(OctreePlugin* p) {
    mPlugins.push_back(p);
    p->install();
    if (mIsInitialised) p->initialise();
  }
  void uninstallPlugin(OctreePlugin* p) {
    if (mIsInitialised) p->shutdown();
    p->uninstall();
    for (auto it = mPlugins.begin(); it != mPlugins.end(); ++it)
      if (*it == p) { mPlugins.erase(it); break; }
  }
  bool mIsInitialised;
  std::vector<OctreePlugin*> mPlugins;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 系统已初始化:install + initialise 都触发
  SimpleRoot root(true);
  OctreePlugin p("Octree Scene Manager");
  root.installPlugin(&p);
  CHECK(p.mFactory != nullptr);
  CHECK(p.isRegistered());
  CHECK_EQ(p.mCalls.size(), size_t(2));
  CHECK(p.mCalls[0] == "install");
  CHECK(p.mCalls[1] == "initialise");
  CHECK_EQ(root.mPlugins.size(), size_t(1));

  // 系统未初始化:install 触发,initialise 推迟
  SimpleRoot cold(false);
  OctreePlugin q("Octree Scene Manager");
  cold.installPlugin(&q);
  CHECK_EQ(q.mCalls.size(), size_t(1));
  CHECK(q.mCalls[0] == "install");
  CHECK(!q.isRegistered());

  // 卸载:已初始化先 shutdown 再 uninstall
  root.uninstallPlugin(&p);
  CHECK(p.mCalls[2] == "shutdown");
  CHECK(p.mCalls[3] == "uninstall");
  CHECK(p.mFactory == nullptr);
  CHECK_EQ(root.mPlugins.size(), size_t(0));

  // 未初始化的卸载:跳过 shutdown,直接 uninstall
  cold.uninstallPlugin(&q);
  CHECK_EQ(q.mCalls.size(), size_t(2));  // install, uninstall
  CHECK(q.mCalls[1] == "uninstall");
  CHECK(!q.isRegistered());
  CHECK(q.mFactory == nullptr);

  return lab::report("1.3 自定义插件骨架");
}

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

小结

  • 自定义插件四步骨架:install 创建、initialise 注册、shutdown 反注册、uninstall 销毁。
  • Root::installPlugin 无条件先调 install,只有 mIsInitialised 为真才立即补调 initialise。
  • loadPlugin 从动态库取 dllStartPlugin 符号,找不到抛 ERR_ITEM_NOT_FOUND。
  • 动态加载的插件必须导出 dllStartPlugin/dllStopPlugin,静态链接直接 installPlugin。
  • OctreePlugin 是「注册一个 SceneManagerFactory」的最小范本,第 2 章自定义 MovableObject 复用同一骨架。

阅读导航:上一节:1.2 动态库加载 · 下一节:2.1 自定义可移动对象 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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