《OGRE 3D 渲染引擎原理与架构》13.2 Overlay 元素

OverlayElement 是覆盖层里的可绘制单元:setPosition/setDimensions 按当前度量模式写入相对或像素坐标,_update 把像素/虚拟像素换算成 0..1 相对坐标;Panel 是透明分组或四边形,TextArea 逐字生成带字符颜色的顶点。源码在 Components/Overlay/ 的 OgreOverlayElement.h/.cpp 与 OgrePanelOverlayElement.h。lab 复现度量模式换算、Panel 尺寸位置与 TextArea 文本颜色。

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_RELATIVE0..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 详述。

源码定位

上游引用固定到 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 覆盖层渲染 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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