《OGRE 3D 渲染引擎原理与架构》4.2 材质脚本解析

材质脚本由三个翻译器逐级消费:MaterialTranslator 创建材质并 removeAllTechniques,TechniqueTranslator 生成 Technique,PassTranslator 生成 Pass 并写回 ambient/diffuse;子对象走 processNode,父对象经 context 传递。lab 复现该翻译链。

4.2 材质脚本解析

4.1 节的 ScriptCompiler 把脚本编译成 AST 就停手了,真正把 AST「翻译」成引擎资源的是一批 ScriptTranslator 子类。材质脚本是最典型的案例——.material 文件里的 material/technique/pass 三级嵌套,对应 MaterialTranslator、TechniqueTranslator、PassTranslator 三个翻译器。这一节跟着一段材质脚本走完整个翻译过程。

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

第 4.1 节停在 AST 之后,本节展示翻译阶段怎么消费 AST。卷二讲过 Material/Technique/Pass 的运行时结构(渲染状态怎么组织),本节看这些结构怎么由脚本驱动生成——翻译器调用的 createTechnique/createPass/setAmbient 就是卷二介绍的那些方法。4.3 节再下沉到文本 → token → 树的词法与语法。

三级翻译器:对象树的下沉

一段 material 脚本的 AST 是个三级对象树:material 有 technique 子对象,technique 又有 pass 子对象。翻译阶段就按这棵树逐级下沉。最上层 MaterialTranslator::translate 负责创建材质本体:

// OgreMain/src/OgreScriptTranslator.cpp:MaterialTranslator::translate(v14.6.3 源码摘录,已删减)
    void MaterialTranslator::translate(ScriptCompiler *compiler, const AbstractNodePtr &node)
    {
        ObjectAbstractNode *obj = static_cast<ObjectAbstractNode*>(node.get());
        if(obj->name.empty())
        {
            compiler->addError(ScriptCompiler::CE_OBJECTNAMEEXPECTED, obj->file, obj->line);
            return;
        }

        Material* mMaterial = 0;

        // Create a material with the given name
        CreateMaterialScriptCompilerEvent evt(node->file, obj->name, compiler->getResourceGroup());
        bool processed = compiler->_fireEvent(&evt, (void*)&mMaterial);

        if(!processed)
        {
            mMaterial = MaterialManager::getSingleton().create(obj->name, compiler->getResourceGroup()).get();
        }

        if(!mMaterial)
        {
            compiler->addError(ScriptCompiler::CE_OBJECTALLOCATIONERROR, obj->file, obj->line, obj->name);
            return;
        }

        mMaterial->removeAllTechniques();
        obj->context = mMaterial;
        mMaterial->_notifyOrigin(obj->file);

关键流程四步:

  1. 校验对象名:obj->name 为空直接报 CE_OBJECTNAMEEXPECTED——脚本里 material { ... } 少了名字是不合法的。
  2. 创建材质:先发 CreateMaterialScriptCompilerEvent 事件,让监听器有机会介入(_fireEvent 返回 true 表示已处理);没人处理就回落 MaterialManager::create(name, group)。
  3. 建空材质:removeAllTechniques()——材质对象刚创建时带一套默认 technique,脚本里写的 technique 要替换它,所以先清空。
  4. 挂上下文:obj->context = mMaterial——这是整个翻译器的关键机制,父对象的 context 字段向下传递对象指针,子翻译器靠 any_cast 从 obj->parent->context 取出父级对象。

建完材质后,MaterialTranslator 遍历自己的子节点,区分两种类型:

// OgreMain/src/OgreScriptTranslator.cpp:MaterialTranslator 子节点遍历(v14.6.3 源码摘录,已删减)
        for(auto & i : obj->children)
        {
            if(i->type == ANT_PROPERTY)
            {
                PropertyAbstractNode *prop = static_cast<PropertyAbstractNode*>(i.get());
                switch(prop->id)
                {
                case ID_LOD_VALUES:
                    {
                        Material::LodValueList lods;
                        for(const auto& j : prop->values)
                        {
                            Real v = 0;
                            if(getReal(j, &v))
                                lods.push_back(v);
                            else
                                compiler->addError(ScriptCompiler::CE_NUMBEREXPECTED, prop->file, prop->line,
                                                   "lod_values expects only numbers as arguments");
                        }
                        mMaterial->setLodLevels(lods);
                    }
                    break;
                case ID_RECEIVE_SHADOWS:
                    if(getValue(prop, compiler, bval))
                        mMaterial->setReceiveShadows(bval);
                    break;
                default:
                    compiler->addError(ScriptCompiler::CE_UNEXPECTEDTOKEN, prop->file, prop->line,
                                       "token \"" + prop->name + "\" is not recognized");
                }
            }
            else if(i->type == ANT_OBJECT)
            {
                processNode(compiler, i);
            }
        }

子节点分两类处理:属性节点(ANT_PROPERTY)是 material 自己的关键词(如 lod_values、receive_shadows),按 prop->id 的 switch 分发;对象节点(ANT_OBJECT)是嵌套的子对象(technique),统一交给 processNode——它根据对象类型查翻译器并递归调用。processNode 就是「子对象下沉」的机制,三层翻译器靠它串起来。

Technique 与 Pass:往下走两级

TechniqueTranslator::translate 从父对象的 context 取材质,创建 technique:

// OgreMain/src/OgreScriptTranslator.cpp:TechniqueTranslator::translate(v14.6.3 源码摘录,已删减)
    void TechniqueTranslator::translate(ScriptCompiler *compiler, const AbstractNodePtr &node)
    {
        ObjectAbstractNode *obj = static_cast<ObjectAbstractNode*>(node.get());

        // Create the technique from the material
        Ogre::Material *material = Ogre::any_cast<Ogre::Material*>(obj->parent->context);
        mTechnique = material->createTechnique();
        obj->context = mTechnique;

        // Get the name of the technique
        if(!obj->name.empty())
            mTechnique->setName(obj->name);

        uint32 uival;
        String sval;

        // Set the properties for the material
        for(auto & i : obj->children)
        {
            if(i->type == ANT_PROPERTY)
            {
                PropertyAbstractNode *prop = static_cast<PropertyAbstractNode*>(i.get());
                switch(prop->id)
                {
                case ID_SCHEME:
                    if(getValue(prop, compiler, sval))
                        mTechnique->setSchemeName(sval);
                    break;
                case ID_LOD_INDEX:
                    if(getValue(prop, compiler, uival))
                        mTechnique->setLodIndex(static_cast<uint16>(uival));
                    break;

obj->parent->context 是 any_cast<Material*>——这正好验证了 MaterialTranslator 里那句 obj->context = mMaterial 的用途:context 字段是父子对象间传递已建对象指针的信使。technique 建好后同样把 obj->context 指向自己,供更下一层的 PassTranslator 取用。scheme、lod_index 这些 technique 级属性在 switch 里处理。

最底层 PassTranslator::translate 走同样的套路,从父级取 technique 创建 pass:

// OgreMain/src/OgreScriptTranslator.cpp:PassTranslator::translate(v14.6.3 源码摘录,已删减)
    void PassTranslator::translate(ScriptCompiler *compiler, const AbstractNodePtr &node)
    {
        ObjectAbstractNode *obj = static_cast<ObjectAbstractNode*>(node.get());

        Technique *technique = any_cast<Technique*>(obj->parent->context);
        mPass = technique->createPass();
        obj->context = mPass;

        // Get the name of the technique
        if(!obj->name.empty())
            mPass->setName(obj->name);

        Real fval;
        bool bval;
        uint32 uival;

        // Set the properties for the material
        for(auto & i : obj->children)
        {
            if(i->type == ANT_PROPERTY)
            {
                PropertyAbstractNode *prop = static_cast<PropertyAbstractNode*>(i.get());
                switch(prop->id)
                {
                case ID_AMBIENT:
                    if(prop->values.empty())
                    {
                        compiler->addError(ScriptCompiler::CE_NUMBEREXPECTED, prop->file, prop->line);
                    }
                    else if(prop->values.size() > 4)
                    {
                        compiler->addError(ScriptCompiler::CE_FEWERPARAMETERSEXPECTED, prop->file, prop->line,
                                           "ambient must have at most 4 parameters");
                    }
                    else
                    {
                        if(getAtomId(prop->values.front()) == ID_VERTEXCOLOUR)
                        {
                            mPass->setVertexColourTracking(mPass->getVertexColourTracking() | TVC_AMBIENT);
                        }
                        else
                        {
                            ColourValue val = ColourValue::White;
                            if(getColour(prop->values.begin(), prop->values.end(), &val))
                                mPass->setAmbient(val);
                            else
                                compiler->addError(*prop, "ambient requires 3 or 4 colour arguments, or a \"vertexcolour\" directive");
                        }
                    }
                    break;
                case ID_DIFFUSE:
                    ...
                    break;

ambient 属性的处理展示了参数校验与两种取值方式:空值报 CE_NUMBEREXPECTED,超过 4 个参数报 CE_FEWERPARAMETERSEXPECTED;第一个原子是 vertexcolour 关键字就启用顶点色追踪(TVC_AMBIENT 位),否则用 getColour 解析 3-4 个数值填入 ColourValue 并 setAmbient。diffuse 同构。这些 CE_* 错误码正是 4.1 节介绍的那套枚举。

MaterialManager:翻译的资源挂钩

翻译器创建材质靠的是 MaterialManager——它就是 3.1 节 ResourceManager 的一个具体子类:

// OgreMain/src/OgreMaterialManager.cpp:createImpl / create(v14.6.3 源码摘录,已删减)
    Resource* MaterialManager::createImpl(const String& name, ResourceHandle handle,
        const String& group, bool isManual, ManualResourceLoader* loader,
    const NameValuePairList* params)
    {
        return OGRE_NEW Material(this, name, handle, group, isManual, loader);
    }
    //-----------------------------------------------------------------------
    MaterialPtr MaterialManager::create (const String& name, const String& group,
                                    bool isManual, ManualResourceLoader* loader,
                                    const NameValuePairList* createParams)
    {
        return static_pointer_cast<Material>(createResource(name,group,isManual,loader,createParams));
    }

createImpl 是 ResourceManager 的纯虚方法,MaterialManager 的实现就一行——OGRE_NEW Material(...) 造出 Material 资源对象。create 调基类 createResource(3.1 节讲过的句柄分配 + 登记流程),返回值 static_pointer_cast<Material> 转成 MaterialPtr。MaterialTranslator 里那句 MaterialManager::create(obj->name, group) 最终就落在这里。

源码定位

  • OgreMain/src/OgreScriptTranslator.cpp :MaterialTranslator::translate(988-1119)、CreateMaterialScriptCompilerEvent(1000)、removeAllTechniques(1014)、obj->context = mMaterial(1015)、子节点遍历(1021-1115)、TechniqueTranslator::translate(1129-1284)、PassTranslator::translate(1294 起)、ID_AMBIENT(1318-1343)、ID_DIFFUSE(1344-1369)
  • OgreMain/src/OgreMaterialManager.cpp :createImpl(80-85)、create(87-92)

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

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

下面用纯 C++ 复现材质脚本翻译:Material/Technique/Pass 三级结构、MaterialManager::create 的 createImpl 挂钩、以及 Builder 对 MaterialTranslator/TechniqueTranslator/PassTranslator 组合逻辑的模拟。它与 src/ogre-ext-04-2-material-script.cpp 逐字节一致:

// file: src/ogre-ext-04-2-material-script.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-04-2-material-script.cpp -o bin/ogre-ext-04-2-material-script && ./bin/ogre-ext-04-2-material-script
//
// 复现材质脚本解析(对应 OgreMain/src/OgreScriptTranslator.cpp 988-1119 的
//   MaterialTranslator::translate、1129-1140 的 TechniqueTranslator、1294-1300
//   的 PassTranslator,以及 OgreMaterialManager.cpp 80-92 的 createImpl/create):
//   脚本对象树驱动构造:Material 建好后 removeAllTechniques,子对象依次生成
//   Technique/Pass,属性(ambient/diffuse)写回 Pass。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

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

namespace ogre_repro {

using String = std::string;

struct Colour {
  float r = 0, g = 0, b = 0, a = 1;
  explicit Colour(const std::vector<float>& v) {
    if (v.size() > 0) r = v[0];
    if (v.size() > 1) g = v[1];
    if (v.size() > 2) b = v[2];
    if (v.size() > 3) a = v[3];
  }
};

// 极简 Pass / Technique / Material(对应 OGRE 的材质层级)
class Pass {
 public:
  void setName(const String& n) { mName = n; }
  String mName;
  Colour mAmbient{std::vector<float>{0, 0, 0}};
  Colour mDiffuse{std::vector<float>{0, 0, 0}};
};

class Technique {
 public:
  Pass* createPass() {
    mPasses.push_back(new Pass());
    return mPasses.back();
  }
  void setName(const String& n) { mName = n; }
  String mName;
  std::vector<Pass*> mPasses;
};

class Material {
 public:
  explicit Material(const String& name) : mName(name) {}
  ~Material() {
    for (auto t : mTechniques) {
      for (auto p : t->mPasses) delete p;
      delete t;
    }
  }
  Technique* createTechnique() {
    mTechniques.push_back(new Technique());
    return mTechniques.back();
  }
  void removeAllTechniques() {
    for (auto t : mTechniques) {
      for (auto p : t->mPasses) delete p;
      delete t;
    }
    mTechniques.clear();
  }
  String mName;
  std::vector<Technique*> mTechniques;
};

// 对应 MaterialManager:create 经 createImpl 构造并登记
class MaterialManager {
 public:
  Material* create(const String& name) {
    Material* mat = createImpl(name);
    mRegistry.emplace(name, mat);
    return mat;
  }
  virtual Material* createImpl(const String& name) { return new Material(name); }
  Material* getByName(const String& name) {
    auto it = mRegistry.find(name);
    return it == mRegistry.end() ? nullptr : it->second;
  }
  std::map<String, Material*> mRegistry;
};

// 极简脚本对象树:对应 CST 翻译后的 ObjectAbstractNode
struct ScriptProperty {
  String name;
  std::vector<float> values;
};
struct ScriptObject {
  String cls;
  String name;
  std::vector<ScriptProperty> props;
  std::vector<ScriptObject> children;
};

// 翻译器:MaterialTranslator/TechniqueTranslator/PassTranslator 的组合逻辑,
// 用 currentMaterial/currentTechnique 扮演 obj->parent->context
class Builder {
 public:
  explicit Builder(MaterialManager& mgr) : mgr(mgr) {}

  void translate(const ScriptObject& obj) {
    if (obj.cls == "material") {
      // 对应 MaterialTranslator::translate 1000-1016
      currentMaterial = mgr.create(obj.name);
      currentMaterial->removeAllTechniques();
      for (const auto& child : obj.children) translate(child);
    } else if (obj.cls == "technique") {
      // 对应 TechniqueTranslator::translate 1134-1140
      Technique* tech = currentMaterial->createTechnique();
      if (!obj.name.empty()) tech->setName(obj.name);
      for (const auto& child : obj.children) translate(child);
    } else if (obj.cls == "pass") {
      // 对应 PassTranslator::translate 1298-1300
      Pass* pass = currentMaterial->mTechniques.back()->createPass();
      if (!obj.name.empty()) pass->setName(obj.name);
      for (const auto& prop : obj.props) {
        if (prop.name == "ambient")
          pass->mAmbient = Colour(prop.values);
        else if (prop.name == "diffuse")
          pass->mDiffuse = Colour(prop.values);
      }
    }
  }

  Material* currentMaterial = nullptr;
  MaterialManager& mgr;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  MaterialManager mgr;

  // 构造材质脚本对象树:
  // material Red { technique t0 { pass p0 { ambient 0.8 0.2 0.2 diffuse 0.6 0.6 0.6 } } }
  ScriptObject pass;
  pass.cls = "pass";
  pass.name = "p0";
  pass.props.push_back({"ambient", {0.8f, 0.2f, 0.2f}});
  pass.props.push_back({"diffuse", {0.6f, 0.6f, 0.6f}});
  ScriptObject tech;
  tech.cls = "technique";
  tech.name = "t0";
  tech.children.push_back(pass);
  ScriptObject mat;
  mat.cls = "material";
  mat.name = "Red";
  mat.children.push_back(tech);

  // 翻译前没有任何材质
  CHECK_EQ(mgr.mRegistry.size(), size_t(0));

  Builder builder(mgr);
  builder.translate(mat);
  CHECK_EQ(mgr.mRegistry.size(), size_t(1));

  // 材质名与三级结构(对应 create + removeAllTechniques + createTechnique + createPass)
  Material* red = mgr.getByName("Red");
  CHECK(red != nullptr);
  CHECK_EQ(red->mTechniques.size(), size_t(1));
  CHECK(red->mTechniques[0]->mName == "t0");
  CHECK_EQ(red->mTechniques[0]->mPasses.size(), size_t(1));
  CHECK(red->mTechniques[0]->mPasses[0]->mName == "p0");

  // 属性写回 Pass:ambient/diffuse 颜色
  Pass* p0 = red->mTechniques[0]->mPasses[0];
  CHECK(p0->mAmbient.r == 0.8f);
  CHECK(p0->mAmbient.g == 0.2f);
  CHECK(p0->mDiffuse.b == 0.6f);
  CHECK(p0->mDiffuse.a == 1.0f);  // 未给的 alpha 保持默认 1

  // 第二个材质:未命名 technique/pass 也成立
  ScriptObject pass2;
  pass2.cls = "pass";
  pass2.props.push_back({"ambient", {0.1f, 0.1f, 0.1f}});
  ScriptObject tech2;
  tech2.cls = "technique";
  tech2.children.push_back(pass2);
  ScriptObject mat2;
  mat2.cls = "material";
  mat2.name = "Blue";
  mat2.children.push_back(tech2);
  Builder builder2(mgr);
  builder2.translate(mat2);

  Material* blue = mgr.getByName("Blue");
  CHECK(blue != nullptr);
  CHECK_EQ(blue->mTechniques.size(), size_t(1));
  CHECK_EQ(blue->mTechniques[0]->mPasses.size(), size_t(1));
  CHECK(blue->mTechniques[0]->mPasses[0]->mAmbient.b == 0.1f);
  CHECK_EQ(mgr.mRegistry.size(), size_t(2));

  return lab::report("4.2 材质脚本解析");
}

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

小结

  • 材质脚本的三级嵌套对应三个翻译器:MaterialTranslator/TechniqueTranslator/PassTranslator。
  • 父对象通过 obj->context 向下传递已建对象指针,子翻译器 any_cast 取用。
  • Material 创建后先 removeAllTechniques 再重新生成,保证脚本内容完全替换默认值。
  • processNode 统一处理对象子节点,属性按 prop->id 的 switch 分发。
  • MaterialManager::create 走 ResourceManager::createResource,createImpl 一行 OGRE_NEW Material(...)。

阅读导航:上一节:4.1 脚本编译器 · 下一节:4.3 脚本词法与语法树 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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