《OGRE 3D 渲染引擎原理与架构》12.3 引擎混合使用

12.3 讲 Root 主循环帧驱动。renderOneFrame fireFrameStarted→updateAllRenderTargets→fireFrameEnded,任一 false 即中断;_fireFrameEnded 后无条件调 processMainThreadTasks;startRendering 直到 queueEndRendering。lab 复现中断,14 项断言。

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 对齐分配器 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图