《OGRE 3D 渲染引擎原理与架构》11.2 XML 转换器

11.2 讲 XMLConverter 工具的双向分流。它按源文件扩展名分流:mesh 走 meshToXML、skeleton 走 skeletonToXML、xml 走 XMLToBinary、其余报错;XMLToBinary 再读根元素前缀 mesh/skeleton 决定导出网格还是骨架二进制。lab 复现扩展名推断、根元素分流与未知输入报错,22 项断言。

11.2 XML 转换器

XMLConverter 是 OGRE 的网格/骨架 XML 桥:它把二进制 .mesh/.skeleton 转成可读的 XML,也把 XML 转回二进制。因为输入可能是二进制也可能是 XML,工具在 main 里按源文件扩展名分流:.mesh → meshToXML,.skeleton → skeletonToXML,.xml → XMLToBinary,其他扩展名直接报 Unknown input type。而 XMLToBinary 还要再读 XML 的根元素来判断里面装的是网格还是骨架,因为 XML 文件本身不区分两者。

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

11.1 的 MeshUpgrader 是二进制网格的原地升级;本节的 XMLConverter 是二进制 ↔ XML 的双向转换。两者都作为离线工具存在,不参与运行时加载。lab 复现扩展名分流、根元素二次分流与错误返回。

main:按源扩展名分流

main 解析出 opts.sourceExt 后,用一连串 else if 把输入导向三个转换函数之一;四个分支都不命中就记错误并把 retCode 置 1。这个分流决定了「文件长什么样就做什么转换」:

// Tools/XMLConverter/src/main.cpp:main 的分流(v14.6.3 源码摘录,已删减)
        if (opts.sourceExt == "mesh")
        {
            meshToXML(opts, meshSerializer);
        }
        else if (opts.sourceExt == "skeleton")
        {
            skeletonToXML(opts);
        }
        else if (opts.sourceExt == "xml")
        {
            XMLToBinary(opts, meshSerializer);
        }
        else
        {
            logMgr.logError("Unknown input type: " + opts.sourceExt);
            retCode = 1;
        }

meshToXML 把二进制网格读进 MeshManager 再用 XMLMeshSerializer 导出;skeletonToXML 同理走骨架序列化器,并且支持 optimiseAllAnimations(命令行开关)在导出前压掉无变化的动画轨:

// Tools/XMLConverter/src/main.cpp:meshToXML(v14.6.3 源码摘录,已删减)
    MeshPtr mesh = MeshManager::getSingleton().create("conversion", 
        ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
    

    meshSerializer.importMesh(stream, mesh.get());
   
    XMLMeshSerializer xmlMeshSerializer;
    xmlMeshSerializer.exportMesh(mesh.get(), opts.dest);

XMLToBinary:读根元素决定类型

XMLToBinary 先用 pugixml 读文档根元素,再 StringUtil::startsWith 按名字前缀分流:mesh 开头走网格分支(先 XMLMeshSerializer::importMesh、可选合并相邻 UV 与生成极端点,再 MeshSerializer::exportMesh);skeleton 开头走骨架分支(XMLSkeletonSerializer::importSkeleton、可选动画优化,再 SkeletonSerializer::exportSkeleton)。XMLConverterRepro::xmlToBinary 对未知根元素返回错误码,对应源码里 OGRE_EXCEPT 抛出后被上层捕获置 retCode 的路径:

// Tools/XMLConverter/src/main.cpp:XMLToBinary(v14.6.3 源码摘录,已删减)
    // Read root element and decide from there what type
    pugi::xml_document doc;
    auto result = doc.load_file(opts.source.c_str());
    if (!result)
    {
        OGRE_EXCEPT(Exception::ERR_INTERNAL_ERROR,
                    StringUtil::format("Unable to load '%s' - %s", opts.source.c_str(), result.description()));
    }
    pugi::xml_node root = doc.document_element();
    if (StringUtil::startsWith("mesh", root.name()))
    {
        MeshPtr newMesh = MeshManager::getSingleton().createManual("conversion", 
            ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);

        XMLMeshSerializer xmlMeshSerializer;
        xmlMeshSerializer.importMesh(opts.source, newMesh.get());

        if( opts.mergeTexcoordResult != opts.mergeTexcoordToDestroy )
        {
            newMesh->mergeAdjacentTexcoords( uint16(opts.mergeTexcoordResult), uint16(opts.mergeTexcoordToDestroy) );
        }

        if (opts.nuextremityPoints)
        {
            for (size_t i = 0; i < newMesh->getNumSubMeshes(); i++)
            {
                SubMesh* sm = newMesh->getSubMesh(i);
                sm->generateExtremes (opts.nuextremityPoints);
            }
        }

        meshSerializer.exportMesh(newMesh, opts.dest, opts.endian);
    }
    else if (StringUtil::startsWith("skeleton", root.name()))
    {
        SkeletonPtr newSkel = SkeletonManager::getSingleton().create("conversion", RGN_DEFAULT);

        XMLSkeletonSerializer xmlSkeletonSerializer;
        xmlSkeletonSerializer.importSkeleton(opts.source, newSkel.get());
        if (opts.optimiseAnimations)
        {
            newSkel->optimiseAllAnimations();
        }
        SkeletonSerializer skeletonSerializer;
        skeletonSerializer.exportSkeleton(newSkel.get(), opts.dest, SKELETON_VERSION_LATEST, opts.endian);
    }

源码定位

  • Tools/XMLConverter/src/main.cpp:meshToXML(263-281 行)
  • Tools/XMLConverter/src/main.cpp:XMLToBinary(283-331 行)
  • Tools/XMLConverter/src/main.cpp:skeletonToXML(333-349 行)
  • Tools/XMLConverter/src/main.cpp:main 分流(417-433 行)

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

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

XMLConverterRepro::sourceExt 复现扩展名推断,convert 复现四路分流,xmlToBinary 复现按根元素前缀 mesh/skeleton 分流并返回错误码(未知根元素返回 1,对应源码中 OGRE_EXCEPT 被 catch 后置 retCode = 1)。它与 src/11-2-xml-converter.cpp 逐字节一致:

// file: src/11-2-xml-converter.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/11-2-xml-converter.cpp -o bin/11-2-xml-converter && ./bin/11-2-xml-converter
//
// 复现 XMLConverter 的方向分流(Tools/XMLConverter/src/main.cpp 263-349 的
//   meshToXML/skeletonToXML/XMLToBinary 与 417-433 的 main 分流):按源文件
//   扩展名 mesh/skeleton/xml 选择转换方向;xml 输入再按根元素前缀
//   mesh/skeleton 走二进制导出;未知扩展名返回错误。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <string>

namespace ogre_repro {

// 对应 XMLConverter 的三个转换方向(瘦身版)
class XMLConverterRepro {
public:
    uint32_t meshExports = 0;       // mesh→xml 与 xml→mesh.bin 合计
    uint32_t skeletonExports = 0;   // skeleton→xml 与 xml→skeleton.bin 合计
    uint32_t optimiseAnimations = 0;
    std::string lastOp;
    std::string lastError;

    // 取源文件扩展名(对应 parseArgs 里 sourceExt 的推断)
    static std::string sourceExt(const std::string& source) {
        const size_t dot = source.find_last_of('.');
        return dot == std::string::npos ? std::string() : source.substr(dot + 1);
    }

    // 对应 main.cpp 263-281 的 meshToXML
    void meshToXML() {
        ++meshExports;
        lastOp = "mesh->xml";
    }

    // 对应 main.cpp 333-349 的 skeletonToXML(可附带 optimiseAllAnimations)
    void skeletonToXML(bool optimise) {
        ++skeletonExports;
        lastOp = "skeleton->xml";
        if (optimise)
            ++optimiseAnimations;
    }

    // 对应 main.cpp 283-331 的 XMLToBinary:读根元素决定类型
    int xmlToBinary(const std::string& rootName) {
        if (rootName.rfind("mesh", 0) == 0) {         // StringUtil::startsWith("mesh")
            ++meshExports;
            lastOp = "xml->mesh.bin";
            return 0;
        }
        if (rootName.rfind("skeleton", 0) == 0) {
            ++skeletonExports;
            lastOp = "xml->skeleton.bin";
            return 0;
        }
        lastError = "unknown root element";  // 对应源码 OGRE_EXCEPT 后被 catch
        return 1;
    }

    // 对应 main.cpp 417-433 的分流逻辑
    int convert(const std::string& source, const std::string& rootName, bool optimise = false) {
        const std::string ext = sourceExt(source);
        if (ext == "mesh") {
            meshToXML();
        } else if (ext == "skeleton") {
            skeletonToXML(optimise);
        } else if (ext == "xml") {
            return xmlToBinary(rootName);
        } else {
            lastError = "Unknown input type: " + ext;  // 对应 main.cpp 431 行
            return 1;
        }
        return 0;
    }
};

}  // namespace ogre_repro

int main() {
    using namespace ogre_repro;

    CHECK_EQ(XMLConverterRepro::sourceExt("model.mesh"), std::string("mesh"));
    CHECK_EQ(XMLConverterRepro::sourceExt("walk.skeleton"), std::string("skeleton"));
    CHECK_EQ(XMLConverterRepro::sourceExt("scene.xml"), std::string("xml"));
    CHECK_EQ(XMLConverterRepro::sourceExt("noext"), std::string());

    XMLConverterRepro c;
    CHECK_EQ(c.convert("model.mesh", ""), 0);          // mesh → xml
    CHECK_EQ(c.meshExports, 1u);
    CHECK(c.lastOp == "mesh->xml");

    CHECK_EQ(c.convert("walk.skeleton", "", true), 0); // skeleton → xml,附带动画优化
    CHECK_EQ(c.skeletonExports, 1u);
    CHECK_EQ(c.optimiseAnimations, 1u);
    CHECK(c.lastOp == "skeleton->xml");

    CHECK_EQ(c.convert("scene.xml", "mesh"), 0);       // xml 根元素 mesh → 二进制 mesh
    CHECK_EQ(c.meshExports, 2u);
    CHECK(c.lastOp == "xml->mesh.bin");

    CHECK_EQ(c.convert("scene.xml", "skeleton"), 0);   // xml 根元素 skeleton → 二进制 skeleton
    CHECK_EQ(c.skeletonExports, 2u);
    CHECK(c.lastOp == "xml->skeleton.bin");

    CHECK_EQ(c.convert("scene.xml", "unknown"), 1);    // 未知根元素报错
    CHECK(!c.lastError.empty());

    CHECK_EQ(c.convert("model.mdl", ""), 1);           // 未知扩展名
    CHECK(c.lastError == "Unknown input type: mdl");
    CHECK(c.lastOp == "xml->skeleton.bin");            // 失败不改变最后一次成功方向

    return lab::report("11.2 XML 转换器");
}

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

小结

  • 转换方向由源文件扩展名决定:mesh/skeleton/xml 三路,其余扩展名报 Unknown input type 并返回错误码 1。
  • meshToXML/skeletonToXML 用 XML 序列化器导出可读 XML;后者可附带动画优化。
  • XMLToBinary 读根元素前缀分流:mesh 前缀导出网格二进制,skeleton 前缀导出骨架二进制。
  • XML 二进制导出可选支持相邻 UV 合并、极端点生成与动画优化。
  • 转换失败不影响已记录的上一次成功方向,错误信息单独记录。

阅读导航:上一节:11.1 网格升级工具 · 下一节:11.3 Assimp 资源导入 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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