13.2 模板测试
模板缓冲是深度缓冲的「表兄弟」:它也在逐像素管线上做一次测试,只是比较对象由你写入的整数。镜子、剪影、模板阴影都要它。OGRE 不把模板状态拆成一堆散参数,而是收进一个 StencilState 结构,RenderSystem::setStencilState 一次整体下发。这一节看这个结构长什么样,以及 RenderSystem 基类是怎么门控「改缓存」与「真下发」的。
本章与站内既有内容的分工
cg 三卷讲模板测试的图形学语义(参考值、比较、三种结果动作),这里讲 OGRE 如何用 StencilState 把语义落成字段;卷一 ogre-core 的 Pass 持有材质级模板参数,这里讲 RenderSystem 怎么把它们聚合进 mStencilState 并批量下发。
StencilState:一次说清九个字段
模板测试的完整描述需要三类信息:比较函数、三种分支的动作、参考值与掩码。OGRE 把它们全部塞进一个结构:
// OgreMain/include/OgreRenderSystem.h:StencilState 结构(v14.6.3 源码摘录,已删减)
struct _OgreExport StencilState
{
/// Comparison operator for the stencil test
CompareFunction compareOp;
/// The action to perform when the stencil check fails
StencilOperation stencilFailOp;
/// The action to perform when the stencil check passes, but the depth buffer check fails
StencilOperation depthFailOp;
/// The action to take when both the stencil and depth check pass
StencilOperation depthStencilPassOp;
/// The reference value used in the stencil comparison
uint32 referenceValue;
/// The bitmask applied to both the stencil value and the reference value before comparison
uint32 compareMask;
/** The bitmask the controls which bits from stencilRefValue will be written to stencil buffer
(valid for operations such as #SOP_REPLACE) */
uint32 writeMask;
/// Turns stencil buffer checking on or off
bool enabled : 1;
/// Toggles two-sided stencil operation, which swaps increment and decrement for back-facing polygons.
bool twoSidedOperation : 1;
StencilState()
: compareOp(CMPF_LESS_EQUAL), stencilFailOp(SOP_KEEP), depthFailOp(SOP_KEEP),
depthStencilPassOp(SOP_KEEP), referenceValue(0), compareMask(0xFFFFFFFF),
writeMask(0xFFFFFFFF), enabled(false), twoSidedOperation(false)
{
}
};
| 字段 | 角色 |
|---|---|
compareOp | 比较函数,见下节 CompareFunction |
stencilFailOp | 模板测试失败时的动作 |
depthFailOp | 模板通过但深度测试失败时的动作 |
depthStencilPassOp | 模板与深度都通过时的动作 |
referenceValue | 参考值,参与比较 |
compareMask | 比较前对参考值与缓冲值的位掩码 |
writeMask | 写入模板缓冲时允许改写的位 |
enabled | 是否开启模板测试 |
twoSidedOperation | 背面是否交换增/减操作 |
三个动作类型本身是 StencilOperation 枚举,SOP_* 前八个取值一一对应 GPU 的固定指令(KEEP/ZERO/REPLACE/INCREMENT/DECREMENT/INCREMENT_WRAP/DECREMENT_WRAP/INVERT)。位掩码 enabled : 1 / twoSidedOperation : 1 是 C++ 位域,把两个布尔压进同一字节。
CompareFunction:比较函数枚举
compareOp 用的 CompareFunction 定义在 OgreCommon.h,供深度与模板两处共用:
// OgreMain/include/OgreCommon.h:CompareFunction 枚举(v14.6.3 源码摘录,已删减)
enum CompareFunction : uint8
{
CMPF_ALWAYS_FAIL, //!< Never writes a pixel to the render target
CMPF_ALWAYS_PASS, //!< Always writes a pixel to the render target
CMPF_LESS, //!< Write if (new_Z < existing_Z)
CMPF_LESS_EQUAL, //!< Write if (new_Z <= existing_Z)
CMPF_EQUAL, //!< Write if (new_Z == existing_Z)
CMPF_NOT_EQUAL, //!< Write if (new_Z != existing_Z)
CMPF_GREATER_EQUAL,//!< Write if (new_Z >= existing_Z)
CMPF_GREATER //!< Write if (new_Z >= existing_Z)
};
CMPF_ALWAYS_FAIL/CMPF_ALWAYS_PASS 是常开常关的快捷方式;CMPF_LESS 之类与深度测试的 new_Z/existing_Z 注释共用,模板测试时把 Z 换成「参考值 & 掩码 vs 缓冲值 & 掩码」即可。StencilState 的默认 compareOp 是 CMPF_LESS_EQUAL。
门控:缓存与下发分离
setStencilState 是纯虚函数,真正下发留给各后端。基类提供两个聚合入口,它们只改 mStencilState,且只在需要时才调 setStencilState:
// OgreMain/src/OgreRenderSystem.cpp:RenderSystem::setStencilCheckEnabled/setStencilBufferParams(v14.6.3 源码摘录,已删减)
void RenderSystem::setStencilCheckEnabled(bool enabled)
{
mStencilState.enabled = enabled;
if (!enabled)
setStencilState(mStencilState);
}
void RenderSystem::setStencilBufferParams(CompareFunction func, uint32 refValue, uint32 compareMask,
uint32 writeMask, StencilOperation stencilFailOp,
StencilOperation depthFailOp, StencilOperation passOp,
bool twoSidedOperation)
{
mStencilState.compareOp = func;
mStencilState.referenceValue = refValue;
mStencilState.compareMask = compareMask;
mStencilState.writeMask = writeMask;
mStencilState.stencilFailOp = stencilFailOp;
mStencilState.depthFailOp = depthFailOp;
mStencilState.depthStencilPassOp = passOp;
mStencilState.twoSidedOperation = twoSidedOperation;
if(mStencilState.enabled)
setStencilState(mStencilState);
}
| 场景 | 行为 |
|---|---|
| 关闭状态改参数 | 只写 mStencilState 缓存,不下发(因为没开模板) |
setStencilCheckEnabled(true) | 只置位,不下发——真正的下发等下一次 setStencilBufferParams |
setStencilCheckEnabled(false) | 置位后强制下发一次,让后端真正停用模板 |
| 开启状态改参数 | 每次都调用 setStencilState 整体下发 |
这个「改缓存与真下发分离」的设计让多次 setStencilBufferParams 合并成一次 API 调用,也保证关闭模板这条路径不会被遗漏——即使参数没变,也要通知后端停用。
源码定位
OgreMain/include/OgreRenderSystem.h:StencilOperation枚举(79-96)、StencilState结构(114-144)、mStencilState成员(1240)、setStencilState纯虚(791)OgreMain/include/OgreCommon.h:CompareFunction枚举(61-71)OgreMain/src/OgreRenderSystem.cpp:setStencilCheckEnabled(926-931)、setStencilBufferParams(932-949)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现 StencilState 的默认值、枚举语义与 enabled 门控。它与 src/13-2-stencil.cpp 逐字节一致:
// file: src/13-2-stencil.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/13-2-stencil.cpp -o bin/13-2-stencil && ./bin/13-2-stencil
//
// 复现 StencilState 状态聚合与「enabled 才下发」的门控(对应 OgreRenderSystem.cpp 926-949):
// setStencilBufferParams 先改写 mStencilState 九个字段;
// 仅当 mStencilState.enabled 为真时才调用 setStencilState 真正下发;
// setStencilCheckEnabled(false) 强制下发一次(关掉也要让后端停用模板)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
namespace ogre_repro {
// 对应 OgreCommon.h 的 CompareFunction 枚举
enum CompareFunction : uint8_t {
CMPF_ALWAYS_FAIL = 0,
CMPF_ALWAYS_PASS,
CMPF_LESS,
CMPF_LESS_EQUAL,
CMPF_EQUAL,
CMPF_NOT_EQUAL,
CMPF_GREATER_EQUAL,
CMPF_GREATER
};
// 对应 OgreRenderSystem.h 的 StencilOperation 枚举
enum StencilOperation {
SOP_KEEP = 0,
SOP_ZERO,
SOP_REPLACE,
SOP_INCREMENT,
SOP_DECREMENT,
SOP_INCREMENT_WRAP,
SOP_DECREMENT_WRAP,
SOP_INVERT
};
// 对应 OgreRenderSystem.h 的 StencilState 结构
struct StencilState {
CompareFunction compareOp;
StencilOperation stencilFailOp;
StencilOperation depthFailOp;
StencilOperation depthStencilPassOp;
uint32_t referenceValue;
uint32_t compareMask;
uint32_t writeMask;
bool enabled : 1;
bool twoSidedOperation : 1;
StencilState()
: compareOp(CMPF_LESS_EQUAL),
stencilFailOp(SOP_KEEP),
depthFailOp(SOP_KEEP),
depthStencilPassOp(SOP_KEEP),
referenceValue(0),
compareMask(0xFFFFFFFF),
writeMask(0xFFFFFFFF),
enabled(false),
twoSidedOperation(false) {}
};
class RenderSystemRepro {
public:
StencilState mStencilState; // 对应 RenderSystem::mStencilState
int mFlushCount = 0; // 模拟 setStencilState 的下发次数
// 对应 setStencilState 的计数替身
void setStencilState(const StencilState&) { ++mFlushCount; }
// 对应 RenderSystem::setStencilCheckEnabled
void setStencilCheckEnabled(bool enabled) {
mStencilState.enabled = enabled;
if (!enabled) setStencilState(mStencilState);
}
// 对应 RenderSystem::setStencilBufferParams
void setStencilBufferParams(CompareFunction func, uint32_t refValue, uint32_t compareMask,
uint32_t writeMask, StencilOperation stencilFailOp,
StencilOperation depthFailOp, StencilOperation passOp,
bool twoSidedOperation) {
mStencilState.compareOp = func;
mStencilState.referenceValue = refValue;
mStencilState.compareMask = compareMask;
mStencilState.writeMask = writeMask;
mStencilState.stencilFailOp = stencilFailOp;
mStencilState.depthFailOp = depthFailOp;
mStencilState.depthStencilPassOp = passOp;
mStencilState.twoSidedOperation = twoSidedOperation;
if (mStencilState.enabled) setStencilState(mStencilState);
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 默认值:模板默认关闭、比较函数 LESS_EQUAL、掩码全开
StencilState s;
CHECK(s.compareOp == CMPF_LESS_EQUAL);
CHECK(s.stencilFailOp == SOP_KEEP);
CHECK(s.depthFailOp == SOP_KEEP);
CHECK(s.depthStencilPassOp == SOP_KEEP);
CHECK_EQ(s.referenceValue, 0u);
CHECK_EQ(s.compareMask, 0xFFFFFFFFu);
CHECK_EQ(s.writeMask, 0xFFFFFFFFu);
CHECK(!s.enabled);
CHECK(!s.twoSidedOperation);
// 枚举数值顺序即文档语义
CHECK_EQ(static_cast<int>(CMPF_ALWAYS_FAIL), 0);
CHECK_EQ(static_cast<int>(CMPF_GREATER), 7);
CHECK_EQ(static_cast<int>(SOP_INVERT), 7);
RenderSystemRepro rs;
// 初始 disabled:改参数只写缓存,不下发
rs.setStencilBufferParams(CMPF_LESS, 1, 0xFFFFFFFFu, 0xFFFFFFFFu, SOP_KEEP, SOP_KEEP,
SOP_REPLACE, false);
CHECK_EQ(rs.mFlushCount, 0);
CHECK(rs.mStencilState.compareOp == CMPF_LESS);
CHECK_EQ(rs.mStencilState.referenceValue, 1u);
// 开启模板:setStencilCheckEnabled(true) 只置位,下发由后续 setStencilBufferParams 触发
rs.setStencilCheckEnabled(true);
CHECK_EQ(rs.mFlushCount, 0);
CHECK(rs.mStencilState.enabled);
// enabled 后改参数:每次调用都下发一次
rs.setStencilBufferParams(CMPF_NOT_EQUAL, 5, 0x00FF0000u, 0x000000FFu, SOP_INCREMENT,
SOP_DECREMENT, SOP_REPLACE, true);
CHECK_EQ(rs.mFlushCount, 1);
CHECK(rs.mStencilState.compareOp == CMPF_NOT_EQUAL);
CHECK_EQ(rs.mStencilState.compareMask, 0x00FF0000u);
CHECK(rs.mStencilState.twoSidedOperation);
// 关闭模板:即使状态没变也强制下发一次,让后端停用
rs.setStencilCheckEnabled(false);
CHECK_EQ(rs.mFlushCount, 2);
CHECK(!rs.mStencilState.enabled);
// 关闭后再改参数:只写缓存,不再下发
rs.setStencilBufferParams(CMPF_EQUAL, 9, 0xFFFFFFFFu, 0xFFFFFFFFu, SOP_ZERO, SOP_KEEP,
SOP_INVERT, false);
CHECK_EQ(rs.mFlushCount, 2);
CHECK(rs.mStencilState.compareOp == CMPF_EQUAL);
return lab::report("13-2 模板测试");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 25/25 通过。
小结
StencilState把模板测试的九个字段聚成一个对象,setStencilState一次整体下发。CompareFunction与StencilOperation是深度/模板共用或模板专用的小枚举,取值顺序即语义。setStencilBufferParams总是先改缓存;只有enabled时才真正调用setStencilState。setStencilCheckEnabled(false)强制下发一次,保证关闭路径不被遗漏。- 位域布尔(
enabled : 1、twoSidedOperation : 1)把两个开关压进一个字节。
阅读导航:上一节:13.1 深度缓冲 · 下一节:13.3 深度缓冲管理 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。