3.1 OgrePlugin 接口与插件职责
OGRE 的渲染后端、场景管理器类型、编解码器,几乎全是插件。插件系统的契约定义在 OgrePlugin.h,一个抽象类只有五个纯虚方法。先看接口:
// OgreMain/include/OgrePlugin.h:Plugin 类(v14.6.3 教学示意,参照上游同名实现,已删减)
class _OgreExport Plugin : public PluginAlloc
{
public:
Plugin() {}
virtual ~Plugin() {}
/** Get the name of the plugin. */
virtual const String& getName() const = 0;
/** Perform the plugin initial installation sequence. */
virtual void install() = 0;
/** Perform any tasks the plugin needs to perform on full system
initialisation. */
virtual void initialise() = 0;
/** Perform any tasks the plugin needs to perform when the system is shut down. */
virtual void shutdown() = 0;
/** Perform the final plugin uninstallation sequence. */
virtual void uninstall() = 0;
};
五个方法不是五个自由动作,而是一条有约束的生命周期。注释里写得最清楚的分界是 install 与 initialise:
install():只做「不依赖系统初始化」的事,比如注册渲染系统定制。注释明说:此时不能创建任何渲染系统相关的对象;initialise():在系统完全初始化之后调用(Root::initialise或首个窗口创建之后),此时渲染系统功能全部可用,可以建依赖渲染系统的资源;shutdown():系统关停时调用,在所有其他插件(如渲染后端)仍存活时释放资源、解绑自定义对象;uninstall():最后一步,此时无法确定其他插件还活着,不能再碰渲染系统对象。
顺序是一条清晰的链:install → initialise → shutdown → uninstall。这套四段式生命周期是 OGRE 插件与「普通接口」的本质区别:插件不是「被调用」,而是被宿主在正确时机唤醒。
宿主如何执行生命周期
OgreRoot.cpp 的 installPlugin 与 uninstallPlugin 把生命周期串起来,并处理一个关键分支——系统当前是否已初始化:
// OgreMain/src/OgreRoot.cpp:installPlugin/uninstallPlugin(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");
}
关键在 if (mIsInitialised) 这个守卫:
- 插件在引擎启动前安装(构造期
loadPlugins)→ 只调install(),initialise()留给窗口建好后的oneTimePostWindowInit; - 插件在引擎已初始化后安装(运行时动态加载)→
install()后立即补initialise(); - 卸载时若已初始化 → 先
shutdown()再uninstall(); - 从头到尾有日志:「Installing plugin: xxx」/「Plugin successfully installed」。
这个分支正是「晚注册插件」能无缝工作的原因:同一个 installPlugin 入口,根据系统状态自动补全生命周期。
插件能改什么:注册的钩子
插件的 install() 里通常做三件事,全部通过单例管理器注册:
- 注册渲染后端:
Root::getSingleton().addRenderSystem(new RenderSystemVulkan()); - 注册场景管理器类型:
SceneManagerEnumerator里加OctreeSceneManagerFactory; - 注册资源编解码器:
Codec::registerCodec。
三者共同的模式:插件的职责是把实现注册进核心的单例,核心只保留抽象与调度。这也是本书卷一反复出现的「核心抽象 + 插件实现」结构。
源码定位
OgreMain/include/OgrePlugin.h:Plugin 抽象类(getName/install/initialise/shutdown/uninstall)OgreMain/src/OgreRoot.cpp:Root::installPlugin、Root::uninstallPlugin、mIsInitialised分支OgreMain/src/OgreRoot.cpp:oneTimePostWindowInit里的initialisePlugins()
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 Plugin 生命周期与「系统未初始化不 initialise」分支。它与 src/03-1-plugin-interface.cpp 逐字节一致:
// file: src/03-1-plugin-interface.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/03-1-plugin-interface.cpp -o bin/03-1-plugin-interface && ./bin/03-1-plugin-interface
//
// 复现 OgrePlugin.h 的 Plugin 接口与安装/卸载生命周期:
// install → initialise → shutdown → uninstall
// 其中 initialise 仅在系统已初始化时调用。独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 OgrePlugin.h:Plugin 抽象接口
class Plugin {
public:
virtual ~Plugin() = default;
virtual const std::string& getName() const = 0;
virtual void install() = 0;
virtual void initialise() = 0;
virtual void shutdown() = 0;
virtual void uninstall() = 0;
};
// 记录生命周期事件的插件
class LifecyclePlugin : public Plugin {
public:
std::vector<std::string>& log;
explicit LifecyclePlugin(std::vector<std::string>& log) : log(log) {}
const std::string& getName() const override {
static const std::string n = "RTSS";
return n;
}
void install() override { log.push_back("install"); }
void initialise() override { log.push_back("initialise"); }
void shutdown() override { log.push_back("shutdown"); }
void uninstall() override { log.push_back("uninstall"); }
};
// 对应 OgreRoot.cpp:installPlugin / uninstallPlugin
class ManagerRepro {
public:
std::vector<std::string> log;
bool initialised = false;
void install(Plugin& p) {
log.push_back("Installing plugin: " + p.getName());
p.install();
if (initialised) p.initialise();
log.push_back("Plugin successfully installed");
}
void uninstall(Plugin& p) {
log.push_back("Uninstalling plugin: " + p.getName());
if (initialised) p.shutdown();
p.uninstall();
log.push_back("Plugin successfully uninstalled");
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
ManagerRepro m;
LifecyclePlugin plugin(m.log);
// 系统未初始化:只 install,不 initialise
m.install(plugin);
CHECK(m.log[0] == "Installing plugin: RTSS");
CHECK(m.log[1] == "install");
CHECK(m.log.back() == "Plugin successfully installed");
CHECK_EQ(m.log.size(), 3u);
m.log.clear();
// 系统已初始化:install 后紧跟 initialise
m.initialised = true;
m.install(plugin);
CHECK(m.log[1] == "install");
CHECK(m.log[2] == "initialise");
CHECK_EQ(m.log.size(), 4u);
// 卸载:先 shutdown 再 uninstall
m.uninstall(plugin);
CHECK(m.log[5] == "shutdown");
CHECK(m.log[6] == "uninstall");
CHECK(m.log[7] == "Plugin successfully uninstalled");
return lab::report("03-1 插件系统:Plugin 接口");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 10/10 通过。
小结
- Plugin 只有五个纯虚方法,构成 install → initialise → shutdown → uninstall 生命周期。
- install 只做核心层可做的事;initialise 等窗口建好、渲染系统可用才做。
mIsInitialised守卫让晚注册的插件也能被补全生命周期。- 插件做的事本质是「向核心单例注册实现」,核心只保留抽象与调度。
阅读导航:上一节:2.3 Root 析构与清理顺序 · 下一节:3.2 OgreDynLib 动态加载与解析 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。