13.2 Overlay 元素
Overlay 只是容器,真正画在屏幕上的是一棵 OverlayElement 树。元素要解决的问题很朴素:给定「放哪、多大」,怎么换算成渲染用的相对坐标;不同子类怎么把语义变成几何。这一节看度量模式(GuiMetricsMode)、基类的坐标换算、以及三个具体子类 PanelOverlayElement、TextAreaOverlayElement、BorderPanelOverlayElement。
本章与站内既有内容的分工
helio 的 View 层和 cg 的 UI 绘制都做过「相对布局 + 像素换算」;本卷 13.1 讲了 overlay 与元素的登记。这一节的 OverlayElement 是 UI 布局问题的 OGRE 答案:分辨率无关的 0..1 相对坐标 + 可选的像素/虚拟像素模式。它与卷二 Renderable 契约的接口(getRenderOperation)在 13.3 才真正消费。
度量模式:相对、像素与长宽比修正
OverlayElement 的位置与尺寸用三种模式解释,枚举定义在头文件:
// Components/Overlay/include/OgreOverlayElement.h:GuiMetricsMode(v14.6.3 源码摘录,已删减)
enum GuiMetricsMode
{
/// 'left', 'top', 'height' and 'width' are parametrics from 0.0 to 1.0
GMM_RELATIVE,
/// Positions & sizes are in absolute pixels
GMM_PIXELS,
/// Positions & sizes are in virtual pixels
GMM_RELATIVE_ASPECT_ADJUSTED
};
| 模式 | 语义 | 适用 |
|---|---|---|
GMM_RELATIVE | 0..1 参数化,直接就是屏幕比例 | 大部分 HUD,分辨率无关 |
GMM_PIXELS | 绝对像素 | 准星、固定尺寸控件 |
GMM_RELATIVE_ASPECT_ADJUSTED | 虚拟像素,横向按视口长宽比缩放 | 字号/面板想保持物理大小 |
setPosition 与 setDimensions 并不立即换算——它们按当前模式写入不同的成员:
// Components/Overlay/src/OgreOverlayElement.cpp:OverlayElement::setDimensions / setPosition(v14.6.3 源码摘录,已删减)
void OverlayElement::setDimensions(Real width, Real height)
{
if (mMetricsMode != GMM_RELATIVE)
{
mPixelWidth = width;
mPixelHeight = height;
}
else
{
mWidth = width;
mHeight = height;
}
mDerivedOutOfDate = true;
_positionsOutOfDate();
}
//---------------------------------------------------------------------
void OverlayElement::setPosition(Real left, Real top)
{
if (mMetricsMode != GMM_RELATIVE)
{
mPixelLeft = left;
mPixelTop = top;
}
else
{
mLeft = left;
mTop = top;
}
mDerivedOutOfDate = true;
_positionsOutOfDate();
}
两种模式都标记派生数据失效(mDerivedOutOfDate)并要求重建几何(_positionsOutOfDate)。真正的换算发生在 _update()。
_update:像素到相对坐标的换算
每帧(或视口尺寸变化时)_update 依据当前模式求出 mPixelScaleX/mPixelScaleY,再把像素坐标乘上比例得到 0..1 的相对坐标。换算部分:
// Components/Overlay/src/OgreOverlayElement.cpp:OverlayElement::_update(v14.6.3 源码摘录,已删减)
// Check size if pixel-based or relative-aspect-adjusted
switch (mMetricsMode)
{
case GMM_PIXELS :
if (mGeomPositionsOutOfDate)
{
mPixelScaleX = 1.0f / vpWidth;
mPixelScaleY = 1.0f / vpHeight;
}
break;
case GMM_RELATIVE_ASPECT_ADJUSTED :
if (mGeomPositionsOutOfDate)
{
mPixelScaleX = 1.0f / (10000.0f * (vpWidth / vpHeight));
mPixelScaleY = 1.0f / 10000.0f;
}
break;
default:
case GMM_RELATIVE :
mPixelScaleX = 1.0;
mPixelScaleY = 1.0;
mPixelLeft = mLeft;
mPixelTop = mTop;
mPixelWidth = mWidth;
mPixelHeight = mHeight;
break;
}
mLeft = mPixelLeft * mPixelScaleX;
mTop = mPixelTop * mPixelScaleY;
mWidth = mPixelWidth * mPixelScaleX;
mHeight = mPixelHeight * mPixelScaleY;
关键区别在比例:GMM_PIXELS 用 1/vpWidth、1/vpHeight 把像素换算成相对;GMM_RELATIVE_ASPECT_ADJUSTED 用 1/(10000*aspect) 与 1/10000——横轴随视口长宽比缩放,纵轴固定 1/10000,这样相同字号在 4:3 与 16:9 屏幕上物理大小一致。GMM_RELATIVE 直接把相对值透传。
_update 后半段调用 _updateFromParent() 处理对齐(GHA_LEFT/CENTER/RIGHT、GVA_TOP/CENTER/BOTTOM),然后按需重建位置与纹理几何。
Panel / TextArea / BorderPanel:三个内置元素
PanelOverlayElement 是「一块单材质面板」,可透明(只当分组容器)或真正渲染:
// Components/Overlay/include/OgrePanelOverlayElement.h:PanelOverlayElement(v14.6.3 源码摘录,已删减)
class _OgreOverlayExport PanelOverlayElement : public OverlayContainer
{
public:
/** Constructor. */
PanelOverlayElement(const String& name);
virtual ~PanelOverlayElement();
/** Initialise */
void initialise(void) override;
...
/** Sets whether this panel is transparent (used only as a grouping level), or
if it is actually rendered.
*/
void setTransparent(bool isTransparent);
/** Returns whether this panel is transparent. */
bool isTransparent(void) const;
...
RenderOperation mRenderOp;
TextAreaOverlayElement 是带字体的文本区域:setCaption 设置文本、setCharHeight 设置字符高度、setColour 设整体颜色,还支持 setColourTop/setColourBottom 做渐变色:
// Components/Overlay/include/OgreTextAreaOverlayElement.h:TextAreaOverlayElement(v14.6.3 源码摘录,已删减)
class _OgreOverlayExport TextAreaOverlayElement : public OverlayElement
{
public:
enum Alignment
{
Left,
Right,
Center
};
...
void setCaption(const DisplayString& text) override;
void setCharHeight( Real height );
Real getCharHeight() const;
...
void setColour(const ColourValue& col) override;
...
/// Colours to use for the vertices
ColourValue mColourBottom;
ColourValue mColourTop;
bool mColoursChanged;
BorderPanelOverlayElement 则专攻带边框的面板:边框宽度可四周分别设置(setBorderSize(left, right, top, bottom)),边框用 8 个面板拼接(四角 + 四边,中心区重复填充),每段有独立 UV。它派生自 PanelOverlayElement,因此也具备容器能力。
渲染时 Panel 生成一个四边形(4 顶点),TextArea 对每个字符生成一个四边形(4 顶点),最终通过 getRenderOperation 交给渲染队列——这一步在 13.3 详述。
源码定位
Components/Overlay/include/OgreOverlayElement.h:GuiMetricsMode(52-60)、OverlayElement类(102-459)、setDimensions(214)、setPosition(217)、setMetricsMode(375)、setColour(360)Components/Overlay/src/OgreOverlayElement.cpp:setDimensions(105-119)、setPosition(121-135)、_update(360-429)、_updateFromParent(431-515)、setMetricsMode(701-)Components/Overlay/include/OgrePanelOverlayElement.h:PanelOverlayElement(58-128)、setTransparent(97)Components/Overlay/include/OgreTextAreaOverlayElement.h:TextAreaOverlayElement(44-167)、setCaption(66)、setCharHeight(68)、setColour(92)Components/Overlay/include/OgreBorderPanelOverlayElement.h:BorderPanelOverlayElement(57-)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现元素度量换算与 Panel/TextArea 语义:三种模式的坐标换算、透明分组、文本顶点与字符颜色。它与 src/13-2-overlay-element.cpp 逐字节一致:
// file: src/13-2-overlay-element.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/13-2-overlay-element.cpp -o bin/13-2-overlay-element && ./bin/13-2-overlay-element
//
// 复现 OverlayElement 的度量模式与 Panel/TextArea 语义(对应
// Components/Overlay/include/OgreOverlayElement.h 52-60、102-、214-、375- 与
// Components/Overlay/src/OgreOverlayElement.cpp 105-135、360-429、701-):
// setPosition/setDimensions:按当前度量模式写入相对或像素坐标;
// _update:把像素/虚拟像素换算成 0..1 相对坐标(像素比例或长宽比修正);
// Panel:透明分组或渲染四边形;
// TextArea:caption + 字符高度 + 字符颜色,逐字生成顶点。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cmath>
#include <cstdint>
#include <string>
namespace ogre_repro {
using Real = float;
// 对应 OgreOverlayElement.h 52:GuiMetricsMode。
enum GuiMetricsMode {
GMM_RELATIVE = 0,
GMM_PIXELS = 1,
GMM_RELATIVE_ASPECT_ADJUSTED = 2
};
// 对应 OgreOverlayElement.h 102:元素基类(简化)。
class OverlayElement {
public:
explicit OverlayElement(const std::string& name) : mName(name) {}
// 对应 setMetricsMode(OgreOverlayElement.cpp 701-):切换模式并保留旧值。
void setMetricsMode(GuiMetricsMode gmm) { mMetricsMode = gmm; }
GuiMetricsMode getMetricsMode() const { return mMetricsMode; }
// 对应 setPosition(OgreOverlayElement.cpp 121-135)。
void setPosition(Real left, Real top) {
if (mMetricsMode != GMM_RELATIVE) {
mPixelLeft = left;
mPixelTop = top;
} else {
mLeft = left;
mTop = top;
}
}
// 对应 setDimensions(OgreOverlayElement.cpp 105-119)。
void setDimensions(Real width, Real height) {
if (mMetricsMode != GMM_RELATIVE) {
mPixelWidth = width;
mPixelHeight = height;
} else {
mWidth = width;
mHeight = height;
}
}
// 对应 _update 的换算部分(OgreOverlayElement.cpp 360-429)。
// vpWidth/vpHeight 由 OverlayManager 的视口尺寸提供。
void update(Real vpWidth, Real vpHeight) {
switch (mMetricsMode) {
case GMM_PIXELS:
mPixelScaleX = 1.0f / vpWidth;
mPixelScaleY = 1.0f / vpHeight;
break;
case GMM_RELATIVE_ASPECT_ADJUSTED:
mPixelScaleX = 1.0f / (10000.0f * (vpWidth / vpHeight));
mPixelScaleY = 1.0f / 10000.0f;
break;
default: // GMM_RELATIVE
mPixelScaleX = 1.0f;
mPixelScaleY = 1.0f;
mPixelLeft = mLeft;
mPixelTop = mTop;
mPixelWidth = mWidth;
mPixelHeight = mHeight;
break;
}
mLeft = mPixelLeft * mPixelScaleX;
mTop = mPixelTop * mPixelScaleY;
mWidth = mPixelWidth * mPixelScaleX;
mHeight = mPixelHeight * mPixelScaleY;
}
Real getLeft() const { return mLeft; }
Real getTop() const { return mTop; }
Real getWidth() const { return mWidth; }
Real getHeight() const { return mHeight; }
const std::string& getName() const { return mName; }
protected:
std::string mName;
GuiMetricsMode mMetricsMode = GMM_RELATIVE;
Real mLeft = 0, mTop = 0, mWidth = 0, mHeight = 0;
Real mPixelLeft = 0, mPixelTop = 0, mPixelWidth = 0, mPixelHeight = 0;
Real mPixelScaleX = 1.0f, mPixelScaleY = 1.0f;
};
// 对应 OgrePanelOverlayElement.h 58:Panel,透明时只分组、否则渲染四边形。
class PanelOverlayElement : public OverlayElement {
public:
explicit PanelOverlayElement(const std::string& name) : OverlayElement(name) {}
void setTransparent(bool t) { mTransparent = t; }
bool isTransparent() const { return mTransparent; }
// 对应 getRenderOperation:一个面板四边形 = 4 个顶点。
size_t getVertexCount() const { return mTransparent ? 0 : 4; }
private:
bool mTransparent = false;
};
// 对应 OgreTextAreaOverlayElement.h 44:文本区域。
class TextAreaOverlayElement : public OverlayElement {
public:
explicit TextAreaOverlayElement(const std::string& name) : OverlayElement(name) {}
void setCaption(const std::string& text) { mCaption = text; }
const std::string& getCaption() const { return mCaption; }
void setCharHeight(Real height) { mCharHeight = height; }
Real getCharHeight() const { return mCharHeight; }
void setColour(Real r, Real g, Real b, Real a) {
mCharR = r;
mCharG = g;
mCharB = b;
mCharA = a;
}
Real getCharR() const { return mCharR; }
// 对应逐字顶点:每个字符一个四边形 = 4 个顶点。
size_t getVertexCount() const { return mCaption.size() * 4; }
private:
std::string mCaption;
Real mCharHeight = 0.04f;
Real mCharR = 1.0f, mCharG = 1.0f, mCharB = 1.0f, mCharA = 1.0f;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 相对模式:0..1 参数化坐标直接保留
PanelOverlayElement panel("panel");
panel.setMetricsMode(GMM_RELATIVE);
panel.setPosition(0.1f, 0.2f);
panel.setDimensions(0.5f, 0.25f);
panel.update(800.0f, 600.0f);
CHECK_EQ(panel.getLeft(), 0.1f);
CHECK_EQ(panel.getTop(), 0.2f);
CHECK_EQ(panel.getWidth(), 0.5f);
CHECK_EQ(panel.getHeight(), 0.25f);
// 像素模式:setPosition/setDimensions 写入像素,update 换算成相对
panel.setMetricsMode(GMM_PIXELS);
panel.setPosition(80.0f, 60.0f);
panel.setDimensions(400.0f, 150.0f);
panel.update(800.0f, 600.0f);
CHECK(std::fabs(panel.getLeft() - 0.1f) < 1e-6f); // 80 / 800
CHECK(std::fabs(panel.getTop() - 0.1f) < 1e-6f); // 60 / 600
CHECK(std::fabs(panel.getWidth() - 0.5f) < 1e-6f); // 400 / 800
CHECK(std::fabs(panel.getHeight() - 0.25f) < 1e-6f); // 150 / 600
// 长宽比修正模式:虚拟像素,横向按视口长宽比缩放
PanelOverlayElement virt("virt");
virt.setMetricsMode(GMM_RELATIVE_ASPECT_ADJUSTED);
virt.setPosition(500.0f, 100.0f);
virt.update(1000.0f, 500.0f); // 长宽比恰好 2.0
CHECK(std::fabs(virt.getLeft() - 0.025f) < 1e-5f); // 500 / (10000 * 2)
CHECK(std::fabs(virt.getTop() - 0.01f) < 1e-5f); // 100 / 10000
// Panel:透明分组 vs 可见四边形
CHECK(panel.isTransparent() == false);
CHECK_EQ(panel.getVertexCount(), size_t(4));
panel.setTransparent(true);
CHECK(panel.isTransparent());
CHECK_EQ(panel.getVertexCount(), size_t(0));
// TextArea:caption + 字符高度 + 字符颜色
TextAreaOverlayElement text("text");
text.setMetricsMode(GMM_PIXELS);
text.setPosition(160.0f, 120.0f);
text.setCaption("OGRE");
text.setCharHeight(32.0f);
text.setColour(1.0f, 0.5f, 0.25f, 1.0f);
text.update(800.0f, 600.0f);
CHECK(text.getCaption() == "OGRE");
CHECK_EQ(text.getCharHeight(), 32.0f);
CHECK_EQ(text.getCharR(), 1.0f);
CHECK_EQ(text.getVertexCount(), size_t(16)); // 4 字符 × 4 顶点
CHECK(std::fabs(text.getLeft() - 0.2f) < 1e-6f); // 160 / 800
CHECK(std::fabs(text.getTop() - 0.2f) < 1e-6f); // 120 / 600
return lab::report("13-2 Overlay 元素");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 20/20 通过。
小结
GuiMetricsMode三种模式决定 setPosition/setDimensions 写入相对还是像素成员。_update按模式求出mPixelScale,把像素/虚拟像素换算成 0..1 相对坐标;GMM_RELATIVE直接透传。GMM_RELATIVE_ASPECT_ADJUSTED横轴按视口长宽比缩放,纵轴固定 1/10000,保持物理大小。PanelOverlayElement可透明(分组)或渲染四边形;TextAreaOverlayElement逐字生成带颜色的顶点。BorderPanelOverlayElement用 8 段边框拼接出可拉伸、中心重复的面板。
阅读导航:上一节:13.1 Overlay 系统 · 下一节:13.3 覆盖层渲染 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。