《OGRE 3D 渲染引擎原理与架构》15.1 场景装配

场景装配从 Root::createSceneManager 开始:SceneManagerEnumerator 按类型名登记工厂(默认 DefaultSceneManager),createSceneManager 查重名实例、按类型找工厂、空名自动编号;SceneManager 再按名登记场景节点与相机。源码在 OgreMain/ 的 OgreRoot.cpp、OgreSceneManagerEnumerator.cpp 与 OgreSceneManager.cpp。lab 复现工厂登记、实例创建与命名冲突。

15.1 场景装配

卷三走到最后一章:把前面各章(相机、视口、查询、天空、雾、粒子、RTSS……)组装成一个能渲染的场景。入口是 Root::createSceneManager——它经过 SceneManagerEnumerator 的工厂注册表,生产出场景管理器;场景管理器再按名登记场景节点、相机、实体。这一节讲这棵「工厂 → 实例 → 命名登记」的装配树。

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

helio 四卷讲过场景图从零实现;本卷 1-3 章讲相机、视口、查询等单个子系统。15 章是把它们接起来的装配与一帧调度:15.1 讲管理器怎么造出来,15.2 讲相机/视口/渲染目标三元组,15.3 讲完整一帧怎么推进。SceneManagerEnumerator 的工厂模式与 13.1 的 Overlay 元素工厂、14.1 的子渲染状态工厂一脉相承。

Root 的委托:createSceneManager

Root::createSceneManager 本身很薄——它把活全部委托给枚举器:

// OgreMain/src/OgreRoot.cpp:Root::createSceneManager(v14.6.3 源码摘录,已删减)
    SceneManager* Root::createSceneManager(const String& typeName, const String& instanceName)
    {
        return mSceneManagerEnum->createSceneManager(typeName, instanceName);
    }

类型选择用类型名字符串(如 SMT_DEFAULT 即 "DefaultSceneManager")。注意这与旧版的 ST_GENERIC 场景类型枚举不是一回事——后者在 OgreDeprecated.h 中标记为弃用,工厂选型走的是「按类型名查工厂表」。

SceneManagerEnumerator:工厂注册与实例创建

SceneManagerEnumerator 持有两张表:mFactories(类型名 → 工厂)与 mInstances(实例名 → 场景管理器)。构造时默认登记 DefaultSceneManager 工厂:

// OgreMain/src/OgreSceneManagerEnumerator.cpp:SceneManagerEnumerator::SceneManagerEnumerator / addFactory(v14.6.3 源码摘录,已删减)
    SceneManagerEnumerator::SceneManagerEnumerator()
        : mInstanceCreateCount(0), mCurrentRenderSystem(0)
    {
        addFactory(&mDefaultFactory);

    }
    //-----------------------------------------------------------------------
    void SceneManagerEnumerator::addFactory(SceneManagerFactory* fact)
    {
        mFactories[fact->getTypeName()] = fact;
        // add to metadata
        mMetaDataList.push_back(fact->getTypeName());
        // Log
        LogManager::getSingleton().logMessage("SceneManagerFactory for type '" + fact->getTypeName() + "' registered.");
    }

第三方场景管理器(Octree、Portal、Paging)以插件形式 addFactory 进来,随后就能用各自的类型名创建。

createSceneManager 是装配的核心,四条规则:

// OgreMain/src/OgreSceneManagerEnumerator.cpp:SceneManagerEnumerator::createSceneManager(v14.6.3 源码摘录,已删减)
    SceneManager* SceneManagerEnumerator::createSceneManager(
        const String& typeName, const String& instanceName)
    {
        if (mInstances.find(instanceName) != mInstances.end())
        {
            OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM, 
                "SceneManager instance called '" + instanceName + "' already exists",
                "SceneManagerEnumerator::createSceneManager");
        }

        auto it = mFactories.find(typeName);

        if (it == mFactories.end())
        {
            OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, "No factory found for scene manager of type '" + typeName + "'");
        }

        SceneManager* inst = 0;
        if (instanceName.empty())
        {
            // generate a name
            StringStream s;
            s << "SceneManagerInstance" << ++mInstanceCreateCount;
            inst = it->second->createInstance(s.str());
        }
        else
        {
            inst = it->second->createInstance(instanceName);
        }

        /// assign rs if already configured
        if (mCurrentRenderSystem)
            inst->_setDestinationRenderSystem(mCurrentRenderSystem);

        mInstances[inst->getName()] = inst;
        
        return inst;
        

    }
  • 实例名查重:同名实例已存在 → 抛 ERR_DUPLICATE_ITEM。
  • 类型查工厂:类型名没有对应工厂 → 抛 ERR_ITEM_NOT_FOUND。
  • 空名自动编号:不传名字就用 SceneManagerInstanceN(计数递增)。
  • 登记:创建后按实例名记入 mInstances,getSceneManager(name) 可查。

SceneManager:命名登记场景节点与相机

场景管理器默认就具备创建与登记能力。createSceneNode 先查重名再登记,createCamera 同样:

// OgreMain/src/OgreSceneManager.cpp:SceneManager::createSceneNode(v14.6.3 源码摘录,已删减)
SceneNode* SceneManager::createSceneNode(const String& name)
{
    // Check name not used
    if (hasSceneNode(name))
    {
        OGRE_EXCEPT(
            Exception::ERR_DUPLICATE_ITEM,
            "A scene node with the name " + name + " already exists",
            "SceneManager::createSceneNode" );
    }

    SceneNode* sn = createSceneNodeImpl(name);
    mSceneNodes.push_back(sn);
    mNamedNodes[name] = sn;
    sn->mGlobalIndex = mSceneNodes.size() - 1;
    return sn;
}
// OgreMain/src/OgreSceneManager.cpp:SceneManager::createCamera(v14.6.3 源码摘录,已删减)
Camera* SceneManager::createCamera(const String& name)
{
    // Check name not used
    if (mCameras.find(name) != mCameras.end())
    {
        OGRE_EXCEPT(
            Exception::ERR_DUPLICATE_ITEM,
            "A camera with the name " + name + " already exists",
            "SceneManager::createCamera" );
    }

    Camera *c = OGRE_NEW Camera(name, this);
    mCameras.emplace(name, c);

    // create visible bounds aab map entry
    mCamVisibleObjectsMap[c] = VisibleObjectsBoundsInfo();

    return c;
}

命名是全局约定:实体、光源、动画状态也按名登记。命名查重贯穿整个场景装配——这是「按名查找」API(getSceneNode、getCamera、hasEntity)可靠性的来源。注意 createSceneNode 把新节点同时推进 mSceneNodes 并分配全局索引,而相机额外建立可见包围盒登记项。

源码定位

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

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

下面用纯 C++ 复现场景装配:枚举器的工厂登记与实例创建、空名自动编号、重复实例名/未知类型拒绝、SceneManager 按名登记节点与相机及重名冲突。它与 src/15-1-scene-assembly.cpp 逐字节一致:

// file: src/15-1-scene-assembly.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/15-1-scene-assembly.cpp -o bin/15-1-scene-assembly && ./bin/15-1-scene-assembly
//
// 复现 Root -> SceneManager 的工厂装配(对应 OgreMain/src/OgreRoot.cpp
// 540-543 的 Root::createSceneManager、OgreMain/src/OgreSceneManagerEnumerator.cpp
// 46-51、74-147 的 addFactory / createSceneManager,以及
// OgreMain/src/OgreSceneManager.cpp 168-186、517-541 的 createCamera / createSceneNode):
//   SceneManagerEnumerator 按类型名登记工厂,默认登记 DefaultSceneManager;
//   createSceneManager:查重名实例、按类型找工厂、空名自动编号、按实例名登记;
//   SceneManager 默认能力:createSceneNode 按名登记、createCamera 按名登记;
//   场景类型选择通过类型名(如 SMT_DEFAULT)而非已废弃的 ST_GENERIC 掩码。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <map>
#include <sstream>
#include <stdexcept>
#include <string>
#include <vector>

namespace ogre_repro {

// 对应 OgreSceneManager.h 3452:SMT_DEFAULT。
static const char* SMT_DEFAULT = "DefaultSceneManager";

// 对应 OgreSceneManager 极简形式:名字 + 命名节点/相机登记。
class SceneManager {
 public:
  explicit SceneManager(const std::string& name) : mName(name) {}

  // 对应 SceneManager::createSceneNode(OgreSceneManager.cpp 525-541)。
  void createSceneNode(const std::string& name) {
    if (mNamedNodes.find(name) != mNamedNodes.end())
      throw std::runtime_error("A scene node with the name " + name + " already exists");
    mNamedNodes[name] = new SceneNode(name);
    ++mNodeCount;
  }

  // 对应 SceneManager::createCamera(OgreSceneManager.cpp 168-186)。
  void createCamera(const std::string& name) {
    if (mCameras.find(name) != mCameras.end())
      throw std::runtime_error("A camera with the name " + name + " already exists");
    mCameras[name] = new Camera(name);
  }

  bool hasSceneNode(const std::string& name) const { return mNamedNodes.find(name) != mNamedNodes.end(); }
  bool hasCamera(const std::string& name) const { return mCameras.find(name) != mCameras.end(); }
  size_t nodeCount() const { return mNamedNodes.size(); }
  const std::string& getName() const { return mName; }

 private:
  struct SceneNode {
    explicit SceneNode(const std::string& n) : name(n) {}
    std::string name;
  };
  struct Camera {
    explicit Camera(const std::string& n) : name(n) {}
    std::string name;
  };
  std::string mName;
  std::map<std::string, SceneNode*> mNamedNodes;
  std::map<std::string, Camera*> mCameras;
  size_t mNodeCount = 0;
};

// 对应 SceneManagerFactory(OgreSceneManagerEnumerator.h 46-53)。
class SceneManagerFactory {
 public:
  virtual ~SceneManagerFactory() {}
  virtual const std::string& getTypeName() const = 0;
  virtual SceneManager* createInstance(const std::string& name) = 0;
};

class DefaultSceneManagerFactory : public SceneManagerFactory {
 public:
  const std::string& getTypeName() const override { return msTypeName; }
  SceneManager* createInstance(const std::string& name) override { return new SceneManager(name); }
  static std::string msTypeName;
};
std::string DefaultSceneManagerFactory::msTypeName = SMT_DEFAULT;

class OctreeSceneManagerFactory : public SceneManagerFactory {
 public:
  const std::string& getTypeName() const override { return msTypeName; }
  SceneManager* createInstance(const std::string& name) override { return new SceneManager(name); }
  static std::string msTypeName;
};
std::string OctreeSceneManagerFactory::msTypeName = "OctreeSceneManager";

// 对应 SceneManagerEnumerator(OgreSceneManagerEnumerator.h 84)。
class SceneManagerEnumerator {
 public:
  using Factories = std::map<std::string, SceneManagerFactory*>;
  using Instances = std::map<std::string, SceneManager*>;

  // 构造函数登记默认工厂(OgreSceneManagerEnumerator.cpp 46-51)。
  SceneManagerEnumerator() { addFactory(&mDefaultFactory); }

  // 对应 addFactory(OgreSceneManagerEnumerator.cpp 74-81)。
  void addFactory(SceneManagerFactory* fact) {
    mFactories[fact->getTypeName()] = fact;
    mMetaDataList.push_back(fact->getTypeName());
  }

  // 对应 getMetaData(112)。
  const std::vector<std::string>& getMetaData() const { return mMetaDataList; }

  // 对应 createSceneManager(108-147)。
  SceneManager* createSceneManager(const std::string& typeName, const std::string& instanceName) {
    if (mInstances.find(instanceName) != mInstances.end())
      throw std::runtime_error("SceneManager instance called '" + instanceName + "' already exists");
    auto it = mFactories.find(typeName);
    if (it == mFactories.end())
      throw std::runtime_error("No factory found for scene manager of type '" + typeName + "'");

    std::string name = instanceName;
    if (name.empty()) {
      std::stringstream s;
      s << "SceneManagerInstance" << ++mInstanceCreateCount;
      name = s.str();
    }
    SceneManager* inst = it->second->createInstance(name);
    mInstances[inst->getName()] = inst;
    return inst;
  }

  size_t numFactories() const { return mFactories.size(); }
  size_t numInstances() const { return mInstances.size(); }

  Factories mFactories;
  Instances mInstances;
  std::vector<std::string> mMetaDataList;
  DefaultSceneManagerFactory mDefaultFactory;
  unsigned long mInstanceCreateCount = 0;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 枚举器默认登记 DefaultSceneManager
  SceneManagerEnumerator enumerator;
  CHECK_EQ(enumerator.numFactories(), size_t(1));
  CHECK(enumerator.mFactories.find(SMT_DEFAULT) != enumerator.mFactories.end());

  // 插件可再登记新类型工厂(如 OctreeSceneManager)
  OctreeSceneManagerFactory octreeFactory;
  enumerator.addFactory(&octreeFactory);
  CHECK_EQ(enumerator.numFactories(), size_t(2));
  CHECK(enumerator.mMetaDataList[1] == "OctreeSceneManager");

  // createSceneManager:按类型创建,空名自动编号
  SceneManager* sm1 = enumerator.createSceneManager(SMT_DEFAULT, "");
  CHECK(sm1 != nullptr);
  CHECK(sm1->getName() == "SceneManagerInstance1");
  CHECK_EQ(enumerator.numInstances(), size_t(1));

  // 显式命名
  SceneManager* sm2 = enumerator.createSceneManager(SMT_DEFAULT, "Main");
  CHECK(sm2 != nullptr);
  CHECK(sm2->getName() == "Main");
  CHECK(enumerator.mInstances["Main"] == sm2);

  // 重复实例名被拒绝
  bool dupInstance = false;
  try {
    enumerator.createSceneManager(SMT_DEFAULT, "Main");
  } catch (const std::runtime_error&) {
    dupInstance = true;
  }
  CHECK(dupInstance);

  // 未知类型被拒绝
  bool unknownType = false;
  try {
    enumerator.createSceneManager("NoSuchType", "x");
  } catch (const std::runtime_error&) {
    unknownType = true;
  }
  CHECK(unknownType);

  // SceneManager 默认能力:场景节点与相机登记
  sm2->createSceneNode("root");
  sm2->createSceneNode("cameraNode");
  CHECK(sm2->hasSceneNode("root"));
  CHECK(sm2->hasSceneNode("cameraNode"));
  CHECK_EQ(sm2->nodeCount(), size_t(2));
  bool dupNode = false;
  try {
    sm2->createSceneNode("root");
  } catch (const std::runtime_error&) {
    dupNode = true;
  }
  CHECK(dupNode);

  sm2->createCamera("MainCamera");
  CHECK(sm2->hasCamera("MainCamera"));
  bool dupCamera = false;
  try {
    sm2->createCamera("MainCamera");
  } catch (const std::runtime_error&) {
    dupCamera = true;
  }
  CHECK(dupCamera);

  return lab::report("15-1 场景装配");
}

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

小结

  • Root::createSceneManager 委托给 SceneManagerEnumerator,类型选择用类型名(如 SMT_DEFAULT),不是已弃用的 ST_GENERIC 枚举。
  • SceneManagerEnumerator 以工厂表(类型名 → 工厂)+ 实例表(实例名 → 管理器)管理装配,构造时登记默认工厂。
  • createSceneManager:实例名查重、类型查工厂、空名自动编号、创建后登记。
  • SceneManager 按名登记节点与相机,重名抛异常;命名查重贯穿整个装配层。
  • 第三方场景管理器以插件工厂扩展,注册后即可用类型名创建。

阅读导航:上一节:14.3 RTSS 与场景集成 · 下一节:15.2 相机视口装配 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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