6.3 CompositorChain 实现
单个 Compositor 只是「配方」,真正把它应用到 viewport 的是 CompositorChain:它持有若干 CompositorInstance(每个 instance 对应一个 compositor 的激活状态),并提供增、删、查、编译的完整生命周期。这一节看链本身——实例怎么进出、位置怎么查、编译期怎么把 enabled 实例串成 mPreviousInstance 前驱链。
OgreCompositorChain.h 开头注释把链定位为「一组复合到一个目标上的 compositor 序列」:
A chain of Compositor instances, applied to a single RenderTarget.
addCompositor:LAST 哨兵追加
addCompositor 拿到 compositor 后先取受支持的 technique(跳过不兼容),新建 CompositorInstance 插入 mInstances 向量。addPosition == LAST 时追加到末尾:
// OgreMain/src/OgreCompositorChain.cpp:CompositorChain::addCompositor(v14.6.3 源码摘录,已删减)
CompositorInstance* CompositorChain::addCompositor(const CompositorPtr& filter, size_t addPosition, const String& scheme)
{
filter->touch();
CompositionTechnique *tech = filter->getSupportedTechnique(scheme);
if(!tech)
{
return 0;
}
CompositorInstance *t = OGRE_NEW CompositorInstance(tech, this);
if(addPosition == LAST)
addPosition = mInstances.size();
else
assert(addPosition <= mInstances.size() && "Index out of bounds.");
mInstances.insert(mInstances.begin()+addPosition, t);
mDirty = true;
mAnyCompositorsEnabled = true;
return t;
}
三个要点:LAST 是静态哨兵(等于 NPOS),插入后置 mDirty = true 要求下次重编译,并把 mAnyCompositorsEnabled 置真(一旦曾经有 compositor 激活,viewport 的自动清屏就要被接管)。注意位置插入用的是 assert 校验而非运行时错误。
removeCompositor 与 removeAllCompositors
删除同样接受 LAST 哨兵——不传索引时删最后一项:
// OgreMain/src/OgreCompositorChain.cpp:CompositorChain::removeCompositor / removeAllCompositors(v14.6.3 源码摘录,已删减)
void CompositorChain::removeCompositor(size_t index)
{
if(index == LAST)
index = mInstances.size() - 1;
assert (index < mInstances.size() && "Index out of bounds.");
Instances::iterator i = mInstances.begin() + index;
OGRE_DELETE *i;
mInstances.erase(i);
mDirty = true;
}
//-----------------------------------------------------------------------
void CompositorChain::removeAllCompositors()
{
for (auto *i : mInstances)
{
OGRE_DELETE i;
}
mInstances.clear();
mDirty = true;
}
getCompositorPosition:按名定位
查询按 compositor 的名字线性扫描,找不到返回 NPOS:
// OgreMain/src/OgreCompositorChain.cpp:CompositorChain::getCompositorPosition(v14.6.3 源码摘录,已删减)
size_t CompositorChain::getCompositorPosition(const String& name) const
{
for (auto it = mInstances.begin(); it != mInstances.end(); ++it)
{
if ((*it)->getCompositor()->getName() == name)
{
return std::distance(mInstances.begin(), it);
}
}
return NPOS;
}
CompositorInstance *CompositorChain::getCompositor(const String& name) const
{
size_t idx = getCompositorPosition(name);
return idx == NPOS ? NULL : mInstances[idx];
}
链规模通常个位数,线性扫描足够;getCompositor 在 NPOS 时返回空指针,调用方需判空。
_compile:把 enabled 实例串成前驱链
编译是链的核心动作。它先按 material scheme 重建原场景(mOriginalScene),然后把每个 enabled 实例链接成单链表——原场景永远打头,禁用的实例被跳过:
// OgreMain/src/OgreCompositorChain.cpp:CompositorChain::_compile(v14.6.3 源码摘录,已删减)
/// Set previous CompositorInstance for each compositor in the list
CompositorInstance *lastComposition = mOriginalScene;
mOriginalScene->mPreviousInstance = 0;
for(auto *i : mInstances)
{
if(i->getEnabled())
{
compositorsEnabled = true;
i->mPreviousInstance = lastComposition;
lastComposition = i;
}
}
/// Compile misc targets
lastComposition->_compileTargetOperations(mCompiledState);
/// Final target viewport (0)
mOutputOperation.renderSystemOperations.clear();
lastComposition->_compileOutputOperation(mOutputOperation);
mPreviousInstance 是 6.1 里 IM_PREVIOUS 的实体:每个 compositor 的输入「吃」链上前一个 instance 的输出。链尾的 lastComposition 再把 target operations 和最终输出操作分别编译进 mCompiledState / mOutputOperation。编译完成后清 mDirty,之后 viewport 每帧只要重放编译好的操作序列即可。
lab 里我们验证三点:禁用中间实例后重编译,前一个 enabled 实例成为下一个的前驱(跳过的实例不参与链接);LAST 删除与插入的正确性;编译前后 mDirty 翻转。
后处理纹理生产与消费
flowchart LR
Scene["源场景或前一实例输出"] --> Target["CompositionTargetPass"]
Target --> Operations["清理、场景、四边形等操作"]
Operations --> Tex["中间渲染纹理"]
Tex --> Quad["后续 Pass 将纹理作为输入"]
Quad --> Out["输出目标与 Viewport"]
Chain["CompositorChain 启用实例顺序"] -.-> Target
Chain -.-> Quad
一次后处理从脚本到目标读写
每个启用的 Compositor 实例参与同一个 Viewport 的链。目标定义描述写入位置,操作定义描述如何填充它。后续 Pass 引用前序纹理时,读写顺序和池化复用必须满足该引用的存活区间。
为两段处理列出写入目标、采样输入、格式和尺寸。关闭中间处理或改窗口大小后,检查输出目标的来源,以及纹理何时重建。 OGRE Compositor 手册
处理目标变化时追踪纹理消费者
flowchart TD
D["Compositor 定义"] --> I["视口上的实例"]
I --> P["编译启用实例的目标操作"]
P --> A["向前序中间目标写入"]
A --> B["后序 Pass 读取指定纹理或 MRT 切片"]
B --> C["写输出目标"]
W["尺寸或链配置改变"] --> R["检查相关纹理和目标是否重建"]
R --> P
A -.-> L["读到最后一处前保持有效"]
B -.-> L
可以先用Metal 两级离屏实验 验证纹理生产与采样,再对照本节 CompositorChain 如何组织同样的依赖。实验使用显式更新目标,脚本解析、池化及链重编译由本节源码解释。
源码定位
OgreMain/include/OgreCompositorChain.h:LAST/NPOS静态常量(76-77)、addCompositor(168)、removeCompositor(174)、_compile(235)OgreMain/src/OgreCompositorChain.cpp:addCompositor(140-161)、removeCompositor(163-174)、removeAllCompositors(181-190)、getCompositorPosition(209-224)、_compile(468-523)OgreMain/include/OgreCompositorInstance.h:mPreviousInstance(331)、getPreviousInstance(172)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现 CompositorChain 的实例链表管理:增删查 + 编译期前驱链接。它与 src/06-3-compositor-chain.cpp 逐字节一致:
// file: src/06-3-compositor-chain.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/06-3-compositor-chain.cpp -o bin/06-3-compositor-chain && ./bin/06-3-compositor-chain
//
// 复现 CompositorChain 的实例链表管理(对应 OgreCompositorChain.h 56-251 与
// OgreCompositorChain.cpp 140-231、468-531):
// addCompositor:LAST 追加到末尾,否则按 addPosition 插入;插入后 mDirty=true;
// removeCompositor:LAST 取最后一项删除;removeAllCompositors 清空;
// getCompositorPosition:按名字查位置,找不到返回 NPOS;
// _compile:沿实例表链接 mPreviousInstance(原场景打头),把 enabled 实例编译成
// TargetOperation 序列并清 dirty。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <string>
#include <vector>
namespace ogre_repro {
enum class PassType : uint8_t { PT_RENDERQUAD, PT_RENDERSCENE };
class CompositionPass {
public:
explicit CompositionPass(PassType t) : mType(t) {}
PassType getType() const { return mType; }
private:
PassType mType;
};
class CompositionTargetPass {
public:
CompositionPass* createPass(PassType t = PassType::PT_RENDERQUAD) {
mPasses.push_back(new CompositionPass(t));
return mPasses.back();
}
size_t getNumPasses() const { return mPasses.size(); }
std::vector<CompositionPass*> mPasses;
};
class CompositionTechnique {
public:
CompositionTargetPass* createTargetPass() {
auto* tp = new CompositionTargetPass();
mTargetPasses.push_back(tp);
return tp;
}
size_t getNumTargetPasses() const { return mTargetPasses.size(); }
std::vector<CompositionTargetPass*> mTargetPasses;
};
class CompositorInstance {
public:
CompositorInstance(const std::string& name, CompositionTechnique* tech)
: mPreviousInstance(nullptr), mTechnique(tech), mName(name), mEnabled(true) {}
const std::string& getName() const { return mName; }
bool getEnabled() const { return mEnabled; }
void setEnabled(bool e) { mEnabled = e; }
CompositorInstance* mPreviousInstance;
CompositionTechnique* mTechnique;
private:
std::string mName;
bool mEnabled;
};
class CompositorChain {
public:
static constexpr size_t LAST = static_cast<size_t>(-1);
static constexpr size_t NPOS = LAST;
CompositorInstance* addCompositor(const std::string& name, size_t addPosition = LAST) {
auto* inst = new CompositorInstance(name, new CompositionTechnique());
if (addPosition == LAST) addPosition = mInstances.size();
mInstances.insert(mInstances.begin() + static_cast<long>(addPosition), inst);
mDirty = true;
mAnyCompositorsEnabled = true;
return inst;
}
void removeCompositor(size_t index) {
if (index == LAST) index = mInstances.size() - 1;
delete mInstances[index];
mInstances.erase(mInstances.begin() + static_cast<long>(index));
mDirty = true;
}
void removeAllCompositors() {
for (auto* i : mInstances) delete i;
mInstances.clear();
mDirty = true;
}
size_t getCompositorPosition(const std::string& name) const {
for (size_t i = 0; i < mInstances.size(); ++i)
if (mInstances[i]->getName() == name) return i;
return NPOS;
}
CompositorInstance* getCompositor(const std::string& name) const {
size_t idx = getCompositorPosition(name);
return idx == NPOS ? nullptr : mInstances[idx];
}
// 对应 _compile:链接 enabled 实例的 mPreviousInstance,首节点是"原场景"
void compile() {
CompositorInstance* last = mOriginalScene;
mOriginalScene->mPreviousInstance = nullptr;
mCompiledTargets = 0;
for (auto* i : mInstances) {
if (i->getEnabled()) {
i->mPreviousInstance = last;
last = i;
++mCompiledTargets;
}
}
mDirty = false;
}
CompositorInstance* mOriginalScene = nullptr;
std::vector<CompositorInstance*> mInstances;
bool mDirty = false;
bool mAnyCompositorsEnabled = false;
size_t mCompiledTargets = 0;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
CompositorChain chain;
chain.mOriginalScene = new CompositorInstance("OriginalScene", new CompositionTechnique());
// addCompositor:默认追加到末尾
auto* blur = chain.addCompositor("Blur");
auto* glow = chain.addCompositor("Glow");
auto* bloom = chain.addCompositor("Bloom");
CHECK_EQ(chain.mInstances.size(), size_t(3));
CHECK(chain.mDirty);
CHECK(chain.mInstances[0]->getName() == "Blur");
CHECK(chain.mInstances[2]->getName() == "Bloom");
CHECK(chain.getCompositor("Blur") == blur);
CHECK(chain.getCompositor("Glow") == glow);
// 按位置插入
auto* aa = chain.addCompositor("AA", 1);
CHECK(chain.mInstances[1]->getName() == "AA");
CHECK(chain.mInstances[1] == aa);
CHECK_EQ(chain.mInstances.size(), size_t(4));
// getCompositorPosition:命中与 NPOS
CHECK_EQ(chain.getCompositorPosition("Glow"), size_t(2));
CHECK(chain.getCompositor("Bloom") == bloom);
CHECK_EQ(chain.getCompositorPosition("Nonexistent"), CompositorChain::NPOS);
CHECK(chain.getCompositor("Nonexistent") == nullptr);
// removeCompositor:LAST 删除最后一个
chain.removeCompositor(CompositorChain::LAST);
CHECK_EQ(chain.mInstances.size(), size_t(3));
CHECK(chain.mInstances.back()->getName() == "Glow");
chain.removeCompositor(0);
CHECK(chain.mInstances[0]->getName() == "AA");
// _compile:按 enabled 实例建立 previous 链
chain.mDirty = true;
chain.compile();
CHECK(!chain.mDirty);
CHECK_EQ(chain.mCompiledTargets, size_t(2));
CHECK(chain.mInstances[0]->mPreviousInstance == chain.mOriginalScene);
CHECK(chain.mInstances[1]->mPreviousInstance == chain.mInstances[0]);
// 禁用中间实例后重编译:前一实例成为 next 的前驱
chain.mInstances[0]->setEnabled(false);
chain.compile();
CHECK_EQ(chain.mCompiledTargets, size_t(1));
CHECK(chain.mInstances[1]->mPreviousInstance == chain.mOriginalScene);
// removeAllCompositors
chain.removeAllCompositors();
CHECK_EQ(chain.mInstances.size(), size_t(0));
CHECK(chain.mDirty);
return lab::report("06-3 CompositorChain 实现");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 24/24 通过。
小结
CompositorChain用mInstances向量管理激活的 compositor 实例,LAST/NPOS是同一个哨兵值。addCompositor追加或按位置插入,插入/删除都置mDirty;getCompositorPosition按名线性查找、找不到返回NPOS。_compile把 enabled 实例串成mPreviousInstance单链表,mOriginalScene永远打头,禁用的实例被跳过。- 编译产物分为
mCompiledState(中间 target 操作)与mOutputOperation(最终输出操作),此后每帧只需重放。
阅读导航:上一节:6.2 CompositionPass 后处理通道 · 下一节:7.1 GL3Plus 渲染系统 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。