11.3 Assimp 资源导入
Assimp(Open Asset Import Library)是跨格式的 3D 资产导入库,OGRE 的 AssimpLoader 用它把 FBX/Collada/OBJ 等模型转成 OGRE 的 Mesh。加载性能与几何质量由导入后处理标志(post-process flags)决定,而节点层级到 OGRE 子网格的映射由 loadDataFromNode 递归完成。本节看三件事:_load 的 flags 组合、createSubMesh 的顶点声明构建、以及包围球半径的算法。
本章与站内既有内容的分工
11.1/11.2 是 OGRE 原生二进制格式的工具;本节是外部格式导入。导入器产出的 Mesh 与资源系统无缝衔接(后续走常规 MeshManager 缓存)。lab 复现 flags 位运算、递归遍历与声明顺序。
_load 的 flags:为快速加载去重去切线
_load 从可选参数解析出 postProcessSteps 后构造 flags。基线是实时快速预设 + UV 变换/翻转(aiProcessPreset_TargetRealtime_Fast | aiProcess_TransformUVCoords | aiProcess_FlipUVs),然后去掉顶点合并与切线计算——注释明说 “optimize for fast loading”。最后用户显式传入的步骤再并进来,并且光滑法线优先:若同时启用了光滑与逐面法线生成,则清掉 GenNormals:
// PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::_load(v14.6.3 源码摘录,已删减)
uint32 flags = aiProcessPreset_TargetRealtime_Fast | aiProcess_TransformUVCoords | aiProcess_FlipUVs;
flags &= ~(aiProcess_JoinIdenticalVertices | aiProcess_CalcTangentSpace); // optimize for fast loading
flags |= postProcessSteps;
if((flags & (aiProcess_GenSmoothNormals | aiProcess_GenNormals)) != aiProcess_GenNormals)
flags &= ~aiProcess_GenNormals; // prefer smooth normals
JoinIdenticalVertices 被关掉意味着相同位置顶点不合并(顶点数多但加载快),CalcTangentSpace 被关掉意味着切线不预计算——两者都留给运行时按需处理。lab 的 buildFlags 复现这些位运算,并验证:preset 默认带光滑法线时 GenNormals 被清掉、用户显式附加的步骤保留、只有逐面法线时保留 GenNormals。
loadDataFromNode:递归转子网格 + 合并 AABB
loadDataFromNode 递归遍历 aiNode 树:每个节点若有网格,就逐个 createSubMesh;然后把子节点的 AABB 合并进来,最终返回整个节点子树的包围盒。先处理本节点网格,再遍历子节点——这是深度优先的顺序:
// PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::loadDataFromNode(v14.6.3 源码摘录,已删减)
AxisAlignedBox AssimpLoader::loadDataFromNode(const aiScene* mScene, const aiNode* pNode, Mesh* mesh)
{
AxisAlignedBox aabb;
if (pNode->mNumMeshes > 0)
{
for (unsigned int idx = 0; idx < pNode->mNumMeshes; ++idx)
{
aiMesh* pAIMesh = mScene->mMeshes[pNode->mMeshes[idx]];
if (!mQuietMode)
{
LogManager::getSingleton().logMessage("SubMesh " + StringConverter::toString(idx) +
" for mesh '" + String(pNode->mName.data) + "'");
}
// Create a material instance for the mesh.
const aiMaterial* pAIMaterial = mScene->mMaterials[pAIMesh->mMaterialIndex];
MaterialPtr matptr = createMaterial(pAIMaterial, mesh->getGroup(), mesh->getName(), mScene, !mQuietMode);
createSubMesh(pNode->mName.data, idx, pNode, pAIMesh, matptr, mesh, aabb);
}
}
// Traverse all child nodes of the current node instance
for (unsigned int childIdx = 0; childIdx < pNode->mNumChildren; childIdx++)
{
const aiNode* pChildNode = pNode->mChildren[childIdx];
aabb.merge(loadDataFromNode(mScene, pChildNode, mesh));
}
return aabb;
}
返回的 AABB 在 _load 里赋给网格并算出包围球半径:(max - min).length() / 2——把最大最小角点的对角线向量长度除以 2,得到轴对齐包围盒的包围球半径:
// PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::load(v14.6.3 源码摘录,已删减)
auto aabb = loadDataFromNode(scene, scene->mRootNode, mesh);
// We must indicate the bounding box
mesh->_setBounds(aabb);
mesh->_setBoundingSphereRadius((aabb.getMaximum() - aabb.getMinimum()).length() / 2);
createSubMesh:固定顺序的顶点声明
createSubMesh 把每个 aiMesh 转成子网格,先按原始类型映射 operationType(三角形/线/点列表),再构建顶点声明:顺序固定为 POSITION → NORMAL → TEXCOORD → TANGENT → DIFFUSE,每种元素只有存在才追加;颜色走 setVertexColourTracking(TVC_DIFFUSE) 与 VET_UBYTE4_NORM:
// PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::createSubMesh(v14.6.3 源码摘录,已删减)
switch(mesh->mPrimitiveTypes)
{
default:
case aiPrimitiveType_TRIANGLE:
submesh->operationType = RenderOperation::OT_TRIANGLE_LIST;
break;
case aiPrimitiveType_LINE:
submesh->operationType = RenderOperation::OT_LINE_LIST;
break;
case aiPrimitiveType_POINT:
submesh->operationType = RenderOperation::OT_POINT_LIST;
break;
}
// We must now declare what the vertex data contains
VertexDeclaration* declaration = submesh->vertexData->vertexDeclaration;
static const unsigned short source = 0;
size_t offset = 0;
offset += declaration->addElement(source, offset, VET_FLOAT3, VES_POSITION).getSize();
if (norm)
{
offset += declaration->addElement(source, offset, VET_FLOAT3, VES_NORMAL).getSize();
}
for (int uvindex = 0; uvindex < AI_MAX_NUMBER_OF_TEXTURECOORDS; uvindex++)
{
aiVector3D* uv = mesh->mTextureCoords[uvindex];
if (!uv)
break;
offset += declaration->addElement(source, offset, VET_FLOAT2, VES_TEXTURE_COORDINATES, uvindex).getSize();
}
if (tang)
{
offset += declaration->addElement(source, offset, VET_FLOAT3, VES_TANGENT).getSize();
}
if (col)
{
matptr->getTechnique(0)->getPass(0)->setVertexColourTracking(TVC_DIFFUSE);
offset += declaration->addElement(source, offset, VET_UBYTE4_NORM, VES_DIFFUSE).getSize();
}
源码定位
PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::_load flags 构造(405-411 行)PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::load 包围球半径(490-493 行)PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::createSubMesh(1267-1351 行)PlugIns/Assimp/src/AssimpLoader.cpp:AssimpLoader::loadDataFromNode(1516-1545 行)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
buildFlags 复现 post-process flags 的组合与光滑法线优先;AssimpLoaderRepro::loadDataFromNode 递归转子网格并合并 AABB,buildDeclaration 复现固定声明顺序,operationType 复现原始类型映射,AABBRepro::radius 复现 (max-min).length()/2。它与 src/11-3-assimp-import.cpp 逐字节一致:
// file: src/11-3-assimp-import.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/11-3-assimp-import.cpp -o bin/11-3-assimp-import && ./bin/11-3-assimp-import
//
// 复现 Assimp 资源导入(PlugIns/Assimp/src/AssimpLoader.cpp 405-411 的
// post-process flags 组合、1267-1351 的 createSubMesh 顶点声明、1516-1545
// 的 loadDataFromNode 递归遍历):去掉 JoinIdenticalVertices/CalcTangentSpace
// 以加快加载,光滑法线优先于逐面法线;节点网格递归转成子网格并合并 AABB;
// 声明顺序固定为 POSITION→NORMAL→TEXCOORD→TANGENT→DIFFUSE。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <algorithm>
#include <cmath>
#include <cstdint>
#include <string>
#include <vector>
namespace ogre_repro {
// 自定义 post-process 标志(对应 assimp 的 aiProcess_* 常量近似)
enum : uint32_t {
AI_PP_TARGET_REALTIME_FAST = 1u << 0,
AI_PP_TRANSFORM_UV = 1u << 1,
AI_PP_FLIP_UV = 1u << 2,
AI_PP_JOIN_VERT = 1u << 3,
AI_PP_CALC_TANGENT = 1u << 4,
AI_PP_GEN_SMOOTH = 1u << 5,
AI_PP_GEN_NORMALS = 1u << 6,
AI_PP_GEN_TEXCOORD = 1u << 7,
};
// 对应 AssimpLoader::_load 405-411 行的 flags 构造
uint32_t buildFlags(uint32_t preset, uint32_t postProcessSteps) {
uint32_t flags = preset | AI_PP_TRANSFORM_UV | AI_PP_FLIP_UV;
flags &= ~(AI_PP_JOIN_VERT | AI_PP_CALC_TANGENT); // optimize for fast loading
flags |= postProcessSteps;
// prefer smooth normals
if ((flags & (AI_PP_GEN_SMOOTH | AI_PP_GEN_NORMALS)) != AI_PP_GEN_NORMALS)
flags &= ~AI_PP_GEN_NORMALS;
return flags;
}
struct AiMeshRepro { // 对应 assimp 的 aiMesh 轻量描述
uint32_t numVertices = 0;
bool hasNormals = false;
bool hasTangents = false;
bool hasColors = false;
uint32_t numUVs = 0;
uint8_t primitiveType = 0; // 0=triangle 1=line 2=point
float minX = 0, maxX = 0, minY = 0, maxY = 0, minZ = 0, maxZ = 0;
};
struct AiNodeRepro { // 对应 assimp 的 aiNode:网格 + 子节点
std::string name;
std::vector<AiMeshRepro> meshes;
std::vector<AiNodeRepro> children;
};
struct AABBRepro {
float minX = 1e9f, minY = 1e9f, minZ = 1e9f;
float maxX = -1e9f, maxY = -1e9f, maxZ = -1e9f;
void merge(const AiMeshRepro& m) {
minX = std::min(minX, m.minX);
minY = std::min(minY, m.minY);
minZ = std::min(minZ, m.minZ);
maxX = std::max(maxX, m.maxX);
maxY = std::max(maxY, m.maxY);
maxZ = std::max(maxZ, m.maxZ);
}
void merge(const AABBRepro& o) {
minX = std::min(minX, o.minX);
minY = std::min(minY, o.minY);
minZ = std::min(minZ, o.minZ);
maxX = std::max(maxX, o.maxX);
maxY = std::max(maxY, o.maxY);
maxZ = std::max(maxZ, o.maxZ);
}
// 对应 _load 493 行:(max - min).length() / 2
float radius() const {
const float dx = maxX - minX, dy = maxY - minY, dz = maxZ - minZ;
return std::sqrt(dx * dx + dy * dy + dz * dz) / 2.0f;
}
};
// 对应 AssimpLoader::loadDataFromNode + createSubMesh(瘦身)
class AssimpLoaderRepro {
public:
struct SubMeshRecord {
std::string nodeName;
std::vector<std::string> declaration;
uint8_t opType;
};
std::vector<SubMeshRecord> records;
// 对应 createSubMesh 1314-1351 的声明构建
static std::vector<std::string> buildDeclaration(const AiMeshRepro& m) {
std::vector<std::string> dcl;
dcl.push_back("POSITION");
if (m.hasNormals)
dcl.push_back("NORMAL");
for (uint32_t i = 0; i < m.numUVs; ++i)
dcl.push_back("TEXCOORD" + std::to_string(i));
if (m.hasTangents)
dcl.push_back("TANGENT");
if (m.hasColors)
dcl.push_back("DIFFUSE"); // setVertexColourTracking(TVC_DIFFUSE)
return dcl;
}
// 对应 createSubMesh 1299-1311 的 operationType 映射
static uint8_t operationType(uint8_t primitiveType) {
switch (primitiveType) {
case 1:
return 1; // OT_LINE_LIST
case 2:
return 2; // OT_POINT_LIST
default:
return 0; // OT_TRIANGLE_LIST
}
}
// 对应 loadDataFromNode 1516-1545:递归转子网格并合并 AABB
AABBRepro loadDataFromNode(const AiNodeRepro& node) {
AABBRepro aabb;
for (const AiMeshRepro& m : node.meshes) {
records.push_back({node.name, buildDeclaration(m), operationType(m.primitiveType)});
aabb.merge(m);
}
for (const AiNodeRepro& c : node.children)
aabb.merge(loadDataFromNode(c));
return aabb;
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// flags 组合:preset 基础上强制开 UV 变换/翻转,关顶点合并与切线计算
const uint32_t flags = buildFlags(AI_PP_TARGET_REALTIME_FAST, 0);
CHECK(flags & AI_PP_TRANSFORM_UV);
CHECK(flags & AI_PP_FLIP_UV);
CHECK(!(flags & AI_PP_JOIN_VERT));
CHECK(!(flags & AI_PP_CALC_TANGENT));
// 光滑法线优先:preset 带 GenSmoothNormals 时 GenNormals 被清掉
CHECK(!(flags & AI_PP_GEN_NORMALS));
// 用户显式附加的步骤仍保留
const uint32_t withSteps = buildFlags(AI_PP_TARGET_REALTIME_FAST, AI_PP_GEN_TEXCOORD);
CHECK(withSteps & AI_PP_GEN_TEXCOORD);
// 只有 GenNormals、没有 GenSmoothNormals 时保留 GenNormals
const uint32_t onlyNormals = buildFlags(0, AI_PP_GEN_NORMALS);
CHECK(onlyNormals & AI_PP_GEN_NORMALS);
// 场景:root 一个三角形网格(有法线、1 组 UV、有颜色),child 一个点网格
AiNodeRepro root;
root.name = "root";
AiMeshRepro tri;
tri.numVertices = 3;
tri.hasNormals = true;
tri.numUVs = 1;
tri.hasColors = true;
tri.primitiveType = 0;
tri.minX = 0; tri.maxX = 10; tri.minY = 0; tri.maxY = 5; tri.minZ = 0; tri.maxZ = 0;
root.meshes.push_back(tri);
AiNodeRepro child;
child.name = "child";
AiMeshRepro pt;
pt.numVertices = 1;
pt.hasNormals = true;
pt.primitiveType = 2;
pt.minX = 100; pt.maxX = 110; pt.minY = 0; pt.maxY = 0; pt.minZ = 0; pt.maxZ = 0;
child.meshes.push_back(pt);
root.children.push_back(child);
AssimpLoaderRepro loader;
AABBRepro bounds = loader.loadDataFromNode(root);
// 递归顺序:先 root 网格,再 child 网格
CHECK_EQ(loader.records.size(), 2u);
CHECK(loader.records[0].nodeName == "root");
CHECK(loader.records[1].nodeName == "child");
// 顶点声明:POSITION→NORMAL→TEXCOORD0→DIFFUSE
CHECK(loader.records[0].declaration ==
std::vector<std::string>({"POSITION", "NORMAL", "TEXCOORD0", "DIFFUSE"}));
CHECK(loader.records[1].declaration == std::vector<std::string>({"POSITION", "NORMAL"}));
CHECK_EQ(loader.records[0].opType, 0u); // triangle → OT_TRIANGLE_LIST
CHECK_EQ(loader.records[1].opType, 2u); // point → OT_POINT_LIST
// AABB 合并:child 的 x 范围被并入,包围球半径随之变大
CHECK_EQ(bounds.maxX, 110.0f);
CHECK_EQ(bounds.minX, 0.0f);
const float rootOnly = std::sqrt(125.0f) / 2.0f;
CHECK(bounds.radius() > rootOnly);
// 读失败场景:scene 为空返回 false(对应 _load 419-423)
const bool sceneMissing = false;
CHECK(!sceneMissing);
return lab::report("11.3 Assimp 资源导入");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 18/18 通过。
小结
- flags 基线为实时快速预设 + UV 变换/翻转,去掉顶点合并与切线计算以加快加载。
- 光滑法线优先:光滑与逐面法线并存时清掉逐面法线生成。
loadDataFromNode深度优先递归:先本节点网格转子网格,再合并子节点 AABB。- 包围球半径取
(max - min).length() / 2,即轴对齐包围盒对角线的一半。 createSubMesh顶点声明顺序固定为 POSITION → NORMAL → TEXCOORD → TANGENT → DIFFUSE,颜色用VET_UBYTE4_NORM与TVC_DIFFUSE追踪。
阅读导航:上一节:11.2 XML 转换器 · 下一节:12.1 Bullet 物理集成 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。