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 | 抛 DUPLICATE | mGlobalIndex 全局序号 |
| 相机 | 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 一帧渲染循环 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。