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
}
两个要点:
install()无条件先跑,initialise()只在mIsInitialised为真时跟着跑。如果插件是在Root::initialise()之前安装的,initialise()会在系统初始化完成时统一补调(Root::_initialisePlugins)。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: 释放动态库
源码定位
OgreMain/src/OgreRoot.cpp:installPlugin(1013-1027)、uninstallPlugin(1029-1043)、loadPlugin(1045-1070)PlugIns/OctreeSceneManager/src/OgreOctreePlugin.cpp:getName(43-46)、install(48-53)、initialise(55-59)、shutdown(61-65)、uninstall(67-74)PlugIns/OctreeSceneManager/include/OgreOctreePlugin.h:OctreePlugin类声明(45-70)PlugIns/OctreeSceneManager/src/OgreOctreeSceneManagerDll.cpp:dllStartPlugin(42-50)、dllStopPlugin(51-55)
上游引用固定到 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 自定义可移动对象 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。