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;
| 成员 | 键 | 值 | 作用 |
|---|---|---|---|
mOverlayMap | overlay 名 | 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 则在此之上多走一步:从模板元素复制参数。
源码定位
Components/Overlay/include/OgreOverlayManager.h:OverlayManager类(56-206)、create(100)、createOverlayElement(138)、createOverlayElementFromTemplate(179)、addOverlayElementFactory(172)Components/Overlay/src/OgreOverlayManager.cpp:create(104-123)、getByName(126-138)、createOverlayElement(291-308)、createOverlayElementFromFactory(311-323)Components/Overlay/include/OgreOverlay.h:Overlay类(71-276)、show/hide(133-137)、add2D(152)、add3D(193)Components/Overlay/src/OgreOverlay.cpp:show(101-108)、hide(110-113)、add2D(129-140)、add3D(149-152)Components/Overlay/include/OgreOverlayElementFactory.h:OverlayElementFactory(57-68)
上游引用固定到 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 元素 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。