《OGRE 3D 渲染引擎原理与架构》11.3 Assimp 资源导入

11.3 讲 Assimp 导入插件。_load 的 flags 用实时快速预设加 UV 变换/翻转,去掉顶点合并与切线计算加快加载,光滑法线优先;loadDataFromNode 递归转子网格并合并 AABB;声明顺序 POSITION→NORMAL→TEXCOORD→TANGENT→DIFFUSE。lab 复现 flags、递归与声明,18 项断言。

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 物理集成 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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