《OGRE 3D 渲染引擎原理与架构》7.1 Bites 应用上下文

Bites 的 ApplicationContextBase 封装应用启动流程:initApp 依次 createRoot、oneTimeConfig、setup,setup 里 createWindow 建主窗口、locateResources 与 loadResources 加载资源并把自己注册为帧监听。lab 复现初始化状态机、窗口列表与 getRenderWindow 首窗口语义。

7.1 Bites 应用上下文

写一个 OGRE 示例最啰嗦的部分是样板:建 Root、读配置、选渲染系统、建窗口、定位资源、加载资源。Bites 的 ApplicationContextBase 把这些收进一个类,子类只需要覆写少数几个钩子。这一节看它的初始化状态机与窗口管理。

本章与站内既有内容的分工

卷一 1.x/2.x 讲过 Root 的启动顺序与资源组;这一节的 ApplicationContextBase 是构建在它们之上的「应用级样板」:把 Root 生命周期、窗口创建、资源定位串成固定顺序,并通过 FrameListener 接入渲染循环。7.3 的 Sample/SamplePlugin 又在这层之上再加一层。

上下文类:把 Root 包起来

ApplicationContextBase 继承 Ogre::FrameListener——上下文本身就是一个帧监听,可以在每帧钩子 pollEvents()。它持有的核心状态是 mRoot、mWindows(窗口对列表)、mInputListeners(输入监听器集合):

// Components/Bites/include/OgreApplicationContextBase.h:ApplicationContextBase(v14.6.3 源码摘录,已删减)
    class _OgreBitesExport ApplicationContextBase : public Ogre::FrameListener
    {
    public:
        explicit ApplicationContextBase(const Ogre::String& appName = "Ogre3D");
...
        Ogre::RenderWindow* getRenderWindow() const
        {
            return mWindows.empty() ? NULL : mWindows[0].render;
        }

        Ogre::Root* getRoot() const {
            return mRoot;
        }
...
        void initApp();
        void closeApp();
...
        bool frameStarted(const Ogre::FrameEvent& evt) override {
            pollEvents();
            return true;
        }
...
        virtual void setup();
        virtual void createRoot();
        virtual bool oneTimeConfig();
...
        virtual void locateResources();
        virtual void loadResources();
...
        virtual void pollEvents();
...
        virtual NativeWindowPair
        createWindow(const Ogre::String& name, uint32_t w = 0, uint32_t h = 0,
                     Ogre::NameValuePairList miscParams = Ogre::NameValuePairList());
...
    protected:
        Ogre::OverlaySystem* mOverlaySystem;  // Overlay system

        Ogre::FileSystemLayer* mFSLayer; // File system abstraction layer
        Ogre::Root* mRoot;              // OGRE root
...
        Ogre::String mAppName;

        typedef std::vector<NativeWindowPair> WindowList;
        WindowList mWindows; // all windows
...
    };

NativeWindowPair 把「OGRE 渲染窗口」与「平台原生窗口」配对:render 是 Ogre::RenderWindow*,native 是 SDL_Window*(Android 上是 ANativeWindow*)。getRenderWindow() 永远返回列表首元素——主窗口是 0 号。

initApp:固定顺序的状态机

initApp() 把启动串成三步,任一步失败(比如 oneTimeConfig() 用户取消了配置对话框)就中止:

// Components/Bites/src/OgreApplicationContextBase.cpp:ApplicationContextBase::initApp(v14.6.3 源码摘录,已删减)
void ApplicationContextBase::initApp()
{
    createRoot();
    if (!oneTimeConfig()) return;

#if OGRE_PLATFORM != OGRE_PLATFORM_ANDROID
    // if the context was reconfigured, set requested renderer
    if (!mFirstRun) mRoot->setRenderSystem(mRoot->getRenderSystemByName(mNextRenderer));
#endif

    setup();
...
}

createRoot() 里 mRoot = OGRE_NEW Ogre::Root(pluginsPath, ...) 并 new 出 OverlaySystem;oneTimeConfig() 在无可用渲染系统时记错误返回 false,否则尝试 restoreConfig(),失败则弹配置对话框:

// Components/Bites/src/OgreApplicationContextBase.cpp:ApplicationContextBase::oneTimeConfig(v14.6.3 源码摘录,已删减)
bool ApplicationContextBase::oneTimeConfig()
{
    if(mRoot->getAvailableRenderers().empty())
    {
        Ogre::LogManager::getSingleton().logError("No RenderSystems available");
        return false;
    }
...
    if (!mRoot->restoreConfig()) {
        return mRoot->showConfigDialog(OgreBites::getNativeConfigDialog());
    }
...
    return true;
}

setup:建窗口、定位资源、进渲染循环

setup() 把初始化做完:初始化 Root、建主窗口、定位并加载资源,最后把自己注册为帧监听:

// Components/Bites/src/OgreApplicationContextBase.cpp:ApplicationContextBase::setup(v14.6.3 源码摘录,已删减)
void ApplicationContextBase::setup()
{
    mRoot->initialise(false);
    createWindow(mAppName);

    locateResources();
    initialiseRTShaderSystem();
    loadResources();

    // adds context as listener to process context-level (above the sample level) events
    mRoot->addFrameListener(this);
}

createWindow() 的关键是:第一个窗口自己建,后续窗口复用上下文(currentGLContext = "true"),并且把 RenderWindowDescription 的默认参数合进 miscParams,最终 mRoot->createRenderWindow(p):

// Components/Bites/src/OgreApplicationContextBase.cpp:ApplicationContextBase::createWindow(v14.6.3 源码摘录,已删减)
NativeWindowPair ApplicationContextBase::createWindow(const Ogre::String& name, Ogre::uint32 w, Ogre::uint32 h, Ogre::NameValuePairList miscParams)
{
    NativeWindowPair ret = {NULL, NULL};

    if(!mWindows.empty())
    {
        // additional windows should reuse the context
        miscParams["currentGLContext"] = "true";
    }

    auto p = mRoot->getRenderSystem()->getRenderWindowDescription();
    miscParams.insert(p.miscParams.begin(), p.miscParams.end());
    p.miscParams = miscParams;
    p.name = name;

    if(w > 0 && h > 0)
    {
        p.width = w;
        p.height= h;
    }

    ret.render = mRoot->createRenderWindow(p);

    mWindows.push_back(ret);

    WindowEventUtilities::_addRenderWindow(ret.render);

    return ret;
}

注意这里的 ret.native 在 ApplicationContextBase 实现里没有赋值——它由平台子类(ApplicationContextSDL::createWindow)先 SDL_CreateWindow 再取窗口系统信息填上,OGRE 渲染窗口通过 externalWindowHandle 挂在原生窗口上。locateResources() 解析 resources.cfg(缺省回退到默认媒体目录),loadResources() 一次性 initialiseAllResourceGroups()。之后 mRoot->startRendering() 进入渲染循环,上下文作为帧监听在每帧开头 pollEvents()。

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现应用上下文的初始化状态机与窗口管理:initApp 的 createRoot/oneTimeConfig/setup 顺序、createWindow 维护 WindowList、getRenderWindow 取首窗口、无渲染系统时启动中断。它与 src/ogre-ext-07-1-bites-application-context.cpp 逐字节一致:

// file: src/ogre-ext-07-1-bites-application-context.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-07-1-bites-application-context.cpp -o bin/ogre-ext-07-1-bites-application-context && ./bin/ogre-ext-07-1-bites-application-context
//
// 复现 ApplicationContextBase 的初始化状态机与窗口管理
// (对应 OgreApplicationContextBase.h 87-325、OgreApplicationContextBase.cpp 59-79、171-182、374-402):
//   initApp = createRoot + oneTimeConfig + setup;
//   setup = createWindow + locateResources + loadResources + 注册为 FrameListener;
//   NativeWindowPair{render, native} 组成 WindowList,getRenderWindow 返回首窗口。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <cstddef>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 NativeWindowPair(OgreApplicationContextBase.h 77-81)
struct NativeWindowPair {
  uint32_t render;   // 简化:渲染窗口 id
  uintptr_t native;  // 简化:原生窗口句柄
};

// 对应 ApplicationContextBase(OgreApplicationContextBase.h 87-)
class ApplicationContextBase {
 public:
  // initApp(OgreApplicationContextBase.cpp 59-79)
  bool initApp() {
    createRoot();
    if (!oneTimeConfig()) return false;
    setup();
    return true;
  }
  void createRoot() { mRootCreated = true; }
  // oneTimeConfig(OgreApplicationContextBase.cpp 209-225):无可用渲染系统则失败
  bool oneTimeConfig() { return !mNoRenderers; }
  // setup(OgreApplicationContextBase.cpp 171-182)
  void setup() {
    createWindow(mAppName);
    locateResources();
    loadResources();
    mFrameListener = true;  // mRoot->addFrameListener(this)
  }
  // createWindow(OgreApplicationContextBase.cpp 374-402)
  NativeWindowPair createWindow(const std::string& /*name*/) {
    NativeWindowPair ret{};
    if (!mWindows.empty()) ret.native = 0xBEEF;  // 附加窗口复用上下文
    ret.render = ++mWindowCounter;
    mWindows.push_back(ret);
    return ret;
  }
  // getRenderWindow(OgreApplicationContextBase.h 98-101)
  uint32_t getRenderWindow() const {
    return mWindows.empty() ? 0u : mWindows[0].render;
  }
  size_t windowCount() const { return mWindows.size(); }
  void locateResources() { mResourcesLocated = true; }
  void loadResources() { mResourcesLoaded = true; }
  bool isRootCreated() const { return mRootCreated; }
  bool isFrameListener() const { return mFrameListener; }
  bool isResourcesLocated() const { return mResourcesLocated; }
  bool isResourcesLoaded() const { return mResourcesLoaded; }
  void setNoRenderers(bool v) { mNoRenderers = v; }
  void setAppName(const std::string& n) { mAppName = n; }
  const std::string& getAppName() const { return mAppName; }

 private:
  std::string mAppName = "Ogre3D";  // 构造默认(OgreApplicationContextBase.h 90)
  std::vector<NativeWindowPair> mWindows;  // 对应 WindowList mWindows
  uint32_t mWindowCounter = 0;
  bool mRootCreated = false;
  bool mNoRenderers = false;
  bool mFrameListener = false;
  bool mResourcesLocated = false;
  bool mResourcesLoaded = false;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 初始状态:无窗口、未建 root、未注册帧监听
  ApplicationContextBase ctx;
  CHECK(!ctx.isRootCreated());
  CHECK(!ctx.isFrameListener());
  CHECK(ctx.windowCount() == 0);
  CHECK(ctx.getRenderWindow() == 0u);

  // initApp 成功:root 建立、默认窗口创建、资源定位/加载、成为帧监听
  bool ok = ctx.initApp();
  CHECK(ok);
  CHECK(ctx.isRootCreated());
  CHECK(ctx.windowCount() == 1);
  CHECK(ctx.getRenderWindow() == 1u);
  CHECK(ctx.isFrameListener());
  CHECK(ctx.isResourcesLocated());
  CHECK(ctx.isResourcesLoaded());

  // 附加窗口进入列表,getRenderWindow 仍取首窗口
  ctx.createWindow("Second");
  CHECK(ctx.windowCount() == 2);
  CHECK(ctx.getRenderWindow() == 1u);

  // 无可用渲染系统时 initApp 中断,不建窗口
  ApplicationContextBase bad;
  bad.setNoRenderers(true);
  CHECK(!bad.initApp());
  CHECK(bad.windowCount() == 0);

  // 应用名可配且默认 "Ogre3D"
  CHECK(ctx.getAppName() == "Ogre3D");
  bad.setAppName("MyApp");
  CHECK(bad.getAppName() == "MyApp");

  return lab::report("07-1 Bites 应用上下文");
}

本机实测(Apple clang,clang++ -std=c++20 -Wall):编译通过(零警告),断言 17/17 通过。

小结

  • ApplicationContextBase 继承 FrameListener,把 Root 生命周期、窗口与资源收进一个类。
  • initApp = createRoot → oneTimeConfig → setup,任一步失败即中止。
  • setup 里 createWindow(主窗口 + 附加窗口复用上下文)、locateResources、loadResources,最后注册帧监听。
  • NativeWindowPair{render, native} 组成 WindowList;getRenderWindow() 取首窗口。
  • 平台细节(SDL 原生窗口创建、事件轮询)由 ApplicationContextSDL 子类完成。

阅读导航:上一节:6.3 着色器变体 · 下一节:7.2 Bites 输入与主循环 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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