《OGRE 3D 渲染引擎原理与架构》15.2 建场景

建场景就是往 SceneManager 里登记对象:createSceneNode 把节点 push 进 mSceneNodes 并分配全局索引;createSceneNode(name)/createCamera(name) 先查重名,重名抛 ERR_DUPLICATE_ITEM。camera 用 std::map 按名索引。lab 用 C++ 复现节点登记、重名检查与相机注册表。

15.2 建场景

15.1 把 Root 转起来了;这一节填场景——SceneManager 的 createSceneNode 与 createCamera 是每个 OGRE 程序最早调用的几个 API。它们背后是「登记表 + 重名检查 + 异常」,模式与 11 章 Entity 的注册如出一辙。

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

第 5 章讲过场景图的原理(Node/MovableObject 关系);这里看创建路径的实现——节点和相机如何进入 SceneManager 的登记表。

createSceneNode:入表 + 全局索引

SceneManager::createSceneNode 分匿名与命名两个版本。匿名版最直接:

// OgreMain/src/OgreSceneManager.cpp:SceneManager::createSceneNode(v14.6.3 源码摘录,已删减)
    SceneNode* SceneManager::createSceneNodeImpl(void)
    {
        return OGRE_NEW SceneNode(this);
    }
    SceneNode* SceneManager::createSceneNodeImpl(const String& name)
    {
        return OGRE_NEW SceneNode(this, name);
    }
    SceneNode* SceneManager::createSceneNode(void)
    {
        SceneNode* sn = createSceneNodeImpl();
        mSceneNodes.push_back(sn);
        sn->mGlobalIndex = mSceneNodes.size() - 1;
        return sn;
    }

要点:OGRE_NEW 建节点,立即 push_back 进 mSceneNodes,并顺势把 mGlobalIndex 设为当前 vector 末尾下标——全局索引就是「第几个被创建」。这个索引对场景查询、渲染队列的顺序有意义。

createSceneNode(name):重名检查

命名版多了第一步——查重:

// OgreMain/src/OgreSceneManager.cpp:SceneManager::createSceneNode(name)(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" );
        }
        ...
    }

重名直接 OGRE_EXCEPT(ERR_DUPLICATE_ITEM, ...)——14.2 讲过的工厂分发把码映射成 ItemIdentityException,描述串里带上重复的名字,来源填函数名。这是 OGRE 全套的「报错协议」:不返回错误码,抛异常,异常里带出处。

createCamera:map 登记

相机用 std::map<String, Camera*> 按名索引,重名同样抛 DUPLICATE:

// 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;
    }

新建的相机同时会往 mCamVisibleObjectsMap 里登记一个「可见对象包围盒信息」条目——这是为后续剔除准备的(卷三第 3 章)。getCamera(name) 取不到时抛 ERR_ITEM_NOT_FOUND(与 DUPLICATE 同码,14.2 讲过别名)。

三个登记的共性与差异

对象容器重名副产品
匿名节点std::vector无检查mGlobalIndex 全局序号
命名节点std::vector抛 DUPLICATEmGlobalIndex 全局序号
相机std::map<String, Camera*>抛 DUPLICATE可见包围盒条目

共性:创建即登记,之后 getXxx(name)/hasXxx(name) 都能按名查。这是 OGRE「名字即身份」管理风格的一贯体现。

源码定位

  • OgreMain/src/OgreSceneManager.cpp :SceneManager::createSceneNodeImpl/createSceneNode(push_back + mGlobalIndex)、createSceneNode(name)(hasSceneNode 重名检查 + OGRE_EXCEPT)、createCamera(mCameras.emplace + 重名检查 + mCamVisibleObjectsMap 登记)

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

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

下面复现节点/相机的登记与重名检查。它与 src/15-2-scene-setup.cpp 逐字节一致:

// file: src/15-2-scene-setup.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/15-2-scene-setup.cpp -o bin/15-2-scene-setup && ./bin/15-2-scene-setup
//
// 复现 SceneManager 建场景对象:
//   createSceneNode():登记进 mSceneNodes 并分配 mGlobalIndex(对应 OgreSceneManager.cpp 517-523);
//   createSceneNode(name):重名抛 ERR_DUPLICATE_ITEM(对应 525-534);
//   createCamera(name):登记进 mCameras,重名抛 ERR_DUPLICATE_ITEM(对应 168-186)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <map>
#include <string>
#include <vector>

namespace ogre_repro {

class SceneManager;

// 简化错误码:对应 Ogre::Exception::ERR_DUPLICATE_ITEM
struct Err {
  static const int DUPLICATE = 1;
};

class SceneNode {
 public:
  SceneNode(SceneManager* sm, const std::string& name) : mName(name), mParent(sm) {}
  std::string mName;
  int mGlobalIndex = -1;
  SceneManager* mParent;
};

class Camera {
 public:
  Camera(SceneManager* sm, const std::string& name) : mName(name), mParent(sm) {}
  std::string mName;
  SceneManager* mParent;
};

class SceneManager {
 public:
  // 对应 createSceneNode():push_back + 全局索引
  SceneNode* createSceneNode() {
    SceneNode* sn = new SceneNode(this, "");
    mSceneNodes.push_back(sn);
    sn->mGlobalIndex = static_cast<int>(mSceneNodes.size() - 1);
    return sn;
  }
  // 对应 createSceneNode(name):重名检查
  SceneNode* createSceneNode(const std::string& name) {
    if (hasSceneNode(name)) throw Err::DUPLICATE;
    SceneNode* sn = new SceneNode(this, name);
    mSceneNodes.push_back(sn);
    sn->mGlobalIndex = static_cast<int>(mSceneNodes.size() - 1);
    return sn;
  }
  bool hasSceneNode(const std::string& name) const {
    for (auto* sn : mSceneNodes)
      if (sn->mName == name) return true;
    return false;
  }
  // 对应 createCamera:map + 重名检查
  Camera* createCamera(const std::string& name) {
    if (mCameras.find(name) != mCameras.end()) throw Err::DUPLICATE;
    Camera* c = new Camera(this, name);
    mCameras.emplace(name, c);
    return c;
  }
  bool hasCamera(const std::string& name) const { return mCameras.find(name) != mCameras.end(); }
  Camera* getCamera(const std::string& name) const {
    auto it = mCameras.find(name);
    return it == mCameras.end() ? nullptr : it->second;
  }

  std::vector<SceneNode*> mSceneNodes;
  std::map<std::string, Camera*> mCameras;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  SceneManager sm;

  // createSceneNode():匿名节点,全局索引递增
  SceneNode* root = sm.createSceneNode();
  CHECK(root->mGlobalIndex == 0);
  SceneNode* second = sm.createSceneNode();
  CHECK(second->mGlobalIndex == 1);

  // createSceneNode(name):命名节点
  SceneNode* player = sm.createSceneNode("Player");
  CHECK(sm.hasSceneNode("Player"));
  CHECK(player->mGlobalIndex == 2);

  // 重名抛 DUPLICATE
  bool threw = false;
  try { sm.createSceneNode("Player"); } catch (int) { threw = true; }
  CHECK(threw);

  // createCamera:登记 + 按名取回
  Camera* cam = sm.createCamera("MainCam");
  CHECK(sm.hasCamera("MainCam"));
  CHECK(sm.getCamera("MainCam") == cam);
  CHECK(sm.getCamera("Missing") == nullptr);

  // 重名 camera 抛 DUPLICATE
  threw = false;
  try { sm.createCamera("MainCam"); } catch (int) { threw = true; }
  CHECK(threw);

  return lab::report("15-2 装配:最小的 OGRE 程序(建场景)");
}

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

小结

  • createSceneNode() 建节点即入 mSceneNodes,mGlobalIndex 就是 vector 下标——「第几个被创建」。
  • 命名版先 hasSceneNode 查重,重名抛 ERR_DUPLICATE_ITEM(描述带名字)。
  • createCamera 用 std::map 按名登记,同时建可见包围盒条目,取不到抛 ERR_ITEM_NOT_FOUND。
  • 范式:创建即登记 + 名字即身份 + 出错抛异常。

阅读导航:上一节:15.1 最小的 Root 启动 · 下一节:15.3 一帧渲染循环 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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