《OGRE 3D 渲染引擎原理与架构》13.2 模板测试

StencilState 结构把模板测试的全部参数聚合成一个对象:比较函数、三种操作、参考值与三个掩码、enabled 与双面标记。CompareFunction 枚举来自 OgreCommon.h。setStencilBufferParams 先改缓存,仅当 enabled 才调用 setStencilState 下发。lab 复现门控语义。

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 调用,也保证关闭模板这条路径不会被遗漏——即使参数没变,也要通知后端停用。

源码定位

上游引用固定到 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 深度缓冲管理 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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