《OGRE 3D 渲染引擎原理与架构》6.2 CompositionPass 后处理通道

CompositionPass 是 CompositionTargetPass 里的单个操作:PassType 枚举六类通道,InputTex 把局部纹理按 id 绑到输入,ClearData/QuadData/RenderSceneData 各自持有默认参数。源码在 OgreMain/include/OgreCompositionPass.h。lab 复现通道类型、输入绑定与三类子状态的默认值。

6.2 CompositionPass 后处理通道

上一节的 CompositionTargetPass 是「对某 RenderTarget 的一次渲染」,它内部是一串通道(Pass)。每个通道就是一个 CompositionPass:清屏、写模板、渲染场景、画全屏四边形、跑自定义序列、派发 compute。这一节解剖这个类的类型枚举与它四组内部数据(材质、场景、清屏、四边形),它们决定了每个通道「做什么、用什么、默认值是什么」。

OgreCompositionPass.h 开头注释把它定义为在 Render Queue 之间插入 RenderSystem 命令的手段:

This provides a method to conveniently interleave RenderSystem commands between Render Queues.

PassType:六类通道

通道类型用 PassType 枚举表达,构造时默认就是 PT_RENDERQUAD(画全屏四边形):

// OgreMain/include/OgreCompositionPass.h:CompositionPass::PassType(v14.6.3 源码摘录,已删减)
        enum PassType
        {
            PT_CLEAR,           //!< Clear target to one colour
            PT_STENCIL,         //!< Set stencil operation
            PT_RENDERSCENE,     //!< Render the scene or part of it
            PT_RENDERQUAD,      //!< Render a full screen quad
            PT_RENDERCUSTOM,    //!< Render a custom sequence
            PT_COMPUTE          //!< dispatch a compute shader
        };
// OgreMain/src/OgreCompositionPass.cpp:CompositionPass 构造(v14.6.3 源码摘录,已删减)
CompositionPass::CompositionPass(CompositionTargetPass *parent):
    mParent(parent),
    mType(PT_RENDERQUAD)
{
}
类型作用关键 setter
PT_CLEAR用颜色/深度/模板清空目标setClearBuffers、setClearColour、setClearDepth
PT_STENCIL设置模板操作setStencilCheck、setStencilFunc、setStencilRefValue
PT_RENDERSCENE渲染场景(或其中一段 RenderQueue)setFirstRenderQueue、setLastRenderQueue
PT_RENDERQUAD全屏四边形,后处理主力setMaterial、setInput、setQuadCorners
PT_RENDERCUSTOM自定义序列(注册进 CompositorManager)setCustomType
PT_COMPUTE派发 compute shadersetThreadGroups

setType 只是个直白的赋值(mType = type),但真正的工作发生在 6.3 的 _compile 阶段——collectPasses 会按 mType 把每个通道翻译成 RenderSystem 操作。

RENDERQUAD:输入纹理与材质

后处理的全屏四边形要采样前面渲染好的中间纹理。InputTex 用「局部纹理名 + MRT 面索引」描述输入:

// OgreMain/include/OgreCompositionPass.h:CompositionPass::InputTex / setInput(v14.6.3 源码摘录,已删减)
        struct InputTex
        {
            /// Name (local) of the input texture (empty == no input)
            String name;
            /// MRT surface index if applicable
            size_t mrtIndex;
            InputTex() : mrtIndex(0) {}
            InputTex(const String& _name, size_t _mrtIndex = 0)
                : name(_name), mrtIndex(_mrtIndex) {}
        };
...
        void setInput(size_t id, const String &input=BLANKSTRING, size_t mrtIndex=0);

setInput 的第一个参数 id 是纹理单元号(0..OGRE_MAX_TEXTURE_LAYERS-1),第二个是局部纹理名——名字指向 CompositionTechnique 的 TextureDefinition,由 6.3 的编译期解析成真实纹理。MRT 场景下 mrtIndex 指明取多目标渲染纹理的第几面。空名字(BLANKSTRING)就是「清空该输入」;lab 里我们会验证 id 洞的中间项保持空。

通道的材质与输入同属 MaterialData 结构:identifier 用于让 CompositorInstance::Listener 能「听」到某个通道,material 才是真正画四边形用的材质。

CLEAR 与 RENDERSCENE:默认参数

非 RENDERQUAD 的通道各自携带默认参数。清屏通道的默认是「颜色+深度都清」,深度默认 1.0、模板默认 0、颜色默认 ZERO:

// OgreMain/include/OgreCompositionPass.h:CompositionPass::ClearData(v14.6.3 源码摘录,已删减)
        struct ClearData
        {
            /// Clear buffers
            uint32 buffers;
            /// Clear colour
            ColourValue colour;
            /// Clear colour with the colour of the original viewport. Overrides mClearColour
            bool automaticColour;
            /// Clear depth
            float depth;
            /// Clear stencil value
            uint16 stencil;

            ClearData()
                : buffers(FBT_COLOUR | FBT_DEPTH), colour(ColourValue::ZERO), automaticColour(false),
                  depth(1.0f), stencil(0)
            {
            }
        } mClear;

automaticColour 是「自动取原 viewport 背景色」,开启时覆盖 colour。场景通道的默认则覆盖不透明到透明的整段队列:

// OgreMain/include/OgreCompositionPass.h:CompositionPass::RenderSceneData(v14.6.3 源码摘录,已删减)
        struct RenderSceneData
        {
            /// [first,last] render queue to render this pass (in case of PT_RENDERSCENE)
            uint8 firstRenderQueue;
            uint8 lastRenderQueue;

            /// Material scheme name
            String materialScheme;

            RenderSceneData()
                : firstRenderQueue(RENDER_QUEUE_BACKGROUND), lastRenderQueue(RENDER_QUEUE_TRANSPARENTS),
                  alignCameraToFace(false)
            {
            }
        } mRenderScene;

四边形通道(RENDERQUAD)的默认几何是整个屏幕:QuadData 的默认矩形 rect(-1, 1, 1, -1),且 cornerModified=false 表示「未定制角落」。整套默认值的设计意图是:写 .material 脚本时只需要改差异项。

源码定位

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

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

下面用纯 C++ 复现 CompositionPass 的类型枚举、输入绑定与子状态默认值。它与 src/06-2-composition-pass.cpp 逐字节一致:

// file: src/06-2-composition-pass.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/06-2-composition-pass.cpp -o bin/06-2-composition-pass && ./bin/06-2-composition-pass
//
// 复现 CompositionPass 的通道类型与各子状态默认值(对应 OgreCompositionPass.h 53-408 与
// OgreCompositionPass.cpp 34-47):
//   PassType 六类枚举(CLEAR/STENCIL/RENDERSCENE/RENDERQUAD/RENDERCUSTOM/COMPUTE);
//   InputTex(name + mrtIndex) 绑定输入局部纹理;setInput 按 id 记录;
//   ClearData 默认 FBT_COLOUR|FBT_DEPTH、深度 1.0、stencil 0、automaticColour false;
//   QuadData 默认整屏归一化矩形 (-1,1,1,-1);
//   RenderSceneData 默认渲染队列 [RENDER_QUEUE_BACKGROUND, RENDER_QUEUE_TRANSPARENTS]。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <string>
#include <vector>

namespace ogre_repro {

enum class PassType : uint8_t {
  PT_CLEAR,
  PT_STENCIL,
  PT_RENDERSCENE,
  PT_RENDERQUAD,
  PT_RENDERCUSTOM,
  PT_COMPUTE
};

constexpr uint32_t FBT_COLOUR = 1u;
constexpr uint32_t FBT_DEPTH = 2u;
constexpr uint8_t RENDER_QUEUE_BACKGROUND = 0;
constexpr uint8_t RENDER_QUEUE_TRANSPARENTS = 12;

struct InputTex {
  std::string name;  // 空串 == 无输入
  size_t mrtIndex;
  InputTex() : mrtIndex(0) {}
  InputTex(const std::string& n, size_t idx) : name(n), mrtIndex(idx) {}
};

struct MaterialData {
  uint32_t identifier = 0;
  std::string materialName;
  std::vector<InputTex> inputs;  // 按输入 id 顺序记录
};

struct RenderSceneData {
  uint8_t firstRenderQueue = RENDER_QUEUE_BACKGROUND;
  uint8_t lastRenderQueue = RENDER_QUEUE_TRANSPARENTS;
  std::string materialScheme;
};

struct ClearData {
  uint32_t buffers = FBT_COLOUR | FBT_DEPTH;
  bool automaticColour = false;
  float depth = 1.0f;
  uint16_t stencil = 0;
};

struct QuadData {
  bool cornerModified = false;
  float left = -1.0f, top = 1.0f, right = 1.0f, bottom = -1.0f;  // rect(-1,1,1,-1)
  bool farCorners = false;
};

class CompositionPass {
 public:
  CompositionPass() : mType(PassType::PT_RENDERQUAD) {}
  void setType(PassType t) { mType = t; }
  PassType getType() const { return mType; }
  void setIdentifier(uint32_t id) { mMaterial.identifier = id; }
  uint32_t getIdentifier() const { return mMaterial.identifier; }
  void setMaterialName(const std::string& n) { mMaterial.materialName = n; }
  const std::string& getMaterialName() const { return mMaterial.materialName; }
  void setInput(size_t id, const std::string& name, size_t mrtIndex = 0) {
    if (id >= mMaterial.inputs.size()) mMaterial.inputs.resize(id + 1);
    mMaterial.inputs[id] = InputTex(name, mrtIndex);
  }
  const InputTex& getInput(size_t id) const { return mMaterial.inputs[id]; }
  size_t getNumInputs() const { return mMaterial.inputs.size(); }
  MaterialData mMaterial;
  ClearData mClear;
  QuadData mQuad;
  RenderSceneData mRenderScene;

 private:
  PassType mType;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  CompositionPass pass;
  // 默认类型是 RENDERQUAD(OgreCompositionPass.cpp 34-38)
  CHECK(pass.getType() == PassType::PT_RENDERQUAD);

  // 类型枚举覆盖六类
  pass.setType(PassType::PT_CLEAR);
  CHECK(pass.getType() == PassType::PT_CLEAR);
  pass.setType(PassType::PT_RENDERSCENE);
  CHECK(pass.getType() == PassType::PT_RENDERSCENE);

  // identifier 归 MaterialData 管
  pass.setIdentifier(7);
  CHECK_EQ(pass.getIdentifier(), uint32_t(7));

  // setInput:记录 name + mrtIndex
  pass.setInput(0, "rt_blur", 1);
  CHECK_EQ(pass.getNumInputs(), size_t(1));
  CHECK(pass.getInput(0).name == "rt_blur");
  CHECK_EQ(pass.getInput(0).mrtIndex, size_t(1));
  pass.setInput(2, "rt_lit");
  CHECK_EQ(pass.getNumInputs(), size_t(3));
  CHECK(pass.getInput(2).name == "rt_lit");
  CHECK_EQ(pass.getInput(2).mrtIndex, size_t(0));  // 默认 mrtIndex 0
  CHECK(pass.getInput(1).name.empty());            // 中间空输入

  // ClearData 默认值
  CHECK(pass.mClear.buffers == (FBT_COLOUR | FBT_DEPTH));
  CHECK(!pass.mClear.automaticColour);
  CHECK(pass.mClear.depth == 1.0f);
  CHECK_EQ(pass.mClear.stencil, uint16_t(0));

  // QuadData 默认整屏矩形
  CHECK(!pass.mQuad.cornerModified);
  CHECK(pass.mQuad.left == -1.0f && pass.mQuad.top == 1.0f);
  CHECK(pass.mQuad.right == 1.0f && pass.mQuad.bottom == -1.0f);
  CHECK(!pass.mQuad.farCorners);

  // RenderSceneData 默认渲染整个不透明+透明队列区间
  CHECK_EQ(pass.mRenderScene.firstRenderQueue, RENDER_QUEUE_BACKGROUND);
  CHECK_EQ(pass.mRenderScene.lastRenderQueue, RENDER_QUEUE_TRANSPARENTS);

  return lab::report("06-2 CompositionPass 后处理通道");
}

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

小结

  • PassType 六类通道枚举覆盖后处理的全部操作形态,构造默认 PT_RENDERQUAD。
  • InputTex 以「局部纹理名 + MRT 面索引」描述 RENDERQUAD 的输入,setInput 按纹理单元 id 绑定。
  • 每类通道有独立子状态结构:ClearData(清屏)、QuadData(四边形)、RenderSceneData(场景队列区间),默认值贴近「最常见的用法」。
  • 通道的 identifier 让 CompositorInstance::Listener 能在编译/渲染时精准介入。

阅读导航:上一节:6.1 Compositor 后处理概念 · 下一节:6.3 CompositorChain 实现 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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