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 动态库加载 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。