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 shader | setThreadGroups |
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 脚本时只需要改差异项。
源码定位
OgreMain/include/OgreCompositionPass.h:PassType(54-62)、InputTex(234-243)、setInput(251)、MaterialData(330-341)、RenderSceneData(344-362)、ClearData(365-383)、QuadData(392-404)OgreMain/src/OgreCompositionPass.cpp:构造默认PT_RENDERQUAD(34-38)、setType(44-47)OgreMain/include/OgreCompositionTargetPass.h:createPass(130)OgreMain/src/OgreCompositionTargetPass.cpp:createPass实现(125-136)
上游引用固定到 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 实现 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。