12.3 引擎混合使用
本章把 OGRE 当作组件之一嵌进更大的程序:外部资源流(10.3)、网格与场景工具(11 章)、第三方物理(12.1)、场景导入(12.2)都要汇聚到一个帧循环里。这个帧循环就是 Root::startRendering:它无限调用 renderOneFrame,直到某帧返回 false(帧监听器中断)或 queueEndRendering() 被调用。理解中断语义与 _fireFrameEnded 末尾的 processMainThreadTasks,就能安全地混合渲染、物理步进与异步资源加载。
本章与站内既有内容的分工
10.2 讲 WorkQueue 主线程队列本身;本节看 Root 在每帧末尾如何泵出该队列,以及帧监听器在 _fireFrameStarted/_fireFrameEnded 中的位置。lab 复现三阶段帧循环与各中断点。
renderOneFrame:三阶段串联
renderOneFrame 把一帧切成三段,任一段返回 false 就中断本帧:先 _fireFrameStarted() 通知所有帧监听器,再 _updateAllRenderTargets() 更新所有渲染目标,最后 _fireFrameEnded() 收尾。三段的布尔返回是整个帧循环的控制信号:
// OgreMain/src/OgreRoot.cpp:Root::renderOneFrame(v14.6.3 源码摘录,已删减)
bool Root::renderOneFrame(void)
{
if(!_fireFrameStarted())
return false;
if (!_updateAllRenderTargets())
return false;
return _fireFrameEnded();
}
startRendering 就是这段循环的驱动者:清事件时间、复位 mQueuedEnd,然后 while(!mQueuedEnd) 反复 renderOneFrame(),任一帧返回 false 立即 break:
// OgreMain/src/OgreRoot.cpp:Root::startRendering(v14.6.3 源码摘录,已删减)
void Root::startRendering(void)
{
OgreAssert(mActiveRenderer, "no RenderSystem");
mActiveRenderer->_initRenderTargets();
// Clear event times
clearEventTimes();
// Infinite loop, until broken out of by frame listeners
// or break out by calling queueEndRendering()
mQueuedEnd = false;
while( !mQueuedEnd )
{
if (!renderOneFrame())
break;
}
}
_fireFrameStarted 与 _fireFrameEnded:监听器与主线程任务
_fireFrameStarted 逐个通知 mFrameListeners,任一 frameStarted 返回 false 立即中断本帧(返回 false);它还先同步增删的监听器列表。注意它不调用 processMainThreadTasks——那是收尾阶段的职责:
// OgreMain/src/OgreRoot.cpp:Root::_fireFrameStarted(v14.6.3 源码摘录,已删减)
bool Root::_fireFrameStarted(FrameEvent& evt)
{
OgreProfileBeginGroup("Frame", OGREPROF_GENERAL);
_syncAddedRemovedFrameListeners();
// Tell all listeners
for (auto *l : mFrameListeners)
{
if(mRemovedFrameListeners.find(l) != mRemovedFrameListeners.end())
continue;
if (!l->frameStarted(evt))
return false;
}
return true;
}
_fireFrameEnded 先通知所有监听器(任一 frameEnded 返回 false 会置 ret = false 并 break,但继续往下走),然后释放本帧临时缓冲,最后无条件调用 mWorkQueue->processMainThreadTasks() 泵出主线程任务队列——即使有监听器中断,主线程任务也照样被处理。返回 ret 作为本帧收尾的成败:
// OgreMain/src/OgreRoot.cpp:Root::_fireFrameEnded(v14.6.3 源码摘录,已删减)
bool Root::_fireFrameEnded(FrameEvent& evt)
{
_syncAddedRemovedFrameListeners();
// Tell all listeners
bool ret = true;
for (auto *l : mFrameListeners)
{
if(mRemovedFrameListeners.find(l) != mRemovedFrameListeners.end())
continue;
if (!l->frameEnded(evt))
{
ret = false;
break;
}
}
// Tell buffer manager to free temp buffers used this frame
if (HardwareBufferManager::getSingletonPtr())
HardwareBufferManager::getSingleton()._releaseBufferCopies();
// Tell the queue to process responses
mWorkQueue->processMainThreadTasks();
OgreProfileEndGroup("Frame", OGREPROF_GENERAL);
return ret;
}
中断语义:哪一段停了会怎样
三种退出路径对应三种状态:
frameStarted返回 false:该帧立即中断,updateAllRenderTargets不被执行(渲染目标不更新),frameEnded不被调用。frameEnded返回 false:该帧渲染目标已经更新,但renderOneFrame返回 false,startRendering退出;processMainThreadTasks仍执行。queueEndRendering():置位mQueuedEnd,当前帧完整走完后下一次while条件检查退出。
lab 用一个可配置的 TestListener 验证这三条路径,并断言 frameEnded 后主线程任务无论中断与否都按 FIFO 处理。
帧中段先更新启用自动更新的活动目标,再派发 frameRenderingQueued,随后交换缓冲并处理 LOD 事件。queued 返回 false 时依然执行交换和 LOD,随后跳过 frameEnded。如果 frameEnded 自身返回 false,Root 仍会释放临时缓冲并处理主线程任务。完整调用顺序见卷二 14.1
。
固定步进与渲染帧的交接
宿主维护模拟时钟与输入队列,场景节点接收同步后的状态。renderOneFrame 驱动渲染与其回调,返回 false 后由宿主决定是否进入关停。
用宿主记录模拟步数、提交变换和渲染返回值。关停前按资源及物理组件的引用顺序处理待完成任务。
源码定位
OgreMain/src/OgreRoot.cpp:Root::startRendering(734-752 行)OgreMain/src/OgreRoot.cpp:Root::renderOneFrame(754-763 行)OgreMain/src/OgreRoot.cpp:Root::_fireFrameStarted(595-611 行)OgreMain/src/OgreRoot.cpp:Root::_fireFrameEnded(632-660 行)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
EngineRootRepro 复现三阶段帧循环、监听器中断与主线程任务泵出;TestListener 可配置 startStopAt/endStopAt/endQueue 以覆盖三种退出路径。它与 src/12-3-engine-integration.cpp 逐字节一致:
// file: src/12-3-engine-integration.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/12-3-engine-integration.cpp -o bin/12-3-engine-integration && ./bin/12-3-engine-integration
//
// 复现 Root 主循环(OgreMain/src/OgreRoot.cpp 734-763 的 startRendering/
// renderOneFrame、595-611 的 _fireFrameStarted、632-660 的 _fireFrameEnded):
// renderOneFrame 依次 fireFrameStarted→updateAllRenderTargets→
// fireFrameEnded,任一返回 false 即中断;_fireFrameEnded 在监听器之后
// 无条件调用 mWorkQueue->processMainThreadTasks();startRendering 无限
// 循环直到 queueEndRendering 或某帧中断。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <deque>
#include <functional>
#include <string>
#include <utility>
#include <vector>
namespace ogre_repro {
struct FrameEventRepro {
uint32_t frameNumber = 0;
};
// 对应 Ogre::FrameListener
struct FrameListenerRepro {
virtual ~FrameListenerRepro() = default;
virtual bool frameStarted(FrameEventRepro&) { return true; }
virtual bool frameEnded(FrameEventRepro&) { return true; }
virtual bool frameRenderingQueued(FrameEventRepro&) { return true; }
};
// 对应 Root 的主循环骨架(瘦身)
class EngineRootRepro {
public:
std::vector<FrameListenerRepro*> mFrameListeners;
bool mQueuedEnd = false;
uint32_t mNextFrame = 0;
uint32_t mRenderTargetUpdates = 0;
std::deque<std::function<void()>> mMainTasks;
void addFrameListener(FrameListenerRepro* l) { mFrameListeners.push_back(l); }
void queueEndRendering() { mQueuedEnd = true; }
// 对应 _fireFrameStarted 595-611
bool fireFrameStarted(FrameEventRepro& evt) {
for (auto* l : mFrameListeners)
if (!l->frameStarted(evt))
return false;
return true;
}
// 对应 _updateAllRenderTargets 的简化
bool updateAllRenderTargets() {
++mRenderTargetUpdates;
return true;
}
// 对应 _fireFrameEnded 632-660:监听器之后无条件处理主线程任务
bool fireFrameEnded(FrameEventRepro& evt) {
bool ret = true;
for (auto* l : mFrameListeners)
if (!l->frameEnded(evt)) {
ret = false;
break;
}
processMainThreadTasks(); // 对应 655 行 mWorkQueue->processMainThreadTasks()
return ret;
}
void processMainThreadTasks() {
while (!mMainTasks.empty()) {
std::function<void()> t = std::move(mMainTasks.front());
mMainTasks.pop_front();
t();
}
}
// 对应 renderOneFrame 754-763
bool renderOneFrame() {
FrameEventRepro evt;
evt.frameNumber = mNextFrame;
++mNextFrame;
if (!fireFrameStarted(evt))
return false;
if (!updateAllRenderTargets())
return false;
return fireFrameEnded(evt);
}
// 对应 startRendering 734-752(maxFrames 用于有限测试)
uint32_t startRendering(uint32_t maxFrames) {
mQueuedEnd = false;
uint32_t frames = 0;
while (!mQueuedEnd) {
if (!renderOneFrame())
break;
++frames;
if (maxFrames && frames >= maxFrames)
mQueuedEnd = true;
}
return frames;
}
};
// 可配置的测试监听器
struct TestListener : FrameListenerRepro {
uint32_t startedCalls = 0, endedCalls = 0;
uint32_t startStopAt = 0; // 第 N 次 frameStarted 返回 false(0=从不)
uint32_t endStopAt = 0; // 第 N 次 frameEnded 返回 false
bool endQueue = false; // 每次 frameEnded 都 queueEndRendering
EngineRootRepro* root = nullptr;
bool frameStarted(FrameEventRepro&) override {
++startedCalls;
return !(startStopAt && startedCalls == startStopAt);
}
bool frameEnded(FrameEventRepro&) override {
++endedCalls;
if (endQueue && root)
root->queueEndRendering();
return !(endStopAt && endedCalls == endStopAt);
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 基础:3 帧内每帧完整走过三个阶段
EngineRootRepro root;
const uint32_t n = root.startRendering(3);
CHECK_EQ(n, 3u);
CHECK_EQ(root.mRenderTargetUpdates, 3u);
CHECK_EQ(root.mNextFrame, 3u);
// frameStarted 返回 false:该帧立即中断,不更新渲染目标
EngineRootRepro r2;
TestListener l2;
l2.startStopAt = 1;
r2.addFrameListener(&l2);
CHECK_EQ(r2.startRendering(100), 0u);
CHECK_EQ(l2.startedCalls, 1u);
CHECK_EQ(r2.mRenderTargetUpdates, 0u);
// frameEnded 返回 false:该帧渲染目标已更新但不计入完成帧,循环退出
EngineRootRepro r3;
TestListener l3;
l3.endStopAt = 3;
r3.addFrameListener(&l3);
CHECK_EQ(r3.startRendering(100), 2u); // 前两帧完整,第三帧中断
CHECK_EQ(l3.endedCalls, 3u);
CHECK_EQ(r3.mRenderTargetUpdates, 3u); // 中断的那帧也更新了渲染目标
// queueEndRendering:帧结束后置位,下一轮循环退出
EngineRootRepro r4;
TestListener l4;
l4.endQueue = true;
l4.root = &r4;
r4.addFrameListener(&l4);
CHECK_EQ(r4.startRendering(100), 1u);
CHECK(r4.mQueuedEnd);
// 主线程任务:fireFrameEnded 在监听器之后按 FIFO 处理
EngineRootRepro r5;
std::string order;
r5.mMainTasks.push_back([&order]() { order += "A"; });
r5.mMainTasks.push_back([&order]() { order += "B"; });
r5.startRendering(1);
CHECK(order == "AB");
// 监听器中断时主线程任务仍被处理(源码 655 行无条件调用)
EngineRootRepro r6;
TestListener l6;
l6.endStopAt = 1;
r6.addFrameListener(&l6);
r6.mMainTasks.push_back([&order]() { order += "C"; });
CHECK(!r6.renderOneFrame());
CHECK(order == "ABC");
return lab::report("12.3 引擎混合使用");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 14/14 通过。
小结
renderOneFrame依次fireFrameStarted → updateAllRenderTargets → fireFrameEnded,任一段返回 false 即中断本帧。startRendering无限循环直到queueEndRendering()置位或某帧返回 false。frameStarted中断发生在渲染目标更新前;frameEnded中断发生在渲染目标更新后。_fireFrameEnded在监听器之后无条件调用processMainThreadTasks,中断不阻止主线程任务泵出。- 混合使用引擎时,物理步进、异步资源回填等都可挂在帧监听器里,主线程任务天然收敛到每帧末尾。
阅读导航:上一节:12.2 内容导入集成 · 下一节:13.1 对齐分配器 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。