《OGRE 3D 渲染引擎原理与架构》5.3 QueuedRenderable 与提交

排序完的队列怎么被消费?OGRE 用 QueuedRenderableVisitor 访问者模式:降序集合逐条 visit(RenderablePass*),分组集合每 Pass 一次 visit(Pass*, RenderableList&)。RenderablePass 是「渲染项 + Pass」二元组,addRenderable 按位双写。lab 复现双写、三种访问与未声明模式回退。

5.3 QueuedRenderable 与提交

5.1 把物体装进组,5.2 把组内排好序。剩下最后一步:谁把队列里排好的东西变成实际的绘制调用? OGRE 在这里用了访问者模式——QueuedRenderableVisitor。原因很实际:同一批数据有两种组织方式(按 Pass 分组 / 按距离排序),消费者不该知道内部结构。这一节看 RenderablePass 二元组、addRenderable 的双写、以及三种 acceptVisitor 的访问路径。

本章与站内既有内容的分工

helio 四卷渲染器提交阶段直接遍历 DrawCommand 列表;卷一 ogre-core 讲过 Resource 生命周期。这里看 OGRE 的「提交接口」:不是返回一个遍历器给调用方,而是让调用方实现一个 visitor,由集合自己决定按哪种顺序回调——职责倒置,内部组织方式对外完全透明。

二元组:RenderablePass

降序集合不按 Pass 分组,每条记录必须同时记住「画什么」和「用什么 Pass 画」。这就是 RenderablePass:

// OgreMain/include/OgreRenderQueueSortingGrouping.h:RenderablePass(v14.6.3 源码摘录,已删减)
    typedef std::vector<Renderable*> RenderableList;

    /** Struct associating a single Pass with a single Renderable. 
        This is used to for objects sorted by depth and thus not
        grouped by pass.
    */
    struct RenderablePass
    {
        /// Pointer to the Renderable details
        Renderable* renderable;
        /// Pointer to the Pass
        Pass* pass;

        RenderablePass(Renderable* rend, Pass* p) :renderable(rend), pass(p) {}
    };

两个裸指针加一个构造,仅此而已。它是 5.2 排序的单位:DistanceSortDescendingLess 比的就是两个 RenderablePass 的渲染项距离和 Pass 哈希。

访问者:QueuedRenderableVisitor

集合的消费接口是 visitor,两个 visit 二选一:

// OgreMain/include/OgreRenderQueueSortingGrouping.h:QueuedRenderableVisitor(v14.6.3 源码摘录,已删减)
    class _OgreExport QueuedRenderableVisitor
    {
    public:
        QueuedRenderableVisitor() {}
        virtual ~QueuedRenderableVisitor() {}
        
        /** Called when visiting a RenderablePass, i.e. items in a
            sorted collection where items are not grouped by pass.

            If this is called, the other visit method
            will not be called.
        */
        virtual void visit(RenderablePass* rp) = 0;

        /** When visiting a collection grouped by pass, this is
            called.

            If this method is called, the RenderablePass visit 
            method will not be called for this collection.
        */
        virtual void visit(const Pass* p, RenderableList& rs) = 0;
    };

两种回调互斥:按距离排序的集合逐条调 visit(RenderablePass*),按 Pass 分组的集合每个 Pass 调一次 visit(Pass*, RenderableList&)。注释反复强调「If this is called, the other visit method will not be called」——消费者写其中一个就行。

双写:addRenderable

一个集合可以同时声明多种组织方式(位掩码)。入队时双写——按位决定写进哪个结构:

// OgreMain/src/OgreRenderQueueSortingGrouping.cpp:addRenderable(v14.6.3 源码摘录,已删减)
    void QueuedRenderableCollection::addRenderable(Pass* pass, Renderable* rend)
    {
        // ascending and descending sort both set bit 1
        if (mOrganisationMode & OM_SORT_DESCENDING)
        {
            mSortedDescending.push_back(RenderablePass(rend, pass));
        }

        if (mOrganisationMode & OM_PASS_GROUP)
        {
            // Optionally create new pass entry, build a new list
            // Note that this pass and list are never destroyed until the
            // engine shuts down, or a pass is destroyed or has it's hash
            // recalculated, although the lists will be cleared
            PassGroupRenderableMap::iterator i = mGrouped.emplace(pass, RenderableList()).first;

            // Insert renderable
            i->second.push_back(rend);
            
        }
        
    }

mSortedDescending 是 std::vector<RenderablePass>,mGrouped 是 std::map<Pass*, RenderableList, PassGroupLess>(按 Pass 哈希排序的键)。同一条记录进向量又进分组,两份冗余换来两种访问方式都能 O(1) 就绪。

三种访问路径:acceptVisitor

acceptVisitor 先做模式回退,再按请求分发到三个私有方法。回退逻辑值得看:

// OgreMain/src/OgreRenderQueueSortingGrouping.cpp:acceptVisitor(v14.6.3 源码摘录,已删减)
    void QueuedRenderableCollection::acceptVisitor(
        QueuedRenderableVisitor* visitor, OrganisationMode om) const
    {
        if ((om & mOrganisationMode) == 0)
        {
            // try to fall back
            if (OM_PASS_GROUP & mOrganisationMode)
                om = OM_PASS_GROUP;
            else if (OM_SORT_ASCENDING & mOrganisationMode)
                om = OM_SORT_ASCENDING;
            else if (OM_SORT_DESCENDING & mOrganisationMode)
                om = OM_SORT_DESCENDING;
            else
                OGRE_EXCEPT(Exception::ERR_INVALIDPARAMS, 
                    "Organisation mode requested in acceptVistor was not notified "
                    "to this class ahead of time, therefore may not be supported.", 
                    "QueuedRenderableCollection::acceptVisitor");
        }

        switch(om)
        {
        case OM_PASS_GROUP:
            acceptVisitorGrouped(visitor);
            break;
        case OM_SORT_DESCENDING:
            acceptVisitorDescending(visitor);
            break;
        case OM_SORT_ASCENDING:
            acceptVisitorAscending(visitor);
            break;
        }
        
    }

请求的模式不在集合已声明的掩码里时,按 PASS_GROUP → ASCENDING → DESCENDING 优先级回退;全都没有才抛异常。三个私有访问方法各司其职:

// OgreMain/src/OgreRenderQueueSortingGrouping.cpp:acceptVisitorGrouped(v14.6.3 源码摘录,已删减)
    void QueuedRenderableCollection::acceptVisitorGrouped(
        QueuedRenderableVisitor* visitor) const
    {
        for (auto& ipass : mGrouped)
        {
            // Fast bypass if this group is now empty
            if (ipass.second.empty()) continue;

            visitor->visit(ipass.first, const_cast<RenderableList&>(ipass.second));
        } 

    }
// OgreMain/src/OgreRenderQueueSortingGrouping.cpp:acceptVisitorDescending/Ascending(v14.6.3 源码摘录,已删减)
    void QueuedRenderableCollection::acceptVisitorDescending(
        QueuedRenderableVisitor* visitor) const
    {
        // List is already in descending order, so iterate forward
        for (const auto& i : mSortedDescending)
        {
            visitor->visit(const_cast<RenderablePass*>(&i));
        }
    }
    void QueuedRenderableCollection::acceptVisitorAscending(
        QueuedRenderableVisitor* visitor) const
    {
        // List is in descending order, so iterate in reverse
        RenderablePassList::const_reverse_iterator i, iend;

        iend = mSortedDescending.rend();
        for (i = mSortedDescending.rbegin(); i != iend; ++i)
        {
            visitor->visit(const_cast<RenderablePass*>(&(*i)));
        }

    }

降序列表正向迭代,升序就 rbegin() 反向迭代——排序永远只做一次。真正的消费方(SceneManager 的渲染循环里)实现 visitor,在 visit(RenderablePass*) 里调用 _setPass + renderSingleObject 完成实际提交。

一次索引绘制怎样走出队列

在样例的普通可见路径里,RenderQueue::addRenderable 选择 Technique,给 RenderableListener 一次接受、拒绝或替换 Technique 的机会,再把 Renderable 和对应 Pass 放到队列结构中。消费时,SceneManager 的 visitor 访问排好序的项,调用 _setPass 和 renderSingleObject。到 _issueRenderOp 才收尾 GPU 参数,询问 Renderable 的 preRender,并获取 RenderOperation。需要时补全全局实例化声明,最后调用具体后端的 _render。 入队 · 队列消费 · 绘制入口

sequenceDiagram
  participant O as Renderable
  participant Q as RenderQueue
  participant S as SceneManager
  participant B as RenderSystem
  O->>Q: addRenderable 选择 Technique
  alt 监听器拒绝
    Q-->>O: 当前提交不入队
  else 监听器接受
    Q->>Q: 按 group 和 priority 保存 Renderable 与 Pass
    S->>Q: 访问按模式组织的项目
    S->>S: _setPass 并收尾程序参数
    S->>O: preRender
    opt preRender 允许默认绘制
      S->>O: getRenderOperation
      S->>S: 补全实例化声明
      S->>B: _render,消费索引与顶点
    end
    S->>O: postRender
  end

入队监听统计的是候选。本例还检查 RenderTarget 的三角形数和读回像素,才能把候选与实际绘制对应起来。两个实体各提交六个索引,共四个三角形。材质、组和优先级可以从监听记录核对,顶点与索引范围来自 RenderOperation。GPU 后端实际提交的命令需要该后端的捕获或计数支持。 原生场景样例 。

候选计数、队列项目和 draw 数

RenderableListener 观察入队候选。一个 Technique 可能产生多个 Pass,部分队列项也会因为条件在消费时被跳过。一个候选不能直接对应一个 draw。

把监听记录、Pass 展开和后端统计放在同一帧。当前场景两个候选各一个 Pass,共四个三角形。透明排序、迭代灯光或多 Pass 的观测需要各自的场景。

源码定位

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现双写、三种访问与未声明模式回退。它与 src/05-3-queued-renderable.cpp 逐字节一致:

// file: src/05-3-queued-renderable.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/05-3-queued-renderable.cpp -o bin/05-3-queued-renderable && ./bin/05-3-queued-renderable
//
// 复现 QueuedRenderableCollection 与 QueuedRenderableVisitor(对应 OgreRenderQueueSortingGrouping.h 45-101、OgreRenderQueueSortingGrouping.cpp 382-474):
//   RenderablePass 是「渲染项 + Pass」的二元组,供降序集合使用;
//   addRenderable 双写:OM_SORT_DESCENDING 位写 mSortedDescending 向量,OM_PASS_GROUP 位写 mGrouped 按 Pass 分组;
//   消费者必须用 QueuedRenderableVisitor:降序集合逐条 visit(RenderablePass*),分组集合每 Pass 一次 visit(Pass*, RenderableList&);
//   升序 = 降序向量反向迭代;acceptVisitor 对未声明的模式回退。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <map>
#include <vector>

namespace ogre_repro {

enum OrganisationMode {
  OM_PASS_GROUP = 1,
  OM_SORT_DESCENDING = 2,
  OM_SORT_ASCENDING = 6
};

struct Renderable {
  int id;
};

struct Pass {
  int id;
};

// 对应 RenderablePass:单条「渲染项 + 所用 Pass」
struct RenderablePass {
  Renderable* renderable;
  Pass* pass;

  RenderablePass(Renderable* rend, Pass* p) : renderable(rend), pass(p) {}
};

// 对应 QueuedRenderableVisitor:两种 visit 只会用一种
class QueuedRenderableVisitor {
 public:
  virtual ~QueuedRenderableVisitor() = default;
  virtual void visit(RenderablePass* rp) = 0;
  virtual void visit(const Pass* p, std::vector<Renderable*>& rs) = 0;
};

using RenderableList = std::vector<Renderable*>;
using RenderablePassList = std::vector<RenderablePass>;

// 对应 QueuedRenderableCollection(简化:只保留两种组织所需结构)
class QueuedRenderableCollection {
 public:
  QueuedRenderableCollection(uint8_t mode) : mOrganisationMode(mode) {}

  // 对应 addRenderable:按位写双结构
  void addRenderable(Pass* pass, Renderable* rend) {
    if (mOrganisationMode & OM_SORT_DESCENDING) {
      mSortedDescending.push_back(RenderablePass(rend, pass));
    }
    if (mOrganisationMode & OM_PASS_GROUP) {
      mGrouped.emplace(pass, RenderableList()).first->second.push_back(rend);
    }
  }

  size_t getSortedCount() const { return mSortedDescending.size(); }
  size_t getGroupedPassCount() const { return mGrouped.size(); }
  const RenderablePassList& getSorted() const { return mSortedDescending; }

  // 对应 acceptVisitor:回退 + 分发
  void acceptVisitor(QueuedRenderableVisitor* visitor, OrganisationMode om) const {
    if ((om & mOrganisationMode) == 0) {
      // 回退:优先 pass 分组,其次升序,最后降序
      if (OM_PASS_GROUP & mOrganisationMode)
        om = OM_PASS_GROUP;
      else if (OM_SORT_ASCENDING & mOrganisationMode)
        om = OM_SORT_ASCENDING;
      else if (OM_SORT_DESCENDING & mOrganisationMode)
        om = OM_SORT_DESCENDING;
    }
    switch (om) {
      case OM_PASS_GROUP:
        acceptVisitorGrouped(visitor);
        break;
      case OM_SORT_DESCENDING:
        acceptVisitorDescending(visitor);
        break;
      case OM_SORT_ASCENDING:
        acceptVisitorAscending(visitor);
        break;
    }
  }

 private:
  void acceptVisitorGrouped(QueuedRenderableVisitor* visitor) const {
    for (const auto& ipass : mGrouped) {
      if (ipass.second.empty()) continue;
      visitor->visit(ipass.first, const_cast<RenderableList&>(ipass.second));
    }
  }
  void acceptVisitorDescending(QueuedRenderableVisitor* visitor) const {
    // 列表已降序,正向迭代
    for (const auto& i : mSortedDescending) {
      visitor->visit(const_cast<RenderablePass*>(&i));
    }
  }
  void acceptVisitorAscending(QueuedRenderableVisitor* visitor) const {
    // 降序列表反向迭代 = 升序
    for (auto i = mSortedDescending.rbegin(); i != mSortedDescending.rend(); ++i) {
      visitor->visit(const_cast<RenderablePass*>(&(*i)));
    }
  }

  uint8_t mOrganisationMode;
  RenderablePassList mSortedDescending;
  std::map<Pass*, RenderableList> mGrouped;
};

// 统计降序/升序 visit 的 visitor
struct CountVisitor : QueuedRenderableVisitor {
  int renderablePassVisits = 0;
  int groupVisits = 0;
  int totalRenderables = 0;
  std::vector<int> order;

  void visit(RenderablePass* rp) override {
    renderablePassVisits++;
    order.push_back(rp->renderable->id);
  }
  void visit(const Pass*, RenderableList& rs) override {
    groupVisits++;
    totalRenderables += static_cast<int>(rs.size());
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  Renderable rA{1}, rB{2}, rC{3}, rD{4};
  Pass p1{1}, p2{2}, p3{3};

  // 降序 + 分组双组织:addRenderable 双写
  QueuedRenderableCollection coll(OM_PASS_GROUP | OM_SORT_DESCENDING);
  coll.addRenderable(&p1, &rA);
  coll.addRenderable(&p2, &rB);
  coll.addRenderable(&p1, &rC);  // p1 再挂一个
  coll.addRenderable(&p3, &rD);
  CHECK(coll.getSortedCount() == 4);       // 降序向量 4 条
  CHECK(coll.getGroupedPassCount() == 3);  // 分组 3 个 Pass

  // 降序访问:每条 RenderablePass 一次 visit,不触发分组 visit
  CountVisitor descVisitor;
  coll.acceptVisitor(&descVisitor, OM_SORT_DESCENDING);
  CHECK(descVisitor.renderablePassVisits == 4);
  CHECK(descVisitor.groupVisits == 0);
  CHECK(descVisitor.totalRenderables == 0);

  // 升序访问:同一次排序反向迭代
  CountVisitor ascVisitor;
  coll.acceptVisitor(&ascVisitor, OM_SORT_ASCENDING);
  CHECK(ascVisitor.renderablePassVisits == 4);
  // 反向 = 与降序顺序相反
  for (size_t i = 0; i < 4; ++i) {
    CHECK(ascVisitor.order[i] == descVisitor.order[3 - i]);
  }

  // 分组访问:每个 Pass 一次 visit(Pass*, list),物品总数守恒
  CountVisitor grpVisitor;
  coll.acceptVisitor(&grpVisitor, OM_PASS_GROUP);
  CHECK(grpVisitor.renderablePassVisits == 0);
  CHECK(grpVisitor.groupVisits == 3);
  CHECK(grpVisitor.totalRenderables == 4);

  // 单组织集合:只有降序位时 addRenderable 只写向量
  QueuedRenderableCollection sortedOnly(OM_SORT_DESCENDING);
  sortedOnly.addRenderable(&p1, &rA);
  sortedOnly.addRenderable(&p2, &rB);
  CHECK(sortedOnly.getSortedCount() == 2);
  CHECK(sortedOnly.getGroupedPassCount() == 0);

  CountVisitor soVisitor;
  sortedOnly.acceptVisitor(&soVisitor, OM_SORT_DESCENDING);
  CHECK(soVisitor.renderablePassVisits == 2);
  CHECK(soVisitor.groupVisits == 0);

  // 请求未声明的模式:回退到唯一可用组织
  CountVisitor fallbackVisitor;
  sortedOnly.acceptVisitor(&fallbackVisitor, OM_PASS_GROUP);  // 未声明,回退降序
  CHECK(fallbackVisitor.renderablePassVisits == 2);           // 实际走了降序访问
  CHECK(fallbackVisitor.groupVisits == 0);

  // 双组织集合请求未声明模式:回退优先级 PASS_GROUP > ASCENDING > DESCENDING
  CountVisitor fb2Visitor;
  coll.acceptVisitor(&fb2Visitor, static_cast<OrganisationMode>(0));  // 0 未声明
  CHECK(fb2Visitor.groupVisits == 3);     // 回退到 PASS_GROUP
  CHECK(fb2Visitor.totalRenderables == 4);
  CHECK(fb2Visitor.renderablePassVisits == 0);

  return lab::report("05-3 QueuedRenderable 与提交");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 22/22 通过。

小结

  • RenderablePass 是「渲染项 + Pass」二元组,降序集合的排序与访问单位。
  • QueuedRenderableVisitor 提供两种互斥回调:逐条 visit(RenderablePass*) 或每 Pass 一次 visit(Pass*, RenderableList&)。
  • addRenderable 按 mOrganisationMode 位双写:降序位进向量,分组位进 map。
  • acceptVisitor 对未声明模式按 PASS_GROUP → ASCENDING → DESCENDING 回退,全无才抛异常。
  • 升序就是降序向量反向迭代,排序本身只做一次。

阅读导航:上一节:5.2 排序策略 · 下一节:6.1 Compositor 后处理概念 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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