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 资源导入 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。