《OGRE 3D 渲染引擎原理与架构》13.1 Overlay 系统

Overlay 是渲染在场景之上的图层(HUD、菜单),OverlayManager 是它的登记中心与元素工厂注册表:create 按名把 Overlay 记入 mOverlayMap,addOverlayElementFactory 把类型工厂记入 mFactories,createOverlayElement 经工厂创建并登记元素。源码在 Components/Overlay/ 的 OgreOverlayManager.h/.cpp。lab 复现 overlay 登记、工厂注册与按类型创建。

13.1 Overlay 系统

Overlay 是渲染在「正常场景内容」之上的图层:血条、准星、菜单、提示框都靠它叠加。与场景对象不同,Overlay 没有自己的世界坐标——它永远贴着视口,在场景渲染完之后才画,保证盖在最上。这一节看它的管理中枢 OverlayManager:overlay 怎么登记、元素类型怎么扩展。

OgreOverlay.h 开头注释把 overlay 定义为「渲染在正常场景内容之上的一层」:

Represents a layer which is rendered on top of the ’normal’ scene contents.

一个 Overlay 本身没有视觉元素,它只是 2D 元素与 3D 节点的容器。管理它们的 OverlayManager 同时继承 Singleton 与 ScriptLoader——既是全局单例,又能解析 .overlay 脚本。

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

helio 四卷做过 View 层的从零实现(对象树 + 渲染);cg 图形学讲了 UI 绘制原理。本卷 2.2 节讲 Viewport 只负责「一块目标上的裁剪窗口」,本节的 Overlay 是叠加在 viewport 之上的第二层绘制;OGRE 用独立组件 Components/Overlay 实现,与场景对象渲染完全解耦。这里只讲它的登记与工厂机制,13.2 讲元素本身的度量,13.3 讲它如何进入渲染队列。

OverlayManager:三类登记表

OverlayManager 内部持有三张表:按名字登记的 overlay(mOverlayMap)、按名字登记的元素(mElements)、按类型名登记的元素工厂(mFactories):

// Components/Overlay/include/OgreOverlayManager.h:OverlayManager(v14.6.3 源码摘录,已删减)
    class _OgreOverlayExport OverlayManager : public Singleton<OverlayManager>, public ScriptLoader, public OverlayAlloc
    {
    public:
        typedef std::map<String, Overlay*> OverlayMap;
        typedef std::map<String, OverlayElement*> ElementMap;
        typedef std::map<String, OverlayElementFactory*> FactoryMap;
    private:
        OverlayMap mOverlayMap;
        StringVector mScriptPatterns;
成员键值作用
mOverlayMapoverlay 名Overlay*登记所有 overlay
mElements元素名OverlayElement*登记所有元素实例
mFactories类型名OverlayElementFactory*元素类型工厂注册表

三张表都是 std::map,查找是 O(log n)。overlay 与元素数量都是几十上百的量级,map 的确定性遍历(脚本加载、销毁顺序)比 hash 表更可控。

create:按名登记 Overlay

OverlayManager::create 先查重名——同名 overlay 已存在就抛重复项异常,否则新建并记入 mOverlayMap:

// Components/Overlay/src/OgreOverlayManager.cpp:OverlayManager::create(v14.6.3 源码摘录,已删减)
    Overlay* OverlayManager::create(const String& name)
    {
        Overlay* ret = 0;
        OverlayMap::iterator i = mOverlayMap.find(name);

        if (i == mOverlayMap.end())
        {
            ret = OGRE_NEW Overlay(name);
            assert(ret && "Overlay creation failed");
            mOverlayMap[name] = ret;
        }
        else
        {
            OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM,
                "Overlay with name '" + name + "' already exists!",
                "OverlayManager::create");
        }

        return ret;

    }

要点:同名即冲突(脚本里重名 overlay 会直接报错);getByName 找不到时返回 0(空指针)而不是异常,调用方需要判空。create 是所有 overlay 的唯一入口——构造完立刻登记,保证 getByName 查得到。

Overlay:可见性与 2D/3D 容器

Overlay 实例保存名字、可见性、Z 序与滚屏/旋转/缩放参数,并持有两类内容:2D 容器列表(m2DElements)与一个内部 SceneNode(mRootNode,挂 3D 物体)。show/hide 只翻转可见标志;首次 show 会触发 initialise():

// Components/Overlay/src/OgreOverlay.cpp:Overlay::show / hide(v14.6.3 源码摘录,已删减)
    void Overlay::show(void)
    {
        mVisible = true;
        if (!mInitialised)
        {
            initialise();
        }
    }
    //---------------------------------------------------------------------
    void Overlay::hide(void)
    {
        mVisible = false;
    }

add2D 把一个容器挂进 overlay,并回填父指针、重排 Z 序、通知世界变换;add3D 把场景节点挂到内部根节点:

// Components/Overlay/src/OgreOverlay.cpp:Overlay::add2D / add3D(v14.6.3 源码摘录,已删减)
    void Overlay::add2D(OverlayContainer* cont)
    {
        m2DElements.push_back(cont);
        // Notify parent
        cont->_notifyParent(0, this);

        assignZOrders();

        Matrix4 xform;
        _getWorldTransforms(&xform);
        cont->_notifyWorldTransforms(xform);
    }
    //---------------------------------------------------------------------
    void Overlay::add3D(SceneNode* node)
    {
        mRootNode->addChild(node);
    }

注意 add2D 传的父指针是 0(根级容器没有 parent),overlay 本身通过 assignZOrders() 把 mZOrder*100 作为根容器的起始 Z 序。

元素工厂:类型即插件扩展点

OverlayElement 的类型不写死:第三方可以注册新类型(按钮、进度条……)。addOverlayElementFactory 把工厂记入 mFactories,createOverlayElement 先查元素重名,再经 createOverlayElementFromFactory 按类型找工厂创建:

// Components/Overlay/src/OgreOverlayManager.cpp:createOverlayElement / createOverlayElementFromFactory(v14.6.3 源码摘录,已删减)
    OverlayElement* OverlayManager::createOverlayElement(const String& typeName, const String& instanceName, bool)
    {
        // Check not duplicated
        ElementMap::iterator ii = mElements.find(instanceName);
        if (ii != mElements.end())
        {
            OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM, "OverlayElement with name " + instanceName +
                " already exists.", "OverlayManager::createOverlayElement" );
        }
        OverlayElement* newElem = createOverlayElementFromFactory(typeName, instanceName);

        // Register
        mElements.emplace(instanceName, newElem);

        return newElem;


    }
    //---------------------------------------------------------------------
    OverlayElement* OverlayManager::createOverlayElementFromFactory(const String& typeName, const String& instanceName)
    {
        // Look up factory
        FactoryMap::iterator fi = mFactories.find(typeName);
        if (fi == mFactories.end())
        {
            OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, "Cannot locate factory for element type " + typeName,
                "OverlayManager::createOverlayElement");
        }

        // create
        return fi->second->createOverlayElement(instanceName);
    }

OverlayElementFactory 接口极简——只有 createOverlayElement、destroyOverlayElement 与 getTypeName 三个纯虚方法。内置的 Panel、TextArea、BorderPanel 都各有一个工厂;插件只要实现这个接口并 addOverlayElementFactory 就能贡献新元素类型。createOverlayElementFromTemplate 则在此之上多走一步:从模板元素复制参数。

源码定位

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

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

下面用纯 C++ 复现 OverlayManager 的登记语义:overlay 按名登记与查重、元素工厂注册表、按类型经工厂创建元素。它与 src/13-1-overlay-system.cpp 逐字节一致:

// file: src/13-1-overlay-system.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/13-1-overlay-system.cpp -o bin/13-1-overlay-system && ./bin/13-1-overlay-system
//
// 复现 OverlayManager 的 overlay 登记与元素工厂注册表(对应
// Components/Overlay/include/OgreOverlayManager.h 56-206 与
// Components/Overlay/src/OgreOverlayManager.cpp 104-123、291-323、402):
//   create:按名登记 Overlay 到 mOverlayMap,重名抛重复项异常;
//   getByName:按名取回,找不到返回 0;
//   addOverlayElementFactory:把类型工厂登记到 mFactories,重名拒绝;
//   createOverlayElement:先查重名元素,再经 createOverlayElementFromFactory
//   查找工厂创建,并登记到 mElements。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <map>
#include <stdexcept>
#include <string>

namespace ogre_repro {

// 对应 OgreOverlay.h 71:Overlay 的极简形式,仅名字与可见性。
class Overlay {
 public:
  explicit Overlay(const std::string& name) : mName(name), mVisible(false) {}
  const std::string& getName() const { return mName; }
  void show() { mVisible = true; }
  void hide() { mVisible = false; }
  bool isVisible() const { return mVisible; }

 private:
  std::string mName;
  bool mVisible;
};

// 对应 OgreOverlayElementFactory.h 57:元素工厂接口。
class OverlayElementFactory {
 public:
  virtual ~OverlayElementFactory() {}
  virtual const std::string& getTypeName() const = 0;
};

class PanelFactory : public OverlayElementFactory {
 public:
  const std::string& getTypeName() const override { return msTypeName; }
  static std::string msTypeName;
};
std::string PanelFactory::msTypeName = "Panel";

class TextAreaFactory : public OverlayElementFactory {
 public:
  const std::string& getTypeName() const override { return msTypeName; }
  static std::string msTypeName;
};
std::string TextAreaFactory::msTypeName = "TextArea";

// 对应 OgreOverlayManager.h 56:OverlayManager 的登记语义。
class OverlayManager {
 public:
  using OverlayMap = std::map<std::string, Overlay*>;
  using FactoryMap = std::map<std::string, OverlayElementFactory*>;

  // 对应 OverlayManager::create(OgreOverlayManager.cpp 104-123)。
  Overlay* create(const std::string& name) {
    if (mOverlayMap.find(name) != mOverlayMap.end())
      throw std::runtime_error("Overlay with name '" + name + "' already exists!");
    Overlay* ret = new Overlay(name);
    mOverlayMap[name] = ret;
    return ret;
  }

  // 对应 OverlayManager::getByName(OgreOverlayManager.cpp 126-137)。
  Overlay* getByName(const std::string& name) {
    auto i = mOverlayMap.find(name);
    return i == mOverlayMap.end() ? nullptr : i->second;
  }

  // 对应 OverlayManager::addOverlayElementFactory(OgreOverlayManager.cpp 402-)。
  void addOverlayElementFactory(OverlayElementFactory* factory) {
    if (mFactories.find(factory->getTypeName()) != mFactories.end())
      throw std::runtime_error("A factory of type '" + factory->getTypeName() + "' already exists.");
    mFactories[factory->getTypeName()] = factory;
  }

  // 对应 OverlayManager::createOverlayElement(OgreOverlayManager.cpp 291-308)。
  // 用字符串模拟元素实例,登记进 mElements。
  void createOverlayElement(const std::string& typeName, const std::string& instanceName) {
    if (mElements.find(instanceName) != mElements.end())
      throw std::runtime_error("OverlayElement with name " + instanceName + " already exists.");
    std::string elem = createOverlayElementFromFactory(typeName, instanceName);
    mElements.emplace(instanceName, elem);
  }

  // 对应 OverlayManager::createOverlayElementFromFactory(OgreOverlayManager.cpp 311-323)。
  std::string createOverlayElementFromFactory(const std::string& typeName,
                                              const std::string& instanceName) {
    auto fi = mFactories.find(typeName);
    if (fi == mFactories.end())
      throw std::runtime_error("Cannot locate factory for element type " + typeName);
    return "[" + fi->second->getTypeName() + "]" + instanceName;
  }

  bool hasOverlayElement(const std::string& name) const {
    return mElements.find(name) != mElements.end();
  }
  size_t numOverlays() const { return mOverlayMap.size(); }
  size_t numFactories() const { return mFactories.size(); }

  OverlayMap mOverlayMap;
  FactoryMap mFactories;
  std::map<std::string, std::string> mElements;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  OverlayManager mgr;

  // 元素工厂注册表:登记两个类型工厂
  PanelFactory panelFactory;
  TextAreaFactory textAreaFactory;
  mgr.addOverlayElementFactory(&panelFactory);
  mgr.addOverlayElementFactory(&textAreaFactory);
  CHECK_EQ(mgr.numFactories(), size_t(2));
  CHECK(mgr.mFactories.find("Panel") != mgr.mFactories.end());
  CHECK(mgr.mFactories.find("TextArea") != mgr.mFactories.end());

  // 重复登记同类型工厂被拒绝
  bool dupFactory = false;
  try {
    mgr.addOverlayElementFactory(&panelFactory);
  } catch (const std::runtime_error&) {
    dupFactory = true;
  }
  CHECK(dupFactory);
  CHECK_EQ(mgr.numFactories(), size_t(2));

  // create:按名登记 Overlay
  Overlay* hud = mgr.create("HUD");
  CHECK(hud != nullptr);
  CHECK(hud->getName() == "HUD");
  CHECK_EQ(mgr.numOverlays(), size_t(1));
  CHECK(mgr.getByName("HUD") == hud);
  CHECK(mgr.getByName("Scoreboard") == nullptr);

  // 重复创建同名 Overlay 被拒绝
  bool dupOverlay = false;
  try {
    mgr.create("HUD");
  } catch (const std::runtime_error&) {
    dupOverlay = true;
  }
  CHECK(dupOverlay);
  CHECK_EQ(mgr.numOverlays(), size_t(1));

  // createOverlayElement:经工厂创建并登记
  mgr.createOverlayElement("Panel", "healthbar");
  CHECK(mgr.hasOverlayElement("healthbar"));
  CHECK(mgr.mElements["healthbar"] == "[Panel]healthbar");
  mgr.createOverlayElement("TextArea", "hint");
  CHECK(mgr.mElements["hint"] == "[TextArea]hint");

  // 未知类型找不到工厂
  bool unknownType = false;
  try {
    mgr.createOverlayElement("Button", "btn");
  } catch (const std::runtime_error&) {
    unknownType = true;
  }
  CHECK(unknownType);

  // 重名元素被拒绝
  bool dupElement = false;
  try {
    mgr.createOverlayElement("Panel", "healthbar");
  } catch (const std::runtime_error&) {
    dupElement = true;
  }
  CHECK(dupElement);

  // show/hide 与可见性
  CHECK(!hud->isVisible());
  hud->show();
  CHECK(hud->isVisible());
  hud->hide();
  CHECK(!hud->isVisible());

  return lab::report("13-1 Overlay 系统");
}

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

小结

  • Overlay 是渲染在场景之上的图层,本身无视觉,只是 2D 容器与 3D 节点的容器。
  • OverlayManager 用三张 map 管理 overlay(mOverlayMap)、元素(mElements)与元素工厂(mFactories)。
  • create 按名登记 overlay,重名抛重复项异常;getByName 找不到返回 0。
  • 元素类型由 OverlayElementFactory 工厂扩展:注册工厂后即可用类型名 createOverlayElement。
  • add2D/add3D 把容器或场景节点挂入 overlay,并回填父指针、重排 Z 序。

阅读导航:上一节:12.3 布告板渲染 · 下一节:13.2 Overlay 元素 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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