《OGRE 3D 渲染引擎原理与架构》6.3 着色器变体

着色器变体由 preprocessor defines、entry point 与程序类型三者组合决定:parseDefines 解析宏表、appendBuiltinDefines 追加 OGRE_GLSL 等内置宏,脚本翻译器把 .program 里的 language 交给管理器,GLSLangProgram 以变体键缓存 SPIR-V 汇编。lab 复现变体键与编译缓存语义。

6.3 着色器变体

同一个材质往往要应对多种情况:有骨骼动画时 skinning 分支、光源多了循环展开、雾效开或关。引擎不会为每种情况单独存一份完整着色器,而是用预处理器定义 + 入口点 + 程序类型组合出一个「变体键」,按需编译并缓存。这一节看变体的键是怎么构成的、内置宏从哪来、脚本怎么驱动创建、插件怎么缓存编译产物。

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

6.1 讲了高级程序的壳与工厂分发,6.2 讲了参数绑定;这一节把两者之间的「编译」环节补上:同一次 language glsl 创建,具体产出哪个二进制由 defines/entry point 决定。RTSS(运行时着色器系统)的生成式变体属于内容侧,这里不展开。

变体的维度:类型、入口点、预处理器定义

程序类型本身是变体的一部分。GpuProgramType 是 uint8 枚举,从顶点一路列到 compute:

// OgreMain/include/OgreGpuProgram.h:GpuProgramType(v14.6.3 源码摘录,已删减)
    enum GpuProgramType : uint8
    {
        GPT_VERTEX_PROGRAM = 0,
        GPT_FRAGMENT_PROGRAM,
        GPT_GEOMETRY_PROGRAM,
        GPT_DOMAIN_PROGRAM,
        GPT_HULL_PROGRAM,
        GPT_MESH_PROGRAM, // aliases with vertex
        GPT_COMPUTE_PROGRAM, // aliases with fragment
        GPT_TASK_PROGRAM
    };

高级程序的 HighLevelGpuProgram 再补两维:mPreprocessorDefines 与 mEntryPoint。用户给的 defines 是裸字符串,编译前先由 parseDefines 原地拆成「宏名 → 值」对——分隔符是 ;、,、=,没有值的宏一律记 "1"(相当于开启该开关):

// OgreMain/src/OgreHighLevelGpuProgram.cpp:HighLevelGpuProgram::parseDefines(v14.6.3 源码摘录,已删减)
    std::vector<std::pair<const char*, const char*>> HighLevelGpuProgram::parseDefines(String& defines)
    {
        std::vector<std::pair<const char*, const char*>> ret;
        if (defines.empty())
            return ret;

        String::size_type pos = 0;
        while (pos != String::npos)
        {
            // Find delims
            String::size_type endPos = defines.find_first_of(";,=", pos);
            if (endPos != String::npos)
            {
                String::size_type macro_name_start = pos;
                pos = endPos;
...
                if (defines[pos] == '=')
                {
                    // Setup null character for macro name
                    defines[pos] = '\0';
...
                    ret.push_back({&defines[macro_name_start], &defines[macro_val_start]});
                }
                else
                {
                    // Setup null character for macro name
                    defines[pos] = '\0';
                    // No definition part, define as "1"
                    ++pos;

                    if(defines[macro_name_start] != '\0') // e.g ",DEFINE" or "DEFINE,"
                        ret.push_back({&defines[macro_name_start], "1"});
                }
            }
...
        }

        return ret;
    }

注意实现细节:它在原字符串上打 '\0'(defines[pos] = '\0'),返回的是一组 const char* 指针指向被改写的缓冲区——省了一次拷贝,代价是 defines 字符串被就地破坏。

内置宏:appendBuiltinDefines

光有用户 defines 不够,OGRE 还要告诉着色器「现在是 GLSL 450」「这是顶点着色器」「深度缓冲是否反转」。appendBuiltinDefines 在用户 defines 之后追加这些引擎侧宏:

// OgreMain/src/OgreHighLevelGpuProgram.cpp:HighLevelGpuProgram::appendBuiltinDefines(v14.6.3 源码摘录,已删减)
    String HighLevelGpuProgram::appendBuiltinDefines(String defines)
    {
        if(!defines.empty()) defines += ",";

        auto renderSystem = Root::getSingleton().getRenderSystem();

        // OGRE_HLSL, OGRE_GLSL etc.
        String tmp = getLanguage();
        StringUtil::toUpperCase(tmp);
        auto ver = renderSystem ? renderSystem->getNativeShadingLanguageVersion() : 0;
        defines += StringUtil::format("OGRE_%s=%d", tmp.c_str(), ver);

        // supporting rendersystems will handle this by other means
        defines += ",OGRE_NATIVE_GLSL_VERSION_DIRECTIVE=";

        // OGRE_VERTEX_SHADER, OGRE_FRAGMENT_SHADER
        tmp = GpuProgram::getProgramTypeName(getType());
        StringUtil::toUpperCase(tmp);
        defines += ",OGRE_"+tmp+"_SHADER";

        if(renderSystem && renderSystem->isReverseDepthBufferEnabled())
            defines += ",OGRE_REVERSED_Z";

        return defines;
    }

追加的宏包括:OGRE_GLSL=450(语言 + 原生版本)、OGRE_VERTEX_SHADER/OGRE_FRAGMENT_SHADER(由 getProgramTypeName 大写化而来)、反向深度时的 OGRE_REVERSED_Z。最终这份合并后的 defines 连同入口点一起传给语言插件编译。

脚本侧:.program 里的语言分发

材质脚本里 vertex_program foo glsl { source x.glsl ... } 由 GpuProgramTranslator 翻译。它先收集 source、profiles、target、delegate 与自定义参数,再把语言名(glsl)交给管理器创建:

// OgreMain/src/OgreScriptTranslator.cpp:GpuProgramTranslator::translateGpuProgram(v14.6.3 源码摘录,已删减)
    void GpuProgramTranslator::translateGpuProgram(ScriptCompiler *compiler, ObjectAbstractNode *obj, String language)
    {
        String syntax;
        std::vector<String> delegates;
        std::vector<std::pair<PropertyAbstractNode*, String> > customParameters;
        String source, profiles, target;
        AbstractNodePtr params;
        for(auto & i : obj->children)
        {
...
                    if(prop->id == ID_SOURCE)
                    {
                        if(!getValue(prop, compiler, source))
                            return;
                    }
                    else if(prop->name == "delegate")
                    {
...
                        delegates.push_back(name);
                    }
                    else
                    {
...
                        if(prop->name == "profiles")
                            profiles = value;
                        else if(prop->name == "target")
                            target = value;
                        else if(prop->id == ID_SYNTAX && language == "asm")
                            syntax = value;
                        else
                            customParameters.push_back(std::make_pair(prop, value));
                    }
...
        }

        // Allocate the program
        GpuProgramType gpt = getProgramType(obj->id);
        GpuProgram *prog = 0;

        if(language == "asm")
            language = syntax;
        CreateGpuProgramScriptCompilerEvent evt(obj->file, obj->name, compiler->getResourceGroup(), source,
                                                language, gpt);
        bool processed = compiler->_fireEvent(&evt, &prog);

        if(!processed)
        {
            prog = GpuProgramManager::getSingleton().create(obj->name, compiler->getResourceGroup(), gpt, language).get();
...
            if(prog && !source.empty()) // prog=0 if duplicate definition resolved by "use previous"
                prog->setSourceFile(source);
        }
...
    }

customParameters 里的 preprocessor_defines、entry_point 稍后通过 setParameter 落到程序上——这正是变体键的另外两维。

编译与缓存:GLSLangProgram

语言插件拿到 defines 后做真正的编译。GLSLang 插件把 GLSL/HLSL 编译成 SPIR-V 汇编,GLSLangProgram 是它的 HighLevelGpuProgram 子类:

// PlugIns/GLSLang/include/OgreGLSLangProgramManager.h:GLSLangProgram(v14.6.3 源码摘录,已删减)
class GLSLangProgram : public HighLevelGpuProgram
{
    void createLowLevelImpl() override;
    void unloadHighLevelImpl() override;
    void loadFromSource() override;
    void buildConstantDefinitions() override;
    void prepareImpl() override;

    std::vector<uint32> mAssembly;
public:
    GLSLangProgram(ResourceManager* creator, const String& name, ResourceHandle handle, const String& group,
                   bool isManual, ManualResourceLoader* loader);
    ~GLSLangProgram();
    const String& getLanguage(void) const override;

    bool isSupported() const override;
};

loadFromSource() 用「合并后的 defines + 入口点 + 类型」构造 glslang 编译请求,把产物写进 mAssembly(std::vector<uint32>,SPIR-V 是 32 位字数组);createLowLevelImpl() 再用这段汇编建出低层 GpuProgram。不同的 defines/入口点组合对应不同的 mAssembly——这就是「变体」在数据层面的样子。微代码缓存(GpuProgramManager 的 mMicrocodeCache,按 _getHash 键控)进一步让相同变体跨运行免重编译。

变体输入和缓存失效条件

语言、源码、入口、宏定义和目标配置会改变编译输入。缓存是具体程序或后端的机制,不能用一个通用键解释所有路径。RTSS 还有 scheme 与 SubRenderState 组合。

保持材质其他状态不变,仅修改一个宏或源 Pass,检查新变体选择与实际重新生成。卷三 14.3 维护 RTSS 的失效条件。

源码定位

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

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

下面复现变体的构造与缓存:parseDefines 拆宏表、appendBuiltinDefines 追加内置宏、GLSLangProgram 以 defines+entryPoint+type 为键编译并缓存 SPIR-V 汇编。它与 src/ogre-ext-06-3-shader-variants.cpp 逐字节一致:

// file: src/ogre-ext-06-3-shader-variants.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-06-3-shader-variants.cpp -o bin/ogre-ext-06-3-shader-variants && ./bin/ogre-ext-06-3-shader-variants
//
// 复现着色器变体:preprocessor defines 与 entry point 组合决定编译产物
// (对应 OgreHighLevelGpuProgram.cpp 148-233、OgreScriptTranslator.cpp 3147-、OgreGLSLangProgramManager.h 29-45):
//   parseDefines 把 "A=1,B,C=2" 拆成宏名/值对(无值记 "1");
//   appendBuiltinDefines 在用户 defines 后追加 OGRE_GLSL/OGRE_VERTEX_SHADER 等内置宏;
//   GLSLangProgram 以 defines+entryPoint+type 为变体键,loadFromSource 编译出 SPIR-V 汇编并按键缓存。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cctype>
#include <cstdint>
#include <map>
#include <string>
#include <vector>

namespace ogre_repro {

// parseDefines(OgreHighLevelGpuProgram.cpp 148-207):"A=1,B,C=2" -> {A,1},{B,1},{C,2}
std::vector<std::pair<std::string, std::string>> parseDefines(const std::string& defines) {
  std::vector<std::pair<std::string, std::string>> ret;
  if (defines.empty()) return ret;
  size_t pos = 0;
  while (pos != std::string::npos) {
    size_t endPos = defines.find_first_of(";,=", pos);
    if (endPos != std::string::npos) {
      std::string name = defines.substr(pos, endPos - pos);
      pos = endPos;
      if (defines[pos] == '=') {
        ++pos;
        size_t valEnd = defines.find_first_of(";,", pos);
        std::string val = (valEnd == std::string::npos) ? defines.substr(pos)
                                                        : defines.substr(pos, valEnd - pos);
        ret.emplace_back(name, val);
        pos = (valEnd == std::string::npos) ? valEnd : valEnd + 1;
      } else {
        ret.emplace_back(name, "1");  // 无值定义记 "1"
        ++pos;
      }
    } else {
      if (pos < defines.size()) ret.emplace_back(defines.substr(pos), "1");
      pos = endPos;
    }
  }
  return ret;
}

// appendBuiltinDefines(OgreHighLevelGpuProgram.cpp 209-233):追加 OGRE_<LANG> 等内置宏
std::string appendBuiltinDefines(const std::string& defines, const std::string& language,
                                 uint32_t version, bool isVertex) {
  std::string d = defines;
  if (!d.empty()) d += ",";
  std::string upper = language;
  for (auto& c : upper) c = static_cast<char>(toupper(static_cast<unsigned char>(c)));
  d += "OGRE_" + upper + "=" + std::to_string(version);
  d += ",OGRE_" + std::string(isVertex ? "VERTEX" : "FRAGMENT") + "_SHADER";
  return d;
}

// 对应 GLSLangProgram(OgreGLSLangProgramManager.h 29-45):以变体键缓存 SPIR-V 汇编
class GlslangProgram {
 public:
  struct VariantKey {
    std::string defines;
    std::string entryPoint;
    uint8_t type;  // 0=vertex, 1=fragment
    bool operator<(const VariantKey& o) const {
      if (defines != o.defines) return defines < o.defines;
      if (entryPoint != o.entryPoint) return entryPoint < o.entryPoint;
      return type < o.type;
    }
  };

  void setPreprocessorDefines(const std::string& d) { mDefines = d; }
  void setEntryPoint(const std::string& e) { mEntryPoint = e; }
  void setType(uint8_t t) { mType = t; }
  const std::vector<uint32_t>& getAssembly() const { return mAssembly; }
  bool isLoaded() const { return mLoaded; }

  // loadFromSource:编译(模拟)出 SPIR-V 汇编并按变体键缓存
  void loadFromSource() {
    VariantKey key{mDefines, mEntryPoint, mType};
    auto it = mCache.find(key);
    if (it != mCache.end()) {
      mAssembly = it->second;
    } else {
      mAssembly = compile(key);
      mCache[key] = mAssembly;
    }
    mLoaded = true;
  }

  static size_t cacheSize() { return mCache.size(); }

 private:
  static std::vector<uint32_t> compile(const VariantKey& key) {
    // 模拟编译:产物长度/内容与定义数、入口点、类型都相关
    size_t numDefs = parseDefines(key.defines).size();
    uint32_t seed = 0;
    for (char ch : key.entryPoint) seed = seed * 31 + static_cast<uint32_t>(ch);
    uint32_t extra = key.type == 0 ? 2u : 3u;  // 顶点/片元入口不同
    return std::vector<uint32_t>(4 + numDefs * 2 + (key.entryPoint.size() % 4) + extra,
                                 seed + key.type);
  }

  std::string mDefines;
  std::string mEntryPoint = "main";
  uint8_t mType = 0;
  std::vector<uint32_t> mAssembly;  // 对应 std::vector<uint32> mAssembly
  bool mLoaded = false;
  static std::map<VariantKey, std::vector<uint32_t>> mCache;
};

std::map<GlslangProgram::VariantKey, std::vector<uint32_t>> GlslangProgram::mCache;

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // parseDefines:带值、无值、空串三种情况
  auto defs = parseDefines("MAX_LIGHTS=4,SKINNING,FOG=1");
  CHECK(defs.size() == 3);
  CHECK(defs[0].first == "MAX_LIGHTS");
  CHECK(defs[0].second == "4");
  CHECK(defs[1].first == "SKINNING");
  CHECK(defs[1].second == "1");  // 无值定义记 "1"
  CHECK(defs[2].first == "FOG");
  CHECK(defs[2].second == "1");
  CHECK(parseDefines("").empty());

  // appendBuiltinDefines:在用户 defines 后追加内置宏
  std::string builtin = appendBuiltinDefines("MAX_LIGHTS=4", "glsl", 450, true);
  CHECK(builtin.find("MAX_LIGHTS=4") == 0);
  CHECK(builtin.find("OGRE_GLSL=450") != std::string::npos);
  CHECK(builtin.find("OGRE_VERTEX_SHADER") != std::string::npos);
  CHECK(builtin.find("OGRE_FRAGMENT_SHADER") == std::string::npos);

  // 同一变体键二次 load 命中缓存,汇编逐字节一致
  GlslangProgram a, b;
  a.setPreprocessorDefines("MAX_LIGHTS=4");
  a.setEntryPoint("main_vs");
  a.loadFromSource();
  b.setPreprocessorDefines("MAX_LIGHTS=4");
  b.setEntryPoint("main_vs");
  b.loadFromSource();
  CHECK(a.isLoaded());
  CHECK(b.isLoaded());
  CHECK(a.getAssembly() == b.getAssembly());

  // 不同的 defines 产生不同变体
  GlslangProgram c;
  c.setPreprocessorDefines("MAX_LIGHTS=8,SKINNING");
  c.setEntryPoint("main_vs");
  c.loadFromSource();
  CHECK(c.getAssembly() != a.getAssembly());

  // 不同 entry point 也产生不同变体
  GlslangProgram d;
  d.setPreprocessorDefines("MAX_LIGHTS=4");
  d.setEntryPoint("main_fs");
  d.loadFromSource();
  CHECK(d.getAssembly() != a.getAssembly());

  // 变体键把 type 也算进去:vertex 与 fragment 同名同 defines 不同产物
  GlslangProgram e, f;
  e.setPreprocessorDefines("MAX_LIGHTS=4");
  e.setEntryPoint("main");
  e.setType(1);
  e.loadFromSource();
  f.setPreprocessorDefines("MAX_LIGHTS=4");
  f.setEntryPoint("main");
  f.setType(0);
  f.loadFromSource();
  CHECK(e.getAssembly() != f.getAssembly());

  // 缓存只含不重复的键:MAX_LIGHTS=4/main_vs、MAX_LIGHTS=8,SKINNING/main_vs、
  // MAX_LIGHTS=4/main_fs、MAX_LIGHTS=4/main(type1)、MAX_LIGHTS=4/main(type0) 共 5 个
  CHECK(GlslangProgram::cacheSize() == 5);

  return lab::report("06-3 着色器变体");
}

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

小结

  • 变体键 = 程序类型(GpuProgramType)+ 入口点 + 预处理器 defines。
  • parseDefines 原地把 defines 拆成宏名/值对,无值宏记 "1"。
  • appendBuiltinDefines 追加 OGRE_GLSL=<ver>、OGRE_VERTEX_SHADER、OGRE_REVERSED_Z 等引擎侧宏。
  • .program 脚本由 GpuProgramTranslator 收集参数后把语言交给 GpuProgramManager::create。
  • GLSLangProgram::loadFromSource 编译出 std::vector<uint32> SPIR-V 汇编,配合微代码缓存免重编译。

阅读导航:上一节:6.2 着色器参数绑定 · 下一节:7.1 Bites 应用上下文 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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