2.2 Root 启动:选后端、建场景、跑一帧
Root 构造完成只代表管理器齐了,引擎还没真正「醒」。一个典型程序接下来做三件事:
- 查找或从配置恢复渲染后端。显式选择时,用
getRenderSystemByName查找,确认返回值后调用setRenderSystem; root->initialise(false)初始化,然后调用createRenderWindow。自动开窗参数已弃用;sm = root->createSceneManager()建场景管理器,往里放内容;- 进入渲染循环,每帧调
renderOneFrame()。
场景管理器:createSceneManager
场景管理器不是随便 new 出来的,而是经过 SceneManagerEnumerator 按类型名创建。OgreRoot.h 里接口很薄:
// OgreMain/include/OgreRoot.h:createSceneManager(v14.6.3 教学示意,参照上游同名实现,已删减)
SceneManager* createSceneManager() { return createSceneManager(SMT_DEFAULT); }
...
SceneManager* createSceneManager(const String& typeName, const String& instan...
默认是 SMT_DEFAULT(通用场景),插件可以注册 OctreeSceneManager 等类型名。场景管理器由 Root 统一托管、统一销毁,用户拿到的只是指针。
渲染一帧:三段式管线
renderOneFrame 是整个渲染循环的心脏。OgreRoot.cpp 里它只有十几行,但结构极其清晰:
// OgreMain/src/OgreRoot.cpp:renderOneFrame(v14.6.3 源码摘录)
bool Root::renderOneFrame(Real timeSinceLastFrame)
{
FrameEvent evt;
evt.timeSinceLastFrame = timeSinceLastFrame;
unsigned long now = mTimer->getMilliseconds();
evt.timeSinceLastEvent = calculateEventTime(now, FETT_ANY);
if(!_fireFrameStarted(evt))
return false;
if (!_updateAllRenderTargets(evt))
return false;
now = mTimer->getMilliseconds();
evt.timeSinceLastEvent = calculateEventTime(now, FETT_ANY);
return _fireFrameEnded(evt);
}
三段:_fireFrameStarted(evt) → _updateAllRenderTargets(evt) → _fireFrameEnded(evt)。任何一步返回 false 都提前终止。FrameEvent 携带两个时间:距上一帧的时间(驱动动画与逻辑)和距上一事件的时间。calculateEventTime 用毫秒级定时器累计。
为什么返回 bool 而不是抛异常?因为帧监听器(FrameListener)需要「否决」能力——比如窗口关闭、用户按下退出键,监听器在 frameStarted 返回 false 就能让渲染循环体面退出。这在第 12 章展开。
更新渲染目标:一帧的真正渲染
_updateAllRenderTargets(evt) 遍历所有渲染目标(窗口、渲染到纹理),对每个目标执行场景渲染。这是帧管线里最重的一段:RenderSystem::_beginFrame → 遍历 RenderQueue 渲染 → _endFrame。它之所以独立成一步,是为了支持多窗口。所有符合条件的目标更新后,Root 先调用 frameRenderingQueued,再交换缓冲并处理 LOD 事件。queued 返回 false 时依然完成交换和 LOD,随后跳过 frameEnded。
整个帧管线可以用一条链概括:
FrameEvent(时间戳)
└→ frameStarted —— 监听器可否决(返回 false 终止)
└→ 更新所有渲染目标 —— 每个窗口/纹理各自渲染场景
└→ frameEnded —— 监听器可否决
从启动到循环:完整时序
一个最小 OGRE 程序的生命周期时序:
Root(plugins.cfg, ogre.cfg, Ogre.log) // 构造:管理器+插件+横幅
└→ root->showConfigDialog() 或 setRenderSystem(...) // 选后端
└→ root->initialise(false) → createRenderWindow(...) // 初始化后端并显式创建窗口
└→ root->createSceneManager() // 建场景
└→ 注册 FrameListener
└→ while(条件) root->renderOneFrame(...) // 循环
└→ root->shutdown() / ~Root() // 清理
第 15 章会把这个骨架完整展开。
帧中段先更新启用自动更新的活动目标,再派发 frameRenderingQueued,随后交换缓冲并处理 LOD 事件。queued 返回 false 时依然执行交换和 LOD,随后跳过 frameEnded。如果 frameEnded 自身返回 false,Root 仍会释放临时缓冲并处理主线程任务。完整调用顺序见卷二 14.1
。
后端选择与首窗初始化
sequenceDiagram
participant App as 宿主
participant R as Root
participant RS as RenderSystem
participant P as 已安装插件
App->>R: 构造并加载插件配置
P->>R: 登记可用渲染后端
App->>R: getRenderSystemByName
alt 没找到后端
R-->>App: 空指针,报告缺少后端
else 找到后端
App->>R: setRenderSystem
App->>R: initialise(false)
R->>RS: _initialise
App->>R: createRenderWindow
R->>RS: _createRenderWindow
opt 首个窗口
R->>R: oneTimePostWindowInit
R->>P: initialise
R->>R: 标记 primary window
end
end
源码定位
OgreMain/include/OgreRoot.h:createSceneManager、initialiseOgreMain/src/OgreRoot.cpp:renderOneFrame、_updateAllRenderTargets、_fireFrameStarted、_fireFrameEndedOgreMain/include/OgreFrameListener.h:frameStarted/frameEnded回调接口
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 renderOneFrame 的三段管线与监听器否决语义。它与 src/02-2-render-one-frame.cpp 逐字节一致:
// file: src/02-2-render-one-frame.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/02-2-render-one-frame.cpp -o bin/02-2-render-one-frame && ./bin/02-2-render-one-frame
//
// 复现 OgreRoot::renderOneFrame 的帧管线:
// _fireFrameStarted → _updateAllRenderTargets → _fireFrameEnded
// 帧监听器可以否决帧开始(返回 false 即终止本帧)。独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <string>
#include <vector>
namespace ogre_repro {
struct FrameEvent {
double timeSinceLastFrame = 0.0;
double timeSinceLastEvent = 0.0;
};
using Listener = bool (*)(const FrameEvent&);
class RootRepro {
public:
std::vector<std::string> sequence;
void addListener(Listener l) { listeners.push_back(l); }
// 对应 OgreRoot.cpp:renderOneFrame
bool renderOneFrame(double timeSinceLastFrame) {
FrameEvent evt;
evt.timeSinceLastFrame = timeSinceLastFrame;
evt.timeSinceLastEvent = timeSinceLastFrame; // 简化:同源计时
if (!fireFrameStarted(evt)) return false;
if (!updateAllRenderTargets(evt)) return false;
return fireFrameEnded(evt);
}
private:
std::vector<Listener> listeners;
bool fireFrameStarted(const FrameEvent& e) {
sequence.push_back("frameStarted");
for (auto l : listeners)
if (!l(e)) return false;
return true;
}
bool updateAllRenderTargets(const FrameEvent& e) {
sequence.push_back("updateAllRenderTargets");
return true;
}
bool fireFrameEnded(const FrameEvent& e) {
sequence.push_back("frameEnded");
for (auto l : listeners)
if (!l(e)) return false;
return true;
}
};
bool neverVeto(const FrameEvent&) { return true; }
bool vetoAtSecondFrame(const FrameEvent&) { return false; }
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
RootRepro root;
root.addListener(neverVeto);
bool ok = root.renderOneFrame(16.7);
CHECK(ok);
CHECK(root.sequence.size() == 3);
CHECK(root.sequence[0] == "frameStarted");
CHECK(root.sequence[1] == "updateAllRenderTargets");
CHECK(root.sequence[2] == "frameEnded");
// 帧开始被否决:整帧终止,不渲染
RootRepro vetoRoot;
vetoRoot.addListener(vetoAtSecondFrame);
bool ok2 = vetoRoot.renderOneFrame(16.7);
CHECK(!ok2);
CHECK(vetoRoot.sequence.size() == 1);
CHECK(vetoRoot.sequence[0] == "frameStarted");
std::printf("帧序列:%s → %s → %s\n", root.sequence[0].c_str(),
root.sequence[1].c_str(), root.sequence[2].c_str());
return lab::report("02-2 Root 启动与 renderOneFrame");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 8/8 通过。
小结
- 启动三件事:选后端 → 初始化+建窗口 → 建场景管理器 → 跑帧循环。
renderOneFrame是固定三段管线:frameStarted → 更新渲染目标 → frameEnded。- 监听器可在 frameStarted/frameEnded 返回 false 否决,整帧提前终止。
- 多渲染目标共享同一帧事件时间戳,各自完成场景渲染。
阅读导航:上一节:2.1 Root 单例与构造顺序 · 下一节:2.3 Root 析构与清理顺序 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。