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 并分配全局索引,而相机额外建立可见包围盒登记项。
源码定位
OgreMain/src/OgreRoot.cpp:createSceneManager(540-543)OgreMain/src/OgreSceneManagerEnumerator.cpp:构造(46-51)、addFactory(74-81)、removeFactory(86-109)、createSceneManager(111-147)OgreMain/src/OgreSceneManagerEnumerator.h:SceneManagerEnumerator类(84-)OgreMain/src/OgreSceneManager.cpp:createCamera(168-186)、createSceneNode(525-541)OgreMain/include/OgreSceneManager.h:SMT_DEFAULT(3452)
上游引用固定到 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 相机视口装配 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。