12.1 FrameListener 与帧事件
游戏循环每帧要驱动「逻辑更新 → 渲染 → 收尾」。OGRE 让用户通过 FrameListener 挂进这个循环——不侵入 Root 的代码。这一节看帧事件的两个结构与监听器接口的设计。
本章与站内既有内容的分工
helio 自研引擎的主循环讲「如何自己实现循环」;本节讲 OGRE 里「循环如何对外暴露回调」。帧时序细节在 12.3,这里先看接口本身。
FrameEvent:帧事件的载荷
OgreFrameListener.h 开头定义 FrameEvent——它只装两个时间值:
// OgreMain/include/OgreFrameListener.h:struct FrameEvent(v14.6.3 源码摘录,已删减)
/** Struct containing information about a frame event.
*/
struct FrameEvent
{
/** Elapsed time in seconds since the last event.
This gives you time between frame start & frame end,
and between frame end and next frame start.
@note This may not be the elapsed time but the average
elapsed time between recently fired events.
*/
Real timeSinceLastEvent;
/** Elapsed time in seconds since the last event of the same type,
i.e. time for a complete frame.
@note This may not be the elapsed time but the average
elapsed time between recently fired events of the same type.
*/
Real timeSinceLastFrame;
};
两个字段的区别:
timeSinceLastEvent:距上个任意事件的时间——比如帧开始到帧结束、帧结束到下一帧开始之间的间隔;timeSinceLastFrame:距上个同类型事件的时间,即完整一帧的时长。
注释特别提醒:这两个值「可能不是真实间隔,而是最近若干次事件的平均间隔」——引擎用平滑值避免单帧抖动。
FrameListener:适配器类
FrameListener 的注释解释了它为什么不是抽象类:
// OgreMain/include/OgreFrameListener.h:class FrameListener 注释(v14.6.3 源码摘录,已删减)
class _OgreExport FrameListener
{
/*
Note that this could have been an abstract class, but I made
the explicit choice not to do this, because I wanted to give
people the option of only implementing the methods they wanted,
rather than having to create 'do nothing' implementations for
those they weren't interested in. As such this class follows
the 'Adapter' classes in Java rather than pure interfaces.
*/
三个回调默认全部返回 true,子类只需覆盖关心的那一个:
// OgreMain/include/OgreFrameListener.h:三个回调(v14.6.3 源码摘录,已删减)
virtual bool frameStarted(const FrameEvent& evt)
{ (void)evt; return true; }
...
virtual bool frameRenderingQueued(const FrameEvent& evt)
{ (void)evt; return true; }
...
virtual bool frameEnded(const FrameEvent& evt)
{ (void)evt; return true; }
三个回调的语义(注释原文):
- frameStarted:帧即将开始渲染,发生在任何渲染目标更新之前;返回
false中止渲染、退出循环; - frameRenderingQueued:所有渲染目标的渲染命令已提交、但缓冲还没交换——此时 CPU 空闲,适合做每帧处理(改动下一帧才生效);
- frameEnded:一帧完全渲染完、缓冲已切换;返回
false跳出循环。
适配器 vs 抽象类
| 抽象类(纯虚) | FrameListener 的做法 | |
|---|---|---|
| 子类必须实现 | 全部回调 | 只实现需要的 |
| 未实现的回调 | 强制写空实现 | 继承默认 return true |
| 灵感来源 | 纯接口 | Java 的 Adapter 类 |
bool 返回值是三级控制:监听器既能「观察」(返回 true 继续),也能「喊停」(返回 false 中止整个渲染循环)——这比 void 回调多了中止语义,也比异常中断轻量。
源码定位
OgreMain/include/OgreFrameListener.h:struct FrameEvent、class FrameListener(三个回调 + 「Adapter classes」注释)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 FrameEvent 与适配器模式的用法。它与 src/12-1-frame-event.cpp 逐字节一致:
// file: src/12-1-frame-event.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/12-1-frame-event.cpp -o bin/12-1-frame-event && ./bin/12-1-frame-event
//
// 复现 FrameListener 与 FrameEvent:
// FrameEvent 含 timeSinceLastEvent / timeSinceLastFrame 两个字段
// (对应 OgreFrameListener.h 的 struct FrameEvent);
// FrameListener 是适配器类:三个回调默认返回 true,子类只覆盖需要的
// (对应 OgreFrameListener.h 注释 "Adapter classes in Java")。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cmath>
#include <string>
namespace ogre_repro {
// 对应 Ogre::FrameEvent
struct FrameEvent {
float timeSinceLastEvent = 0; // 距上个事件的时间(秒)
float timeSinceLastFrame = 0; // 距上个同类型事件(完整一帧)
};
// 对应 Ogre::FrameListener:适配器模式,默认全部返回 true
class FrameListener {
public:
virtual bool frameStarted(const FrameEvent& evt) { (void)evt; return true; }
virtual bool frameRenderingQueued(const FrameEvent& evt) { (void)evt; return true; }
virtual bool frameEnded(const FrameEvent& evt) { (void)evt; return true; }
virtual ~FrameListener() {}
};
// 一个具体监听器:只覆盖需要的回调(每帧累积时间)
class CameraController : public FrameListener {
public:
bool frameRenderingQueued(const FrameEvent& evt) override {
// 渲染命令已提交、缓冲交换前做每帧更新
updates += evt.timeSinceLastFrame;
return true;
}
float updates = 0;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 适配器:不覆盖任何回调也能用(默认全返回 true)
FrameListener plain;
FrameEvent evt;
evt.timeSinceLastEvent = 0.016f;
evt.timeSinceLastFrame = 0.016f;
CHECK(plain.frameStarted(evt));
CHECK(plain.frameRenderingQueued(evt));
CHECK(plain.frameEnded(evt));
// 子类只覆盖 frameRenderingQueued,其余仍走默认
CameraController cam;
CHECK(cam.frameStarted(evt));
CHECK(cam.frameRenderingQueued(evt));
CHECK(cam.frameEnded(evt));
// 清零后再测:三帧后 updates 累计 3 * timeSinceLastFrame(浮点累计用 epsilon)
cam.updates = 0;
FrameEvent f2;
f2.timeSinceLastFrame = 0.033f;
for (int i = 0; i < 3; ++i) cam.frameRenderingQueued(f2);
CHECK(std::abs(cam.updates - 0.033f * 3) < 1e-6);
return lab::report("12-1 事件与监听:FrameListener 与帧事件");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 7/7 通过。
小结
FrameEvent只装两个时间值:距上个事件、距上个同类型事件(完整一帧)。FrameListener是适配器类:三个回调默认返回 true,子类只覆盖需要的。- 回调返回
false可中止渲染循环——监听器既观察也喊停。 frameRenderingQueued在命令提交、缓冲交换前触发,是 CPU 做每帧处理的最佳时机。
阅读导航:上一节:11.3 Camera 与投影 · 下一节:12.2 注册与派发顺序 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。