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);
关键流程四步:
- 校验对象名:
obj->name为空直接报CE_OBJECTNAMEEXPECTED——脚本里material { ... }少了名字是不合法的。 - 创建材质:先发
CreateMaterialScriptCompilerEvent事件,让监听器有机会介入(_fireEvent返回 true 表示已处理);没人处理就回落MaterialManager::create(name, group)。 - 建空材质:
removeAllTechniques()——材质对象刚创建时带一套默认 technique,脚本里写的 technique 要替换它,所以先清空。 - 挂上下文:
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 脚本词法与语法树 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。