13.3 覆盖层渲染
13.1 登记了 overlay,13.2 定义了元素,这一节把它们送进渲染队列。Overlay 之所以「盖在场景上」,靠的是两条机制:队列组(RENDER_QUEUE_OVERLAY 排在所有场景内容之后)与 Z 序(overlay 之间、容器与内容之间谁在上)。核心是 Overlay::_findVisibleObjects 与 OverlayElement::_updateRenderQueue。
本章与站内既有内容的分工
卷二 5.1 讲过 RenderQueue 的组与排序,本卷 11.3 讲过天空进入 RENDER_QUEUE_SKIES_LATE。这一节是把同一套队列机制用到覆盖层:overlay 内容不参与场景剔除,只按 Z 序与队列组排在最后。
_findVisibleObjects:切组、更新、入队
OverlayManager::_queueOverlaysForRendering 遍历 mOverlayMap 里的每个 overlay,调用 _findVisibleObjects(cam, queue, vp)。这个函数是覆盖层渲染的入口:
// Components/Overlay/src/OgreOverlay.cpp:Overlay::_findVisibleObjects(v14.6.3 源码摘录,已删减)
void Overlay::_findVisibleObjects(Camera* cam, RenderQueue* queue, Viewport* vp)
{
if (mVisible)
{
// Flag for update pixel-based GUIElements if viewport has changed dimensions
bool tmpViewportDimensionsChanged = false;
if (mLastViewportWidth != vp->getActualWidth() ||
mLastViewportHeight != vp->getActualHeight())
{
tmpViewportDimensionsChanged = true;
mLastViewportWidth = vp->getActualWidth();
mLastViewportHeight = vp->getActualHeight();
}
...
// Add 3D elements
mRootNode->setPosition(cam->getDerivedPosition());
mRootNode->setOrientation(cam->getDerivedOrientation());
mRootNode->_update(true, false);
// Set up the default queue group for the objects about to be added
uint8 oldgrp = queue->getDefaultQueueGroup();
ushort oldPriority = queue-> getDefaultRenderablePriority();
queue->setDefaultQueueGroup(RENDER_QUEUE_OVERLAY);
queue->setDefaultRenderablePriority(static_cast<ushort>((mZOrder*100)-1));
mRootNode->_findVisibleObjects(cam, queue, NULL, true, false);
// Reset the group
queue->setDefaultQueueGroup(oldgrp);
queue->setDefaultRenderablePriority(oldPriority);
// Add 2D elements
for (auto *e : m2DElements)
{
e->_update();
e->_updateRenderQueue(queue);
}
}
}
四步动作:先检查视口尺寸是否变化(像素模式元素需要重算);再把 3D 内容挂到相机位置(mRootNode 跟随相机,3D 物体相对相机放置);然后把队列默认组切成 RENDER_QUEUE_OVERLAY、默认优先级设为 mZOrder*100-1;最后对每个 2D 元素执行 _update(重算几何)与 _updateRenderQueue(入队)。结束后恢复原来的默认组。
RENDER_QUEUE_OVERLAY 是队列组的倒数第二档,保证在所有场景内容之后:
// OgreMain/include/OgreRenderQueue.h:RenderQueueGroupID(v14.6.3 源码摘录,已删减)
/// Penultimate queue(before overlays)
RENDER_QUEUE_TRANSPARENTS = 95,
/// Use this queue for objects which must be rendered last e.g. overlays
RENDER_QUEUE_OVERLAY = 100,
/// Final possible render queue, don't exceed this
RENDER_QUEUE_MAX = 105,
元素入队与 Z 序
OverlayElement::_updateRenderQueue 把自身以 RENDER_QUEUE_OVERLAY 组、mZOrder 为优先级入队:
// Components/Overlay/src/OgreOverlayElement.cpp:OverlayElement::_updateRenderQueue(v14.6.3 源码摘录,已删减)
void OverlayElement::_updateRenderQueue(RenderQueue* queue)
{
if (mVisible)
{
queue->addRenderable(this, RENDER_QUEUE_OVERLAY, mZOrder);
}
}
Z 序怎么在队列里起作用?OverlayElement::getSquaredViewDepth 把 Z 序反向映射成深度——Z 越大越靠前(渲染越晚,即越在上):
// Components/Overlay/include/OgreOverlayElement.h:OverlayElement::getSquaredViewDepth(v14.6.3 源码摘录,已删减)
Real getSquaredViewDepth(const Camera* cam) const override
{
(void)cam;
return 10000.0f - (Real)getZOrder();
}
队列按 squaredViewDepth 升序渲染:深度小(Z 大)的元素后画、盖在最上。Z 序由 assignZOrders 分配:overlay 的根容器拿到 mZOrder*100,每嵌套一层容器递增,保证容器显示在它内容之下、后加入的 overlay 显示在前的 overlay 之上。
元素 → 渲染操作
元素最终要产出 RenderOperation。Panel 生成一个四边形(4 个顶点、2 个三角形);TextArea 对每个字符生成一个四边形,顶点带颜色(可用 setColourTop/setColourBottom 做渐变)。这些 RenderOperation 引用普通顶点/索引缓冲,由渲染系统按队列顺序提交给 GPU。由于 Overlay 材质必须关闭深度测试,覆盖层永远显示在场景之上。
覆盖层为何需要独立的坐标与顺序
Overlay 的元素把相对、像素或宽高修正后的尺寸换成实际绘制坐标。Overlay 及元素的 Z 序影响覆盖顺序,而目标尺寸改变会触发坐标重算。
对照同一元素在两种宽高比下的像素矩形,记录 overlay 开关和队列位置。将覆盖层消失与世界空间剔除分别诊断。
覆盖层的尺寸与提交
flowchart LR
O["Overlay"] --> E["元素和容器"]
E --> G["相对、像素或宽高修正度量"]
V["目标与视口尺寸"] --> G
G --> B["更新几何和屏幕坐标"]
B --> Z["按 Overlay 和元素 Z 序提交"]
Z --> R["Overlay 队列"]
源码定位
Components/Overlay/src/OgreOverlay.cpp:_findVisibleObjects(242-300)、assignZOrders(71-80)、findElementAt(325-343)Components/Overlay/src/OgreOverlayManager.cpp:_queueOverlaysForRendering(208-223)Components/Overlay/src/OgreOverlayElement.cpp:_update(360-429)、_updateRenderQueue(625-631)、_notifyZOrder(567-571)Components/Overlay/include/OgreOverlayElement.h:getSquaredViewDepth(443-447)OgreMain/include/OgreRenderQueue.h:RENDER_QUEUE_OVERLAY(74)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现覆盖层入队路径:可见 overlay 切组入队、元素树递归更新、Panel/TextArea 的渲染操作顶点数、以及 10000 - zOrder 的 Z 序排序。它与 src/13-3-overlay-rendering.cpp 逐字节一致:
// file: src/13-3-overlay-rendering.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/13-3-overlay-rendering.cpp -o bin/13-3-overlay-rendering && ./bin/13-3-overlay-rendering
//
// 复现 Overlay 的覆盖层渲染路径(对应 Components/Overlay/src/OgreOverlay.cpp
// 242-300 的 _findVisibleObjects 与 OgreOverlayElement.cpp 360-429、625-631,
// OgreRenderQueue.h 74 的 RENDER_QUEUE_OVERLAY):
// Overlay 可见时把队列默认组切到 RENDER_QUEUE_OVERLAY,优先级 mZOrder*100-1;
// 2D 元素逐帧 _update 并 _updateRenderQueue 入队;
// OverlayContainer 递归更新子元素树;
// Panel 生成四边形渲染操作、TextArea 逐字生成顶点;
// 元素按 Z 序(10000 - zOrder)排序,高 Z 在上。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 OgreRenderQueue.h 74。
static const uint8_t RENDER_QUEUE_OVERLAY = 100;
// 渲染队列:记录 (queueGroup, zOrder) 并以 10000 - zOrder 排序。
class RenderQueue {
public:
struct Item {
std::string name;
uint8_t group;
uint16_t zOrder;
};
void addRenderable(const std::string& name, uint8_t group, uint16_t zOrder) {
mItems.push_back(Item{name, group, zOrder});
}
size_t size() const { return mItems.size(); }
// 排序:squaredViewDepth = 10000 - zOrder,小者在先(高 Z 后画、在最上)。
void sort() {
for (size_t i = 0; i < mItems.size(); ++i)
for (size_t j = i + 1; j < mItems.size(); ++j)
if (depthOf(mItems[j]) < depthOf(mItems[i])) std::swap(mItems[i], mItems[j]);
}
static float depthOf(const Item& item) { return 10000.0f - static_cast<float>(item.zOrder); }
std::vector<Item> mItems;
uint8_t mDefaultGroup = 50; // RENDER_QUEUE_MAIN
uint16_t mDefaultPriority = 0;
};
// 元素基类:可见性、Z 序、_update 与 _updateRenderQueue。
class OverlayElement {
public:
explicit OverlayElement(const std::string& name) : mName(name), mVisible(true) {}
virtual ~OverlayElement() {}
void setVisible(bool v) { mVisible = v; }
bool isVisible() const { return mVisible; }
void setZOrder(uint16_t z) { mZOrder = z; }
uint16_t getZOrder() const { return mZOrder; }
// 对应 OverlayElement::_update(OgreOverlayElement.cpp 360-)。
virtual void update() {
mUpdated = true;
// 子类可覆盖;容器的 update 会递归更新孩子。
}
// 对应 OverlayElement::_updateRenderQueue(OgreOverlayElement.cpp 625-631)。
virtual void updateRenderQueue(RenderQueue* queue) {
if (mVisible) queue->addRenderable(mName, RENDER_QUEUE_OVERLAY, mZOrder);
}
// 对应 Panel/TextArea 的 getRenderOperation 顶点数。
virtual size_t getVertexCount() const { return 0; }
bool updated() const { return mUpdated; }
protected:
std::string mName;
bool mVisible;
bool mUpdated = false;
uint16_t mZOrder = 0;
};
// 容器:递归更新子元素。
class OverlayContainer : public OverlayElement {
public:
explicit OverlayContainer(const std::string& name) : OverlayElement(name) {}
void addChild(OverlayElement* child) { mChildren.push_back(child); }
// 容器的 _update 递归更新所有孩子(NB container subclasses will update children too)。
void update() override {
OverlayElement::update();
for (auto* c : mChildren) c->update();
}
size_t childCount() const { return mChildren.size(); }
// 容器没有自己的几何,但会入队(对应 OverlayContainer 覆盖 _updateRenderQueue)。
void updateRenderQueue(RenderQueue* queue) override {
OverlayElement::updateRenderQueue(queue);
for (auto* c : mChildren) c->updateRenderQueue(queue);
}
protected:
std::vector<OverlayElement*> mChildren;
};
// Panel:一个四边形 = 4 个顶点。
class PanelOverlayElement : public OverlayElement {
public:
explicit PanelOverlayElement(const std::string& name) : OverlayElement(name) {}
size_t getVertexCount() const override { return mTransparent ? 0 : 4; }
void setTransparent(bool t) { mTransparent = t; }
private:
bool mTransparent = false;
};
// TextArea:逐字四边形 = 字符数 × 4 个顶点。
class TextAreaOverlayElement : public OverlayElement {
public:
explicit TextAreaOverlayElement(const std::string& name) : OverlayElement(name) {}
void setCaption(const std::string& t) { mCaption = t; }
size_t getVertexCount() const override { return mCaption.size() * 4; }
private:
std::string mCaption;
};
// 对应 Overlay::_findVisibleObjects 的入队逻辑(OgreOverlay.cpp 242-300)。
class Overlay {
public:
explicit Overlay(const std::string& name) : mName(name) {}
void setZOrder(uint16_t z) { mZOrder = z; }
uint16_t getZOrder() const { return mZOrder; }
void show() { mVisible = true; }
void hide() { mVisible = false; }
bool isVisible() const { return mVisible; }
void add2D(OverlayContainer* cont) { m2DElements.push_back(cont); }
// 可见时:把队列默认组切成 RENDER_QUEUE_OVERLAY、优先级 mZOrder*100-1,
// 然后逐元素 _update + _updateRenderQueue。
void findVisibleObjects(RenderQueue* queue) {
if (!mVisible) return;
uint8_t oldGroup = queue->mDefaultGroup;
uint16_t oldPriority = queue->mDefaultPriority;
queue->mDefaultGroup = RENDER_QUEUE_OVERLAY;
queue->mDefaultPriority = static_cast<uint16_t>(mZOrder * 100 - 1);
for (auto* e : m2DElements) {
e->update();
e->updateRenderQueue(queue);
}
queue->mDefaultGroup = oldGroup;
queue->mDefaultPriority = oldPriority;
}
private:
std::string mName;
bool mVisible = false;
uint16_t mZOrder = 0;
std::vector<OverlayContainer*> m2DElements;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// Overlay 可见时入队:优先级 mZOrder*100-1
RenderQueue queue;
queue.mDefaultGroup = 50; // RENDER_QUEUE_MAIN
queue.mDefaultPriority = 0;
Overlay hud("HUD");
hud.setZOrder(5);
hud.show();
// 一个容器带两个 Panel,一个 TextArea
OverlayContainer* root = new OverlayContainer("root");
PanelOverlayElement* bg = new PanelOverlayElement("bg");
bg->setZOrder(500); // 根容器 Z 500
PanelOverlayElement* bar = new PanelOverlayElement("bar");
bar->setZOrder(501);
TextAreaOverlayElement* label = new TextAreaOverlayElement("label");
label->setCaption("Hi");
label->setZOrder(502);
root->addChild(bg);
root->addChild(bar);
root->addChild(label);
hud.add2D(root);
// 隐藏时不入队
hud.findVisibleObjects(&queue);
CHECK_EQ(queue.size(), size_t(4)); // root + 3 children
// 排序:Z 502 最先(depth 最小),Z 500 最后
queue.sort();
CHECK(queue.mItems[0].name == "label");
CHECK(queue.mItems[1].name == "bar");
CHECK(queue.mItems[2].name == "bg");
CHECK(queue.mItems[3].name == "root");
// 队列组是 RENDER_QUEUE_OVERLAY,默认组已恢复
CHECK(queue.mItems[0].group == RENDER_QUEUE_OVERLAY);
CHECK(queue.mDefaultGroup == 50);
CHECK_EQ(queue.mDefaultPriority, uint16_t(0));
// 元素树的递归更新:容器与孩子都标记 updated
CHECK(root->updated());
CHECK(bg->updated());
CHECK(bar->updated());
CHECK(label->updated());
// 元素 → 渲染操作:Panel 四边形 4 顶点,TextArea 2 字符 × 4 = 8 顶点
CHECK_EQ(bg->getVertexCount(), size_t(4));
CHECK_EQ(label->getVertexCount(), size_t(8));
// 透明 Panel 不产生几何
bg->setTransparent(true);
CHECK_EQ(bg->getVertexCount(), size_t(0));
bg->setTransparent(false);
// 不可见元素不入队
bar->setVisible(false);
RenderQueue queue2;
hud.findVisibleObjects(&queue2);
CHECK_EQ(queue2.size(), size_t(3)); // root + bg + label
// 隐藏 Overlay 后整棵元素树不入队
hud.hide();
RenderQueue queue3;
hud.findVisibleObjects(&queue3);
CHECK_EQ(queue3.size(), size_t(0));
delete root;
delete bg;
delete bar;
delete label;
return lab::report("13-3 覆盖层渲染");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 17/17 通过。
小结
_findVisibleObjects把队列默认组切成RENDER_QUEUE_OVERLAY、优先级设为mZOrder*100-1,渲染完恢复。- 2D 元素逐帧
_update(重算几何)后_updateRenderQueue入队;容器递归更新子树。 RENDER_QUEUE_OVERLAY = 100排在所有场景内容之后,覆盖层因此盖在场景上。- Z 序经
getSquaredViewDepth = 10000 - zOrder进入排序,Z 大者后画、在最上。 - Panel 产四边形、TextArea 逐字产带色顶点;覆盖层材质关闭深度测试。
阅读导航:上一节:13.2 Overlay 元素 · 下一节:14.1 RTSS 概览 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。