《OGRE 3D 渲染引擎原理与架构》5.3 纹理阴影与投射

纹理阴影的纹理资源由 ShadowTextureManager 池化管理:按宽度/高度/深度/类型/格式/FSAA 全量匹配、命中复用否则新建,空纹理 1×1 按格式复用,引用回落到资源系统阈值才清理。投射端用纯黑或阴影色作 caster 环境光,材质自带 shadowCasterMaterial 优先于自定义 caster pass。lab 复现池与 caster 推导。

5.3 纹理阴影与投射

5.1 定了位标志、5.2 摆了相机,本节把纹理本身管起来。每帧渲染阴影纹理不能反复创建销毁 GPU 资源,所以 OGRE 用一个 ShadowTextureManager 单例做池化:按配置全量匹配,命中就复用,否则新建;引用数回落到「池 + 资源系统」的基线才清理。投射端则是 caster 渲染:把场景几何画进阴影纹理时,用什么材质、什么环境光,由 TextureShadowRenderer 统一推导。

本章与站内既有内容的分工

cg 图形学与 ogre-render 讲过「深度图怎么在 shader 里采样」,本节讲的是引擎侧的资源生命周期:纹理从哪来、何时复用、何时销毁。5.2 的相机只决定深度图拍什么,5.1 的 ShadowTechnique 只决定要不要纹理——本节补上「纹理这个 GPU 对象本身」。caster 材质推导与 Material::setShadowCasterMaterial 联动,属于材质系统在阴影流程里的专用路径。

阴影纹理池:按配置匹配,否则创建

池的配置对象是 ShadowTextureConfig。注意它的默认值:512×512、深度 1、PF_BYTE_RGBA、2D 纹理——这就是不开任何配置时阴影纹理的出厂规格:

// OgreMain/include/OgreSceneManager.h:struct ShadowTextureConfig(v14.6.3 源码摘录,已删减)
    /** Structure containing the configuration for one shadow texture. */
    struct ShadowTextureConfig
    {
        uint32 width;
        uint32 height;
        uint32 depth;
        PixelFormat format;
        uint16      depthBufferPoolId;
        uint16      extraFlags;
        uint8       fsaa;
        TextureType type;

        ShadowTextureConfig()
            : width(512), height(512), depth(1), format(PF_BYTE_RGBA), depthBufferPoolId(1), extraFlags(0), fsaa(0),
              type(TEX_TYPE_2D)
        {
        }
    };

ShadowTextureManager 内部维护两张表:mTextureList 存渲染目标纹理,mNullTextureList 存空纹理。getShadowTextures 先按全量字段匹配池中现有纹理,匹配条件比上面的 operator== 更严——宽度/高度/深度/类型/格式/FSAA 六项全中才复用;同一帧里用过的纹理还要跳过,避免一张纹理同时服务两个光源。都没命中就新建,名字用 mCount 递增:

// OgreMain/src/OgreShadowTextureManager.cpp:getShadowTextures(匹配与新建)(v14.6.3 源码摘录,已删减)
        for (ShadowTextureConfig& config : configList)
        {
            bool found = false;
            for (auto & tex : mTextureList)
            {
                // Skip if already used this one
                if (usedTextures.find(tex.get()) != usedTextures.end())
                    continue;

                if (config.width == tex->getWidth() && config.height == tex->getHeight() &&
                    config.depth == tex->getDepth() && config.type == tex->getTextureType() &&
                    config.format == tex->getFormat() && config.fsaa == tex->getFSAA())
                {
                    // Ok, a match
                    listToPopulate.push_back(tex);
                    usedTextures.insert(tex.get());
                    found = true;
                    break;
                }
            }
            if (!found)
            {
                // Create a new texture
                String targName = StringUtil::format("Ogre/ShadowTexture%zu", mCount++);
                TexturePtr shadowTex = TextureManager::getSingleton().createManual(
                    targName, RGN_INTERNAL, config.type, config.width, config.height, config.depth, 0, config.format,
                    TU_RENDERTARGET | config.extraFlags, NULL, false, config.fsaa);
                OgreAssert(shadowTex, "Unsupported shadow texture configuration");
                ...
                config.format = shadowTex->getFormat();
                listToPopulate.push_back(shadowTex);
                usedTextures.insert(shadowTex.get());
                mTextureList.push_back(shadowTex);
            }
        }

新建后还有一个细节:config.format = shadowTex->getFormat() 回写实际格式——请求的格式若不被驱动支持,以实际创建的为准。所以第一帧建了两张,第二帧同样配置就会原样复用,mTextureList 不再增长。

配套的 operator== 却只比较三个字段。这是 OGRE 里的一个精简写法:它主要用于配置列表对比,而池内匹配另有更严的全量判断:

// OgreMain/src/OgreShadowTextureManager.cpp:operator==(v14.6.3 源码摘录,已删减)
    bool operator== ( const ShadowTextureConfig& lhs, const ShadowTextureConfig& rhs )
    {
        if ( lhs.width != rhs.width ||
            lhs.height != rhs.height ||
            lhs.format != rhs.format )
        {
            return false;
        }

        return true;
    }
对比口径比较字段用途
operator==宽度、高度、格式配置列表级对比(宽松)
getShadowTextures 内联匹配宽度、高度、深度、类型、格式、FSAA池内纹理复用(严格)

空纹理与延迟清理

getNoShadowTexture 提供「永远不产生阴影」的兜底纹理:按格式在 mNullTextureList 里找,找不到就建一张 1×1 的非渲染目标纹理。名字同样走共享的 mCount。深度格式直接返回(像素无法写入),否则把所有字节填成高值——对非深度格式意味着「完全不在阴影中」:

// OgreMain/src/OgreShadowTextureManager.cpp:getNoShadowTexture(v14.6.3 源码摘录,已删减)
        // not found, create a new one
        // A 1x1 texture of the correct format, not a render target
        static const String baseName = "Ogre/ShadowTextureNull";
        String targName = baseName + StringConverter::toString(mCount++);
        TexturePtr shadowTex = TextureManager::getSingleton().createManual(
            targName, 
            ResourceGroupManager::INTERNAL_RESOURCE_GROUP_NAME, 
            TEX_TYPE_2D, 1, 1, 0, format, TU_STATIC_WRITE_ONLY);
        mNullTextureList.push_back(shadowTex);

        // lock & populate the texture based on format
        if(PixelUtil::isDepth(format))
            return shadowTex;

        HardwareBufferLockGuard shadowTexLock(shadowTex->getBuffer(), HardwareBuffer::HBL_DISCARD);
        const PixelBox& box = shadowTex->getBuffer()->getCurrentLock();

        // set high-values across all bytes of the format 
        PixelUtil::packColour( 1.0f, 1.0f, 1.0f, 1.0f, shadowTex->getFormat(), box.data );

        return shadowTex;

清理是「延迟」的:clearUnused 只在每帧渲染完被调用,不立即销毁。判断依据是 shared_ptr::use_count()——OGRE 资源系统每张纹理固定持有 RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS(值为 3)个引用,因此「没人再引用」等价于引用数恰好等于 3 + 1(池自己的一份加资源系统的三份):

// OgreMain/src/OgreShadowTextureManager.cpp:clearUnused(v14.6.3 源码摘录,已删减)
            // Unreferenced if only this reference and the resource system
            // Any cached shadow textures should be re-bound each frame dropping
            // any old references
            if ((*i).use_count() == ResourceGroupManager::RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1)
            {
                TextureManager::getSingleton().remove((*i)->getHandle());
                i = mTextureList.erase(i);
            }
            else
            {
                ++i;
            }

use_count 会精确命中基线 4 的情形很罕见——因为引用计数是精确的整数。缓存引用会逐帧重新绑定(注释里「re-bound each frame dropping any old references」),所以只要有任何 SceneManager 或材质还攥着纹理,计数就会高于 4,纹理得以保留;计数回落才销毁。这套「池 + 引用计数 + 延迟清理」让多 SceneManager 共享纹理时的创建/销毁责任清晰。

投射端:caster 渲染与材质推导

纹理建好后,每帧把阴影投射体(caster)画进纹理。renderTextureShadowCasterQueueGroupObjects 先覆盖环境光:叠加模式用纯黑(简单黑白掩码),调制模式用阴影色(caster 本身就带着阴影颜色):

// OgreMain/src/OgreTextureShadowRenderer.cpp:renderTextureShadowCasterQueueGroupObjects(v14.6.3 源码摘录,已删减)
    // Override auto param ambient to force vertex programs and fixed function to
    ColourValue currAmbient = mSceneManager->getAmbientLight();
    if (mSceneManager->isShadowTechniqueAdditive())
    {
        // Use simple black / white mask if additive
        mSceneManager->setAmbientLight(ColourValue::Black);
    }
    else
    {
        // Use shadow colour as caster colour if modulative
        mSceneManager->setAmbientLight(mSceneManager->getShadowColour());
    }

caster 用什么材质渲染?deriveShadowCasterPass 给出三级优先级:对象的材质若带了 shadowCasterMaterial 用它的最佳技术首 pass;否则用 setShadowTextureCasterMaterial 注册的自定义 caster pass;再否则用内置的 Ogre/TextureShadowCaster 纯黑 pass:

// OgreMain/src/OgreTextureShadowRenderer.cpp:deriveShadowCasterPass(v14.6.3 源码摘录,已删减)
const Pass* SceneManager::TextureShadowRenderer::deriveShadowCasterPass(const Pass* pass)
{
    Pass* retPass;
    if (pass->getParent()->getShadowCasterMaterial())
    {
        auto bestTech = pass->getParent()->getShadowCasterMaterial()->getBestTechnique();
        if (bestTech && bestTech->getNumPasses() > 0) {
            return bestTech->getPass(0);
        }
    }
    retPass = mShadowTextureCustomCasterPass ?
        mShadowTextureCustomCasterPass : mShadowCasterPlainBlackPass;

自定义 caster 材质由 setShadowTextureCasterMaterial 登记:材质无效(未加载成功、无最佳技术、无 pass)时把自定义 pass 清零回退默认,否则取 getTechnique(0)->getPass(0):

// OgreMain/src/OgreTextureShadowRenderer.cpp:setShadowTextureCasterMaterial(v14.6.3 源码摘录,已删减)
void SceneManager::TextureShadowRenderer::setShadowTextureCasterMaterial(const MaterialPtr& mat)
{
    if(!mat) {
        mShadowTextureCustomCasterPass = 0;
        return;
    }

    mat->load();
    if (!mat->getBestTechnique())
    {
        // unsupported
        mShadowTextureCustomCasterPass = 0;
    }
    else
    {
        OgreAssert(!mat->getTechnique(0)->getPasses().empty(), "technique 0 has no passes");
        mShadowTextureCustomCasterPass = mat->getTechnique(0)->getPass(0);
    }
}

setShadowTechnique 切换时还会初始化默认 caster/receiver 材质(Ogre/TextureShadowCaster 与 Ogre/TextureShadowReceiver),并保证切到非纹理阴影时销毁纹理优化资源。这一整套保证了「纹理资源生命周期」与「材质推导」两个维度都可配置、可替换。

纹理阴影的投射与采样

flowchart LR
  L["可投影光源"] --> S["ShadowCameraSetup"]
  S --> V["阴影视口"]
  P["兼容配置的纹理池"] --> V
  O["投射物体及 caster Pass"] --> V
  V --> T["阴影纹理"]
  T --> R["接收物体的阴影采样"]

投射视口与接收视口使用不同数据

光源和 ShadowCameraSetup 先决定投射视图。投射路径把 caster 的深度或其他阴影信息写入纹理。接收路径在相机视图中读取该纹理与对应的投影变换。纹理池影响的是分配和复用。

有阴影时分别检查 caster 入队、纹理产生、receiver 读取。只禁用投射对象时观察其投影是否消失,保留正常场景光照作为对照。

投射与接收的两次场景访问

sequenceDiagram
  participant L as 光源和 ShadowCameraSetup
  participant S as SceneManager
  participant T as 阴影纹理目标
  participant R as 主相机接收路径
  L-->>S: 提供阴影视角与投影
  S->>S: 过滤 caster 并选择投射 Pass
  S->>T: 写入阴影纹理
  S->>R: 恢复主相机与可见对象
  R->>T: 用接收材质读取投射结果
  R->>R: 组合阴影和场景着色

源码定位

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

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

下面复现阴影纹理池与 caster 投射:ShadowTextureConfig 的 operator== 宽松口径与池内全量匹配的严格口径、按配置复用/新建、getNoShadowTexture 的 1×1 空纹理与 mCount 共用、clearUnused 的引用计数阈值、deriveShadowCasterPass 三级优先级、caster 渲染的环境光覆盖。它与 src/05-3-shadow-texture-caster.cpp 逐字节一致:

// file: src/05-3-shadow-texture-caster.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/05-3-shadow-texture-caster.cpp -o bin/05-3-shadow-texture-caster && ./bin/05-3-shadow-texture-caster
//
// 复现 OgreShadowTextureManager.cpp 的阴影纹理池与
// OgreTextureShadowRenderer.cpp 的 caster 投射:
//   ShadowTextureConfig 的 operator==(源码只比 width/height/format);
//   getShadowTextures:按 width/height/depth/type/format/fsaa 全量匹配,
//     已占用的纹理跳过,不匹配则新建(名字 Ogre/ShadowTexture%zu,mCount 共用);
//   getNoShadowTexture:按 format 匹配 1×1 空纹理,否则新建;
//   clearUnused:use_count == RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1 才移除;
//   deriveShadowCasterPass:材质自带 shadowCasterMaterial > 自定义 caster pass
//     > 默认纯黑 pass;
//   caster 渲染前环境光覆盖:additive → 黑,modulative → 阴影色。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <algorithm>
#include <cstdint>
#include <memory>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 OgreSceneManager.h 的 PixelFormat 常用值
enum PixelFormat : int {
  PF_BYTE_RGBA = 0,
  PF_DEPTH16 = 100,
};

// 对应 OgreSceneManager.h 的 TextureType
enum TextureType : int {
  TEX_TYPE_2D = 0,
};

// 对应 OgreResourceGroupManager.h:资源系统内部固定引用数
constexpr long RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS = 3;

// 对应 OgreSceneManager.h:struct ShadowTextureConfig
struct ShadowTextureConfig {
  uint32_t width = 512;
  uint32_t height = 512;
  uint32_t depth = 1;
  int format = PF_BYTE_RGBA;
  uint16_t depthBufferPoolId = 1;
  uint16_t extraFlags = 0;
  uint8_t fsaa = 0;
  int type = TEX_TYPE_2D;
};

// 对应 OgreShadowTextureManager.cpp 的 operator==:源码只比 width/height/format
inline bool operator==(const ShadowTextureConfig& lhs, const ShadowTextureConfig& rhs) {
  if (lhs.width != rhs.width || lhs.height != rhs.height || lhs.format != rhs.format) {
    return false;
  }
  return true;
}
inline bool operator!=(const ShadowTextureConfig& lhs, const ShadowTextureConfig& rhs) {
  return !(lhs == rhs);
}

// getShadowTextures 内部的全量匹配(width/height/depth/type/format/fsaa)
inline bool fullMatch(const ShadowTextureConfig& c, const ShadowTextureConfig& t) {
  return c.width == t.width && c.height == t.height && c.depth == t.depth &&
         c.type == t.type && c.format == t.format && c.fsaa == t.fsaa;
}

// 对应 ShadowTextureManager 管理的纹理
struct Texture {
  std::string name;
  uint32_t width = 0;
  uint32_t height = 0;
  uint32_t depth = 0;
  int format = PF_BYTE_RGBA;
  uint8_t fsaa = 0;
  int type = TEX_TYPE_2D;
  bool removed = false;
};
using TexturePtr = std::shared_ptr<Texture>;

// 对应 OgreShadowTextureManager.h 的 ShadowTextureManager(池)
class ShadowTextureManager {
 public:
  using ConfigList = std::vector<ShadowTextureConfig>;
  using TextureList = std::vector<TexturePtr>;

  // 对应 getShadowTextures:先匹配,匹配不到再新建
  void getShadowTextures(ConfigList& configList, TextureList& listToPopulate) {
    listToPopulate.clear();
    std::vector<Texture*> usedTextures;
    for (auto& config : configList) {
      bool found = false;
      for (auto& tex : mTextureList) {
        // 本帧已用过的纹理跳过
        if (std::find(usedTextures.begin(), usedTextures.end(), tex.get()) != usedTextures.end())
          continue;
        if (config.width == tex->width && config.height == tex->height &&
            config.depth == tex->depth && config.type == tex->type &&
            config.format == tex->format && config.fsaa == tex->fsaa) {
          listToPopulate.push_back(tex);
          usedTextures.push_back(tex.get());
          found = true;
          break;
        }
      }
      if (!found) {
        std::string targName = "Ogre/ShadowTexture" + std::to_string(mCount++);
        auto shadowTex = std::make_shared<Texture>();
        shadowTex->name = targName;
        shadowTex->width = config.width;
        shadowTex->height = config.height;
        shadowTex->depth = config.depth;
        shadowTex->format = config.format;
        shadowTex->type = config.type;
        shadowTex->fsaa = config.fsaa;
        listToPopulate.push_back(shadowTex);
        usedTextures.push_back(shadowTex.get());
        mTextureList.push_back(shadowTex);
        addSystemRefs(shadowTex);
      }
    }
  }

  // 对应 getNoShadowTexture:按 format 匹配,否则新建 1×1 纹理
  TexturePtr getNoShadowTexture(int format) {
    for (auto& tex : mNullTextureList) {
      if (format == tex->format) {
        return tex;
      }
    }
    std::string targName = "Ogre/ShadowTextureNull" + std::to_string(mCount++);
    auto shadowTex = std::make_shared<Texture>();
    shadowTex->name = targName;
    shadowTex->width = 1;
    shadowTex->height = 1;
    shadowTex->depth = 0;
    shadowTex->format = format;
    mNullTextureList.push_back(shadowTex);
    addSystemRefs(shadowTex);
    return shadowTex;
  }

  // 对应 clearUnused:引用数回到「池 1 + 资源系统 3」才移除
  void clearUnused() {
    for (auto i = mTextureList.begin(); i != mTextureList.end();) {
      if ((*i).use_count() == RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1) {
        (*i)->removed = true;
        i = mTextureList.erase(i);
      } else {
        ++i;
      }
    }
    for (auto i = mNullTextureList.begin(); i != mNullTextureList.end();) {
      if ((*i).use_count() == RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1) {
        (*i)->removed = true;
        i = mNullTextureList.erase(i);
      } else {
        ++i;
      }
    }
  }

  size_t textureCount() const { return mTextureList.size(); }
  size_t nullCount() const { return mNullTextureList.size(); }
  size_t count() const { return mCount; }

 private:
  // 模拟 ResourceGroupManager 对每张纹理持有的固定引用数
  void addSystemRefs(const TexturePtr& tex) {
    for (long k = 0; k < RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS; ++k)
      mSystemRefs.push_back(tex);
  }

  TextureList mTextureList;
  TextureList mNullTextureList;
  TextureList mSystemRefs;
  size_t mCount = 0;
};

// ---- 以下复现 OgreTextureShadowRenderer.cpp 的 caster 投射 ----

struct Pass {
  const char* name = "";
  bool valid = true;
};

// 材质(极简):pass 是 technique0 的 pass0,shadowCasterPass 是材质指定的 caster pass
struct Material {
  Pass* pass = nullptr;
  const Pass* shadowCasterPass = nullptr;
};

// 对应 SceneManager::TextureShadowRenderer 的 caster 相关子集
class TextureShadowRenderer {
 public:
  const Pass mPlainBlackPass{"Ogre/TextureShadowCaster", true};
  const Pass* mCustomCasterPass = nullptr;

  // 对应 setShadowTextureCasterMaterial:无效材质(无最佳技术/无 pass)清空
  void setShadowTextureCasterMaterial(const Material* mat) {
    if (!mat || !mat->pass) {
      mCustomCasterPass = nullptr;
      return;
    }
    mCustomCasterPass = mat->pass;
  }

  // 对应 deriveShadowCasterPass:材质自带 > 自定义 > 默认纯黑
  const Pass* deriveShadowCasterPass(const Material& objectMat) const {
    if (objectMat.shadowCasterPass) return objectMat.shadowCasterPass;
    return mCustomCasterPass ? mCustomCasterPass : &mPlainBlackPass;
  }
};

// 对应 caster 渲染前的环境光覆盖
struct Colour {
  float r, g, b;
};
inline bool isBlack(const Colour& c) { return c.r == 0.0f && c.g == 0.0f && c.b == 0.0f; }
inline Colour ambientForCaster(bool additive, const Colour& shadowColour) {
  return additive ? Colour{0.0f, 0.0f, 0.0f} : shadowColour;
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 默认配置字段
  ShadowTextureConfig a;
  CHECK_EQ(a.width, 512u);
  CHECK_EQ(a.height, 512u);
  CHECK_EQ(a.depth, 1u);
  CHECK_EQ(a.format, PF_BYTE_RGBA);
  CHECK_EQ(a.type, TEX_TYPE_2D);
  CHECK_EQ(a.fsaa, 0u);

  // operator==:只比 width/height/format
  ShadowTextureConfig b;
  CHECK(a == b);
  b.format = PF_DEPTH16;
  CHECK(a != b);

  // fsaa 不同但 operator== 仍认为相等;池内全量匹配认为不同
  ShadowTextureConfig x, y;
  y.fsaa = 1;
  CHECK(x == y);
  CHECK(!fullMatch(x, y));

  // 空配置 → 空列表
  ShadowTextureManager mgr0;
  ShadowTextureManager::ConfigList empty;
  ShadowTextureManager::TextureList out0;
  mgr0.getShadowTextures(empty, out0);
  CHECK_EQ(out0.size(), size_t{0});
  CHECK_EQ(mgr0.textureCount(), size_t{0});

  // 第一帧:两个相同配置 → 新建两张
  {
    ShadowTextureManager mgr;
    ShadowTextureManager::ConfigList cfgs;
    cfgs.push_back(ShadowTextureConfig{});
    cfgs.push_back(ShadowTextureConfig{});
    ShadowTextureManager::TextureList frame1;
    mgr.getShadowTextures(cfgs, frame1);
    CHECK_EQ(frame1.size(), size_t{2});
    CHECK_EQ(mgr.textureCount(), size_t{2});
    CHECK_EQ(frame1[0]->name, std::string("Ogre/ShadowTexture0"));
    CHECK_EQ(frame1[1]->name, std::string("Ogre/ShadowTexture1"));
    CHECK_EQ(frame1[0]->width, 512u);
    CHECK_EQ(frame1[0]->height, 512u);
    CHECK_EQ(frame1[0]->depth, 1u);
    CHECK_EQ(frame1[0]->format, PF_BYTE_RGBA);

    // 第二帧同样配置 → 复用池中纹理,不新建
    ShadowTextureManager::TextureList frame2;
    mgr.getShadowTextures(cfgs, frame2);
    CHECK_EQ(frame2.size(), size_t{2});
    CHECK_EQ(mgr.textureCount(), size_t{2});
    CHECK(frame2[0] == frame1[0]);
    CHECK(frame2[1] == frame1[1]);
  }

  // 已占用纹理跳过:池 2 张,请求 3 个相同配置 → 第三张新建
  {
    ShadowTextureManager mgr;
    ShadowTextureManager::ConfigList cfgs;
    cfgs.push_back(ShadowTextureConfig{});
    cfgs.push_back(ShadowTextureConfig{});
    ShadowTextureManager::TextureList f1;
    mgr.getShadowTextures(cfgs, f1);

    ShadowTextureManager::ConfigList three;
    three.push_back(ShadowTextureConfig{});
    three.push_back(ShadowTextureConfig{});
    three.push_back(ShadowTextureConfig{});
    ShadowTextureManager::TextureList f2;
    mgr.getShadowTextures(three, f2);
    CHECK_EQ(f2.size(), size_t{3});
    CHECK_EQ(mgr.textureCount(), size_t{3});
    CHECK(f2[0] == f1[0]);
    CHECK(f2[1] == f1[1]);
    CHECK(f2[2] != f1[0] && f2[2] != f1[1]);
    CHECK_EQ(f2[2]->name, std::string("Ogre/ShadowTexture2"));
  }

  // getNoShadowTexture:1×1 空纹理,按 format 复用,mCount 与阴影纹理共用
  {
    ShadowTextureManager mgr;
    TexturePtr n = mgr.getNoShadowTexture(PF_BYTE_RGBA);
    CHECK_EQ(mgr.nullCount(), size_t{1});
    CHECK_EQ(n->width, 1u);
    CHECK_EQ(n->height, 1u);
    CHECK_EQ(n->depth, 0u);
    CHECK_EQ(n->format, PF_BYTE_RGBA);
    CHECK_EQ(n->name, std::string("Ogre/ShadowTextureNull0"));

    TexturePtr n2 = mgr.getNoShadowTexture(PF_BYTE_RGBA);
    CHECK_EQ(mgr.nullCount(), size_t{1});
    CHECK(n2 == n);

    TexturePtr n3 = mgr.getNoShadowTexture(PF_DEPTH16);
    CHECK_EQ(mgr.nullCount(), size_t{2});
    CHECK_EQ(n3->name, std::string("Ogre/ShadowTextureNull1"));
  }
  {
    ShadowTextureManager mgr;
    ShadowTextureManager::ConfigList cfg;
    cfg.push_back(ShadowTextureConfig{});
    ShadowTextureManager::TextureList out;
    mgr.getShadowTextures(cfg, out);
    CHECK_EQ(mgr.count(), size_t{1});
    TexturePtr n = mgr.getNoShadowTexture(PF_BYTE_RGBA);
    CHECK_EQ(n->name, std::string("Ogre/ShadowTextureNull1"));  // mCount 共用
  }

  // clearUnused:有调用方引用不清,释放后清
  {
    ShadowTextureManager mgr;
    ShadowTextureManager::ConfigList cfg;
    cfg.push_back(ShadowTextureConfig{});
    ShadowTextureManager::TextureList held;
    mgr.getShadowTextures(cfg, held);
    CHECK_EQ(held.size(), size_t{1});
    CHECK_EQ(mgr.textureCount(), size_t{1});
    // 池 1 + 系统 3 + 调用方 1 = 5
    CHECK_EQ(held[0].use_count(), long{5});
    mgr.clearUnused();
    CHECK_EQ(mgr.textureCount(), size_t{1});  // 仍被调用方引用

    TexturePtr keep = held[0];
    held.clear();
    // 池 1 + 系统 3 + keep 1 = 5
    CHECK_EQ(keep.use_count(), long{5});
    mgr.clearUnused();
    CHECK_EQ(mgr.textureCount(), size_t{1});  // keep 仍引用

    keep.reset();
    // 池 1 + 系统 3 = 4,达到 RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1
    mgr.clearUnused();
    CHECK_EQ(mgr.textureCount(), size_t{0});
  }

  // deriveShadowCasterPass:材质自带 > 自定义 > 默认纯黑
  TextureShadowRenderer renderer;
  Pass customPass{"custom", true};
  Pass materialCasterPass{"material-caster", true};
  Material plainMat;   // 无自带 caster pass、无 pass
  Material nullMat;    // 无效材质:pass 为空(无最佳技术)
  Material withCaster; // 材质自带 shadowCasterMaterial
  withCaster.shadowCasterPass = &materialCasterPass;
  Material customMat;  // 用于 setShadowTextureCasterMaterial 的材质
  customMat.pass = &customPass;

  CHECK(renderer.deriveShadowCasterPass(plainMat) == &renderer.mPlainBlackPass);

  renderer.setShadowTextureCasterMaterial(&customMat);
  CHECK(renderer.deriveShadowCasterPass(plainMat) == &customPass);
  // 材质自带 caster pass 优先级最高
  CHECK(renderer.deriveShadowCasterPass(withCaster) == &materialCasterPass);

  // 无效材质(无 pass)清空自定义
  renderer.setShadowTextureCasterMaterial(&nullMat);
  CHECK(renderer.deriveShadowCasterPass(plainMat) == &renderer.mPlainBlackPass);
  renderer.setShadowTextureCasterMaterial(nullptr);
  CHECK(renderer.deriveShadowCasterPass(plainMat) == &renderer.mPlainBlackPass);

  // 环境光覆盖:additive → 黑,modulative → 阴影色
  CHECK(isBlack(ambientForCaster(true, Colour{0.25f, 0.25f, 0.25f})));
  CHECK(ambientForCaster(false, Colour{0.25f, 0.25f, 0.25f}).r == 0.25f);

  return lab::report("05-3 纹理阴影与投射:纹理池与 caster");
}

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

小结

  • ShadowTextureConfig 默认 512×512×1、PF_BYTE_RGBA、2D;池内复用按六字段全量匹配,比配置级 operator==(只比宽高格式)更严。
  • getShadowTextures 命中即复用、不中即新建,名字 Ogre/ShadowTexture%zu 由共享的 mCount 递增;新建后回写实际格式。
  • getNoShadowTexture 提供 1×1 非渲染目标空纹理,按格式复用,深度格式直接返回。
  • clearUnused 用 use_count() == RESOURCE_SYSTEM_NUM_REFERENCE_COUNTS + 1(=4)判定无引用才销毁,是每帧渲染后的延迟清理。
  • caster 渲染时 additive 环境光置黑、modulative 置阴影色;deriveShadowCasterPass 优先级为材质自带 shadowCasterMaterial > 自定义 caster pass > 默认纯黑。

阅读导航:上一节:5.2 阴影相机设置 · 下一节:6.1 粒子系统 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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