《OGRE 3D 渲染引擎原理与架构》11.1 网格升级工具

11.1 讲 MeshUpgrader 工具。管道固定为 importMesh→reorganise→resolveColour→buildLod→exportMesh;getAutoOrganisedDeclaration 只重排元素、不增删,NORMAL 在骨骼/顶点动画时单独拆 buffer。lab 复现重排、颜色统一与 LOD 门控,17 项断言。

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 转换器 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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