《OGRE 3D 渲染引擎原理与架构》6.3 CompositorChain 实现

CompositorChain 把多个 compositor 实例串成一条链:addCompositor 用 LAST 哨兵追加,removeCompositor 支持按索引删除,getCompositorPosition 找不到返回 NPOS,_compile 沿实例表链接 mPreviousInstance 并以原场景打头。源码在 OgreMain/src/OgreCompositorChain.cpp。lab 复现链表增删查与 enabled 实例的前驱链接。

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 如何组织同样的依赖。实验使用显式更新目标,脚本解析、池化及链重编译由本节源码解释。

源码定位

上游引用固定到 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 渲染系统 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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