《OGRE 3D 渲染引擎原理与架构》13.3 覆盖层渲染

覆盖层在场景之后进入渲染队列:Overlay::_findVisibleObjects 把队列默认组切成 RENDER_QUEUE_OVERLAY、优先级设为 mZOrder*100-1,再对每个 2D 元素 _update 与 _updateRenderQueue;元素按 getSquaredViewDepth=10000-zOrder 排序。源码在 Components/Overlay/src/OgreOverlay.cpp 与 OgreOverlayElement.cpp。lab 复现元素树递归更新、元素到渲染操作、Z 序排序。

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 队列"]

源码定位

上游引用固定到 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 概览 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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