11.1 网格升级工具
MeshUpgrader 是 OGRE 自带的老网格升级工具:把一个旧版本 .mesh 读进来,按当前引擎的顶点缓冲布局规则重组、消解颜色类型歧义、可选生成 LOD,再写回指定版本。它的价值在于让声明与缓冲布局跟上引擎对动画网格的要求——因为把 NORMAL、BLEND_WEIGHTS 塞在同一缓冲里,在某些驱动/动画路径下是错的。工具的核心是 getAutoOrganisedDeclaration:它不增删任何顶点元素,只是按动画类型把元素重新分配到更优的 buffer。
本章与站内既有内容的分工
9.3 讲工具对索引的顶点缓存优化(optimiseVertexCacheTriList,就在升级管道里作为可选步);本节讲它对顶点缓冲布局的重组与颜色统一。两者都是离线工具而非运行时渲染路径。lab 复现重组判定、颜色转换与 LOD 门控。
升级管道:五步固定顺序
main.cpp 中每次升级都走同一管道:importMesh 读二进制网格 → reorganiseVertexBuffers 重组缓冲布局 → resolveColourAmbiguities 统一颜色类型 → buildLod 生成 LOD → 可选边列表/切线/顶点缓存优化 → exportMesh 写出:
// Tools/MeshUpgrader/src/main.cpp:main 中的升级管道(v14.6.3 源码摘录,已删减)
DataStreamPtr stream(memstream);
meshSerializer.importMesh(stream, mesh);
// Write out the converted mesh
String dest;
if (numargs == startIdx + 2) {
dest = args[startIdx + 1];
} else {
dest = source;
}
String response;
reorganiseVertexBuffers(opts, *mesh);
// Deal with VET_COLOUR ambiguities
resolveColourAmbiguities(mesh);
buildLod(opts, meshPtr);
reorganiseVertexBuffers 先让 Mesh 自己确定动画类型,然后对共享顶点数据与每个非共享子网格调用 getAutoOrganisedDeclaration,只有自动组织结果与当前声明不同才 reorganiseBuffers。sm->useSharedVertices 的子网格跳过——它们共享网格级顶点数据,不能各自重排:
// Tools/MeshUpgrader/src/main.cpp:reorganiseVertexBuffers(v14.6.3 源码摘录,已删减)
if (mesh.sharedVertexData) {
// Automatic
VertexDeclaration* newDcl =
mesh.sharedVertexData->vertexDeclaration->getAutoOrganisedDeclaration(
mesh.hasSkeleton(), mesh.hasVertexAnimation(), mesh.getSharedVertexDataAnimationIncludesNormals());
if (*newDcl != *(mesh.sharedVertexData->vertexDeclaration)) {
mesh.sharedVertexData->reorganiseBuffers(newDcl);
}
}
for (size_t i = 0; i < mesh.getNumSubMeshes(); i++)
{
SubMesh* sm = mesh.getSubMesh(i);
if (!sm->useSharedVertices) {
const bool hasVertexAnim = sm->getVertexAnimationType() != Ogre::VAT_NONE;
// Automatic
VertexDeclaration* newDcl =
sm->vertexData->vertexDeclaration->getAutoOrganisedDeclaration(
mesh.hasSkeleton(), hasVertexAnim, sm->getVertexAnimationIncludesNormals() );
if (*newDcl != *(sm->vertexData->vertexDeclaration)) {
sm->vertexData->reorganiseBuffers(newDcl);
}
}
}
getAutoOrganisedDeclaration:不增删元素,只重排布局
这是整个工具最微妙的部分。它先 clone() 当前声明、把全部元素暂时放到 buffer 0,然后按语义逐元素决定前后是否需要拆 buffer:位置动画且无法线动画时 POSITION 独占(splitWithNext);NORMAL 不能与混合权重/索引共享(splitWithPrev),且所有动画网格在法线后必须拆(splitWithNext);其余元素在「有骨骼或顶点动画」时不能与 POSITION 同 buffer。最终通过 modifyElement 重写每个元素的目标 buffer 与偏移:
// OgreMain/src/OgreHardwareVertexBuffer.cpp:VertexDeclaration::getAutoOrganisedDeclaration(v14.6.3 源码摘录,已删减)
VertexDeclaration* newDecl = this->clone();
// Set all sources to the same buffer (for now)
const VertexDeclaration::VertexElementList& elems = newDecl->getElements();
unsigned short c = 0;
for (auto& elem : elems)
{
// Set source & offset to 0 for now, before sort
newDecl->modifyElement(c, 0, 0, elem.getType(), elem.getSemantic(), elem.getIndex());
++c;
}
newDecl->sort();
// Now sort out proper buffer assignments and offsets
size_t offset = 0;
c = 0;
unsigned short buffer = 0;
VertexElementSemantic prevSemantic = VES_POSITION;
for (auto& elem : elems)
{
bool splitWithPrev = false;
bool splitWithNext = false;
switch (elem.getSemantic())
{
case VES_POSITION:
// Split positions if vertex animated with only positions
// group with normals otherwise
splitWithPrev = false;
splitWithNext = vertexAnimation && !vertexAnimationNormals;
break;
case VES_NORMAL:
// Normals can't share with blend weights/indices
splitWithPrev = (prevSemantic == VES_BLEND_WEIGHTS || prevSemantic == VES_BLEND_INDICES);
// All animated meshes have to split after normal
splitWithNext = (skeletalAnimation || (vertexAnimation && vertexAnimationNormals));
break;
case VES_BLEND_WEIGHTS:
// Blend weights/indices can be sharing with their own buffer only
splitWithPrev = true;
break;
case VES_BLEND_INDICES:
// Blend weights/indices can be sharing with their own buffer only
splitWithNext = true;
break;
default:
case VES_DIFFUSE:
case VES_SPECULAR:
case VES_TEXTURE_COORDINATES:
case VES_BINORMAL:
case VES_TANGENT:
// Make sure position is separate if animated & there were no normals
splitWithPrev = prevSemantic == VES_POSITION &&
(skeletalAnimation || vertexAnimation);
break;
}
if (splitWithPrev && offset)
{
++buffer;
offset = 0;
}
prevSemantic = elem.getSemantic();
newDecl->modifyElement(c, buffer, offset,
elem.getType(), elem.getSemantic(), elem.getIndex());
if (splitWithNext)
{
++buffer;
offset = 0;
}
else
{
offset += elem.getSize();
}
++c;
}
return newDecl;
lab 的 autoOrganise 复现这套 split 规则,验证两个关键结论:
- 无骨骼无动画时,
POSITION/NORMAL/TEXCOORD0三个元素都不触发 split,全部留在 buffer 0,自动组织结果与现状相同,不重排。 - 有骨骼动画时,
NORMAL的splitWithNext = skeletalAnimation为真,在 NORMAL 处理完毕后 buffer 从 0 升到 1;随后的TEXCOORD0走 default 分支,splitWithPrev要求「前一语义是 POSITION」,而前一语义已是 NORMAL,所以它不因 prev 拆 buffer,直接落在递增后的 buffer 1。
resolveColourAmbiguities:统一成 VET_UBYTE4_NORM
老网格的颜色顶点元素类型不统一(可能 VET_COLOUR/VET_COLOUR_ARGB)。升级第一步是探测:遍历共享数据与所有子网格,checkColour 汇总「有没有颜色」「有没有歧义」「原类型」。没有颜色就直接返回(不产生任何改动),否则把 originalType 统一转成 VET_UBYTE4_NORM:
// Tools/MeshUpgrader/src/main.cpp:resolveColourAmbiguities(v14.6.3 源码摘录,已删减)
bool hasColour = false;
bool hasAmbiguousColour = false;
VertexElementType originalType = VET_FLOAT1;
if (mesh->sharedVertexData) {
checkColour(mesh->sharedVertexData, hasColour, hasAmbiguousColour, originalType);
}
for (unsigned short i = 0; i < mesh->getNumSubMeshes(); ++i) {
SubMesh* sm = mesh->getSubMesh(i);
if (sm->useSharedVertices == false) {
checkColour(sm->vertexData, hasColour, hasAmbiguousColour, originalType);
}
}
if(!hasColour)
return;
VertexElementType desiredType = VET_UBYTE4_NORM;
if (mesh->sharedVertexData) {
mesh->sharedVertexData->convertPackedColour(originalType, desiredType);
}
for (unsigned short i = 0; i < mesh->getNumSubMeshes(); ++i) {
SubMesh* sm = mesh->getSubMesh(i);
if (!sm->useSharedVertices) {
sm->vertexData->convertPackedColour(originalType, desiredType);
}
}
工具输出的验证从版本回到场景
MeshUpgrader 把输入导入资源模型,再按目标格式写出。验证工具时同时确认输入版本、序列化输出、材质和骨架链接。只比文件大小看不到语义变化。
对照子网格数、索引数、包围盒和材质引用。使用卷一 10.3 的导入路径加载结果并运行同一绘制场景。
源码定位
Tools/MeshUpgrader/src/main.cpp:main 升级管道(530-607 行)Tools/MeshUpgrader/src/main.cpp:reorganiseVertexBuffers(208-238 行)Tools/MeshUpgrader/src/main.cpp:resolveColourAmbiguities(377-406 行)OgreMain/src/OgreHardwareVertexBuffer.cpp:VertexDeclaration::getAutoOrganisedDeclaration(566-648 行)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
VertexElementRepro 记录语义与所在 buffer;autoOrganise 复现 getAutoOrganisedDeclaration 的 split 规则;MeshUpgradeRepro 复现重组判定(nd != elements 才动)、无颜色跳过、LOD 门控与五步管道。它与 src/11-1-mesh-upgrader.cpp 逐字节一致:
// file: src/11-1-mesh-upgrader.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/11-1-mesh-upgrader.cpp -o bin/11-1-mesh-upgrader && ./bin/11-1-mesh-upgrader
//
// 复现 MeshUpgrader 的升级管道(Tools/MeshUpgrader/src/main.cpp 530-607 的
// importMesh→reorganiseVertexBuffers→resolveColourAmbiguities→buildLod→
// exportMesh,以及 OgreMain/src/OgreHardwareVertexBuffer.cpp 566-648 的
// getAutoOrganisedDeclaration):自动组织不增删元素,而是按动画需求把元素
// 重新分配到更优的 buffer(NORMAL 在有骨骼/顶点动画时单独拆 buffer);
// 声明布局与现状不同才 reorganiseBuffers;只有存在颜色语义时才统一
// packed colour 为 VET_UBYTE4_NORM;buildLod 由 numLods!=0||autoconfigure 门控。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <string>
#include <utility>
#include <vector>
namespace ogre_repro {
struct VertexElementRepro {
std::string semantic; // "POSITION"/"NORMAL"/"TEXCOORD0"
uint8_t buffer = 0; // 该元素当前所在顶点缓冲区
bool operator==(const VertexElementRepro& o) const {
return semantic == o.semantic && buffer == o.buffer;
}
};
// 对应 VertexData 中与升级相关的状态
struct VertexDataRepro {
std::vector<VertexElementRepro> elements;
uint32_t colourType = 0; // 0=无颜色 1=旧 packed colour 2=VET_UBYTE4_NORM
std::string colourDcl;
void convertPackedColour() {
colourType = 2;
colourDcl = "VET_UBYTE4_NORM";
}
};
struct SubMeshRepro {
bool useShared = false;
bool hasVertexAnim = false;
VertexDataRepro data;
};
// 对应 getAutoOrganisedDeclaration 的 split 规则(566-648 行)
std::vector<VertexElementRepro> autoOrganise(const VertexDataRepro& d, bool skeletal,
bool vertexAnim, bool vAnimNormals) {
std::vector<VertexElementRepro> out;
uint8_t buffer = 0;
bool bufferUsed = false;
std::string prevSemantic = "POSITION";
for (const auto& e : d.elements) {
const std::string& s = e.semantic;
bool splitWithPrev = false;
bool splitWithNext = false;
if (s == "POSITION") {
// 只做位置动画时 position 独占 buffer
splitWithNext = vertexAnim && !vAnimNormals;
} else if (s == "NORMAL") {
splitWithPrev = (prevSemantic == "BLEND_WEIGHTS" || prevSemantic == "BLEND_INDICES");
splitWithNext = skeletal || (vertexAnim && vAnimNormals);
} else {
// 其余元素:骨骼/顶点动画时不能与 position 同 buffer
splitWithPrev = prevSemantic == "POSITION" && (skeletal || vertexAnim);
}
if (splitWithPrev && bufferUsed) {
++buffer;
bufferUsed = false;
}
out.push_back({s, buffer});
bufferUsed = true;
prevSemantic = s;
if (splitWithNext) {
++buffer;
bufferUsed = false;
}
}
return out;
}
// 对应 MeshUpgrader 的升级步骤(瘦身版)
class MeshUpgradeRepro {
public:
bool hasShared = false;
VertexDataRepro shared;
std::vector<SubMeshRepro> submeshes;
bool hasSkeleton = false;
bool hasVertexAnimation = false;
bool sharedIncludesNormals = false;
uint32_t reorganisedBuffers = 0;
uint32_t coloursConverted = 0;
uint32_t lodLevels = 0;
bool exported = false;
std::string sourceFormat;
// 对应 main.cpp 208-238 的 reorganiseVertexBuffers
void reorganiseVertexBuffers() {
if (hasShared) {
auto nd = autoOrganise(shared, hasSkeleton, hasVertexAnimation, sharedIncludesNormals);
if (nd != shared.elements) {
shared.elements = std::move(nd);
++reorganisedBuffers;
}
}
for (auto& sm : submeshes) {
if (sm.useShared)
continue;
const bool vAnimNormals = sm.hasVertexAnim && sharedIncludesNormals;
auto nd = autoOrganise(sm.data, hasSkeleton, sm.hasVertexAnim, vAnimNormals);
if (nd != sm.data.elements) {
sm.data.elements = std::move(nd);
++reorganisedBuffers;
}
}
}
// 对应 main.cpp 377-406 的 resolveColourAmbiguities
void resolveColourAmbiguities() {
bool hasColour = false;
if (hasShared)
hasColour = hasColour || shared.colourType != 0;
for (auto& sm : submeshes)
if (!sm.useShared)
hasColour = hasColour || sm.data.colourType != 0;
if (!hasColour)
return; // 源码 393-394 行:无颜色直接返回
if (hasShared) {
shared.convertPackedColour();
++coloursConverted;
}
for (auto& sm : submeshes)
if (!sm.useShared) {
sm.data.convertPackedColour();
++coloursConverted;
}
}
// 对应 main.cpp 312-320 的 buildLod 门控
void buildLod(uint32_t numLods, bool lodAutoconfigure) {
const bool genLod = (numLods != 0 || lodAutoconfigure);
if (genLod)
lodLevels = numLods;
}
void importMesh() { sourceFormat = "binary"; }
void exportMesh() { exported = true; }
// 对应 main.cpp 530-607 的完整管道
void run(uint32_t numLods, bool lodAutoconfigure) {
importMesh();
reorganiseVertexBuffers();
resolveColourAmbiguities();
buildLod(numLods, lodAutoconfigure);
exportMesh();
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 场景 A:无骨骼无动画,旧布局已是自动组织的布局 → 不重排
MeshUpgradeRepro a;
a.hasShared = true;
a.shared.elements = {{"POSITION", 0}, {"NORMAL", 0}, {"TEXCOORD0", 0}};
a.reorganiseVertexBuffers();
CHECK_EQ(a.reorganisedBuffers, 0u);
CHECK_EQ(a.shared.elements[2].buffer, 0u); // TEXCOORD0 留在 buffer0
// 场景 B:骨骼动画子网格,NORMAL 之后必须拆 buffer → 重排 1 次
MeshUpgradeRepro b;
b.hasSkeleton = true;
SubMeshRepro skinned;
skinned.data.elements = {{"POSITION", 0}, {"NORMAL", 0}, {"TEXCOORD0", 0}};
skinned.data.colourType = 1; // 旧 packed colour
b.submeshes.push_back(std::move(skinned));
b.reorganiseVertexBuffers();
CHECK_EQ(b.reorganisedBuffers, 1u);
CHECK_EQ(b.submeshes[0].data.elements[1].buffer, 0u); // NORMAL 留在 buffer0
CHECK_EQ(b.submeshes[0].data.elements[2].buffer, 1u); // TEXCOORD0 拆到 buffer1
// 颜色歧义消解:只有带颜色的子网格被转换
b.resolveColourAmbiguities();
CHECK_EQ(b.coloursConverted, 1u);
CHECK_EQ(b.submeshes[0].data.colourType, 2u);
CHECK_EQ(b.submeshes[0].data.colourDcl, std::string("VET_UBYTE4_NORM"));
// 无颜色网格:resolve 直接返回
MeshUpgradeRepro clean;
clean.hasShared = true;
clean.shared.elements = {{"POSITION", 0}};
clean.resolveColourAmbiguities();
CHECK_EQ(clean.coloursConverted, 0u);
CHECK_EQ(clean.shared.colourType, 0u);
// buildLod 门控:numLods==0 且未 autoconfigure 时不生成
b.lodLevels = 99;
b.buildLod(0, false);
CHECK_EQ(b.lodLevels, 99u); // 保持原值
b.buildLod(3, false);
CHECK_EQ(b.lodLevels, 3u); // numLods=3 生成 3 级
// 完整管道:顺序 importMesh→reorganise→resolve→buildLod→export
MeshUpgradeRepro full;
full.hasSkeleton = true;
SubMeshRepro sm;
sm.data.elements = {{"POSITION", 0}, {"NORMAL", 0}, {"TEXCOORD0", 0}};
full.submeshes.push_back(std::move(sm));
full.run(2, false);
CHECK_EQ(full.sourceFormat, std::string("binary"));
CHECK_EQ(full.reorganisedBuffers, 1u);
CHECK_EQ(full.coloursConverted, 0u);
CHECK_EQ(full.lodLevels, 2u);
CHECK(full.exported);
return lab::report("11.1 网格升级工具");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 17/17 通过。
小结
- 升级管道固定为
importMesh → reorganiseVertexBuffers → resolveColourAmbiguities → buildLod → exportMesh。 getAutoOrganisedDeclaration只重排元素到新 buffer 布局,不增删元素;NORMAL在骨骼/顶点动画后单独拆 buffer,POSITION仅在纯位置动画时独占。- 只有自动组织结果与现状不同才
reorganiseBuffers,使用共享顶点数据的子网格跳过。 resolveColourAmbiguities无颜色直接返回;有颜色时统一转为VET_UBYTE4_NORM。buildLod由numLods != 0 || autoconfigure门控,升级结果可通过顶点缓存优化进一步打磨索引。
阅读导航:上一节:10.3 资源流式加载 · 下一节:11.2 XML 转换器 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。