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 的观测需要各自的场景。
源码定位
OgreMain/include/OgreRenderQueueSortingGrouping.h:RenderableList(45)、RenderablePass(51-59)、QueuedRenderableVisitor(69-90)、mSortedDescending/mGrouped(155-157)OgreMain/src/OgreRenderQueueSortingGrouping.cpp:addRenderable(382-403)、acceptVisitor(405-437)、acceptVisitorGrouped/Descending/Ascending(439-474)
上游引用固定到 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 后处理概念 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。