《OGRE 3D 渲染引擎原理与架构》11.1 Entity 与 SubEntity

Entity 是场景里可渲染对象的核心:它继承 MovableObject,内部持有 SubEntityList(vector<SubEntity*>),几何来自 Mesh 的各 SubMesh。Entity::setMaterialName 遍历 mSubEntityList 广播材质;SubEntity 继承 Renderable,可单独覆盖材质与可见性。lab 用 C++ 复现 Entity/SubEntity 的对象关系与材质广播。

11.1 Entity 与 SubEntity

第 7 章讲过 Mesh/SubMesh 是几何数据;本节讲把它放进场景去渲染的对象。Entity 是 OGRE 最常用的 MovableObject 子类:它引用一个 Mesh,并把每个 SubMesh 转成一个可独立控制的 SubEntity。

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

第 7 章讲内存里的几何结构,本节讲「几何 → 可渲染对象」的这层封装。helio 的实体/组件讲自研引擎的组织方式,本系列聚焦 OGRE 里 MovableObject 细分与对象关系。

Entity 持有 SubEntityList

OgreEntity.h 里,Entity 把子实体放在一个 std::vector<SubEntity*> 里:

// OgreMain/include/OgreEntity.h:SubEntityList(v14.6.3 源码摘录,已删减)
        typedef std::vector<SubEntity*> SubEntityList;
        ...
        SubEntityList mSubEntityList;

getSubEntity(size_t) 直接索引访问,getNumSubEntities() 返回数量:

// OgreMain/include/OgreEntity.h:访问器(v14.6.3 源码摘录,已删减)
        SubEntity* getSubEntity(size_t index) const { return mSubEntityList.at(index); }
        ...
        size_t getNumSubEntities(void) const { return mSubEntityList.size(); }

关键点:Entity 本身不持有几何,也不持有材质——它把渲染职责全部委托给 SubEntity,自己只是「Mesh 的一个实例化入口」。

setMaterialName:广播到所有子实体

Entity::setMaterialName 的实现是一个简单的遍历:

// OgreMain/src/OgreEntity.cpp:Entity::setMaterialName(v14.6.3 源码摘录,已删减)
    void Entity::setMaterialName( const String& name, const String& groupName /* = ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME */)
    {
        // Set for all subentities
        for (auto *s : mSubEntityList)
        {
            s->setMaterialName(name, groupName);
        }

    }

注释已经说明了用法:这是「给所有子实体设同一个材质」的快捷方式;如果一个 Mesh 有多个 SubMesh 要各自不同材质,就该拿 getSubEntity() 逐个设置。这是 Entity/SubEntity 两级结构存在的根本原因:一个对象整体可以统一换材质,也可以精细到某个子部件。

SubEntity:Renderable + 父指针 + SubMesh

OgreSubEntity.h 里,SubEntity 直接继承 Renderable(可渲染接口):

// OgreMain/include/OgreSubEntity.h:SubEntity 类(v14.6.3 源码摘录,已删减)
    class _OgreExport SubEntity: public Renderable, public SubEntityAlloc
    {
        // Note no virtual functions for efficiency
        friend class Entity;
        friend class SceneManager;
    private:
        ...
        /// Pointer to parent.
        Entity* mParentEntity;

        /// Cached pointer to material.
        MaterialPtr mMaterialPtr;

        /// Pointer to the SubMesh defining geometry.
        SubMesh* mSubMesh;

三个关键字段:

  • mParentEntity:指向所属的 Entity,供反查;
  • mMaterialPtr:缓存的材质指针——setMaterialName 变更的就是它;
  • mSubMesh:决定几何来源的 SubMesh。

SubEntity 自己的 setMaterialName 与父级解耦,默认材质来自 SubMesh:

// OgreMain/include/OgreSubEntity.h:材质与父指针(v14.6.3 源码摘录,已删减)
        void setMaterialName( const String& name, const String& groupName = ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME );

        /** Tells this SubEntity whether to be visible or not. */
        void setVisible(bool visible);

        /** Returns whether or not this SubEntity is supposed to be visible. */
        bool isVisible(void) const { return mVisible; }
        ...
        /** Accessor to get parent Entity */
        Entity* getParent(void) const { return mParentEntity; }

对象关系小结

Mesh ──由──> 多个 SubMesh(几何 + 默认材质名)
Entity(MovableObject)─┬─ 持有 ──> SubEntityList = vector<SubEntity*>
                        └─ 每个 SubEntity ──> Renderable
                                               ├─ mParentEntity
                                               ├─ mMaterialPtr(可独立覆盖)
                                               └─ mSubMesh(几何来源)

Entity::setMaterialName 是「宽泛广播」,SubEntity::setMaterialName 是「精细覆盖」;渲染时各 SubEntity 用各自的 Renderable 提交绘制,所以一个多部件模型可以拆成多个 draw call、各自独立换材质和隐藏。

同一 Mesh 对应多份场景实例

Mesh 和 SubMesh 负责资源数据,Entity 和 SubEntity 负责实例中的对象状态及材质选择。销毁 Entity 后,是否可卸载 Mesh 还取决于其他实例和资源引用。

原生样例用左右两个节点确认位置独立且 getMesh 指向同一资源。用队列与像素同时核查实例级状态,避免把资源是否已加载当作对象是否绘制。

源码定位

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

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

下面复现 Entity/SubEntity 的对象关系与材质广播。它与 src/11-1-entity-subentity.cpp 逐字节一致:

// file: src/11-1-entity-subentity.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/11-1-entity-subentity.cpp -o bin/11-1-entity-subentity && ./bin/11-1-entity-subentity
//
// 复现 Entity / SubEntity 的对象关系:
//   Entity 持有 SubEntityList(vector<SubEntity*>,对应 OgreEntity.h typedef);
//   Entity::setMaterialName 广播到所有 SubEntity(对应 OgreEntity.cpp 遍历 mSubEntityList);
//   SubEntity 可单独 setMaterialName 覆盖(对应 OgreSubEntity.h 的 setMaterialName);
//   SubEntity 默认继承 SubMesh 的默认材质。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <string>
#include <vector>

namespace ogre_repro {

struct SubMesh {
  std::string name;
  std::string defaultMaterialName;
};

// 对应 Ogre::SubEntity:Renderable + mParentEntity + mSubMesh + 独立材质
class SubEntity {
 public:
  SubEntity(class Entity* parent, const SubMesh* subMeshBasis)
      : mParentEntity(parent), mSubMesh(subMeshBasis),
        mMaterialName(subMeshBasis->defaultMaterialName), mVisible(true) {}

  // 对应 SubEntity::setMaterialName:本实例覆盖材质
  void setMaterialName(const std::string& name) { mMaterialName = name; }
  const std::string& getMaterialName() const { return mMaterialName; }
  bool isDefaultMaterial() const { return mMaterialName == mSubMesh->defaultMaterialName; }

  // 对应 SubEntity::setVisible / isVisible
  void setVisible(bool visible) { mVisible = visible; }
  bool isVisible() const { return mVisible; }

  // 对应 SubEntity::getParent
  class Entity* getParent() const { return mParentEntity; }

 private:
  class Entity* mParentEntity;
  const SubMesh* mSubMesh;
  std::string mMaterialName;
  bool mVisible;
};

// 对应 Ogre::Entity:SubEntityList = vector<SubEntity*>,几何来自 Mesh 的 SubMesh 列表
class Entity {
 public:
  // 对应 OgreEntity.h 的 SubEntityList typedef
  typedef std::vector<SubEntity*> SubEntityList;

  Entity(const std::string& name, const std::vector<SubMesh>& submeshes)
      : mName(name) {
    for (const SubMesh& sm : submeshes)
      mSubEntityList.push_back(new SubEntity(this, &sm));
  }
  ~Entity() {
    for (SubEntity* s : mSubEntityList) delete s;
  }

  // 对应 Entity::getNumSubEntities / getSubEntity
  size_t getNumSubEntities() const { return mSubEntityList.size(); }
  SubEntity* getSubEntity(size_t index) const { return mSubEntityList.at(index); }

  // 对应 Entity::setMaterialName:广播到所有 SubEntity
  void setMaterialName(const std::string& name) {
    for (SubEntity* s : mSubEntityList) s->setMaterialName(name);
  }
  bool allUseMaterial(const std::string& name) const {
    for (const SubEntity* s : mSubEntityList)
      if (s->getMaterialName() != name) return false;
    return true;
  }

  const std::string& getName() const { return mName; }

 private:
  std::string mName;
  SubEntityList mSubEntityList;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 一个 Mesh 有三个 SubMesh:身体、头、武器
  std::vector<SubMesh> parts = {
      {"Body", "Materials/RobotBody"},
      {"Head", "Materials/RobotHead"},
      {"Weapon", "Materials/RobotWeapon"}};
  Entity robot("Robot", parts);

  CHECK(robot.getNumSubEntities() == 3);
  CHECK(robot.getSubEntity(0)->getMaterialName() == "Materials/RobotBody");
  CHECK(robot.getSubEntity(2)->getParent() == &robot);

  // 默认各 SubEntity 用自己的 SubMesh 材质
  CHECK(robot.getSubEntity(1)->isDefaultMaterial());

  // setMaterialName 广播:三个子实体全部换成同一材质
  robot.setMaterialName("Materials/RobotCloak");
  CHECK(robot.allUseMaterial("Materials/RobotCloak"));
  CHECK(!robot.getSubEntity(0)->isDefaultMaterial());

  // 单独覆盖:只改头部
  robot.getSubEntity(1)->setMaterialName("Materials/RobotHeadGolden");
  CHECK(robot.getSubEntity(1)->getMaterialName() == "Materials/RobotHeadGolden");
  CHECK(robot.getSubEntity(0)->getMaterialName() == "Materials/RobotCloak");

  // 可见性:单独隐藏武器
  robot.getSubEntity(2)->setVisible(false);
  CHECK(!robot.getSubEntity(2)->isVisible());
  CHECK(robot.getSubEntity(0)->isVisible());

  return lab::report("11-1 渲染对象体系:Entity 与 SubEntity");
}

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

小结

  • Entity 持有 SubEntityList(vector<SubEntity*>),每个 SubMesh 对应一个 SubEntity。
  • Entity::setMaterialName 遍历广播;精细控制用 getSubEntity(i)->setMaterialName。
  • SubEntity 继承 Renderable,持有父指针、缓存材质、SubMesh 几何来源。
  • 两级结构支持「整体统一换材质」与「部件级独立材质/可见性」两种粒度。

阅读导航:上一节:10.3 反序列化与加载流程 · 下一节:11.2 Light 类型与光照参数 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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