5.3 MovableObject 与附着
场景里能被移动、被渲染的东西——实体、灯光、相机、粒子、布告板——都是 MovableObject 的子类。它是「可移动对象」这一族类的基类。一个场景对象要出现在场景里,必须附着(attach)到某个 SceneNode 上。
不透明对象 + 名字表
OgreMovableObject.h 是这条对象族谱的根。它持有两个关键成员:
// OgreMain/include/OgreMovableObject.h:MovableObject 成员(v14.6.3 教学示意,参照上游同名实现,已删减)
class _OgreExport MovableObject
{
...
protected:
/// The render object parent node (s)
SceneNode* mParentNode;
/// Object's name
String mName;
...
};
mParentNode 指向当前挂载的节点——对象知道自己在哪个节点上;而节点的 mObjectsByName 反过来存对象指针——节点也知道自己挂了哪些对象。这是一组双向绑定。mObjectsByName 保存对象指针,getAttachedObject(name) 按名字线性查找。
attachObject 的四个步骤
SceneNode::attachObject 的执行顺序值得细读,它把约束都藏在步骤里:
- 断言未附着:
OgreAssert(!obj->isAttached(), ...)——一个对象同一时刻只能挂在一个节点上; - 回叫:
obj->_notifyAttached(this)——让对象先记住父节点; - 查重:遍历
mObjectsByName,发现同名对象抛ERR_DUPLICATE_ITEM——同一节点上名字必须唯一; - 入表 + 失效:
mObjectsByName.push_back(obj)后needUpdate()——请求更新包围盒,向上游传播更新需求。
// OgreMain/src/OgreSceneNode.cpp(v14.6.3 源码摘录,调整空白)
void SceneNode::attachObject(MovableObject* obj)
{
OgreAssert(!obj->isAttached(), "Object already attached to a SceneNode or a Bone");
obj->_notifyAttached(this);
MovableObjectNameExists pred = {obj->getName()};
ObjectMap::iterator it = std::find_if(mObjectsByName.begin(), mObjectsByName.end(), pred);
if (it != mObjectsByName.end())
OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM,
"An object named '" + obj->getName() + "' already attached to this SceneNode");
mObjectsByName.push_back(obj);
needUpdate();
}
_notifyAttached 是「对象主动通知」模式的体现:MovableObject 自己维护 mParentNode,节点不直接改对象的私有成员,而是调对象的公开回叫,由对象自己完成状态更新。对称地,detachObject 调 _notifyAttached(nullptr) 清空父指针并通知对象监听器。这套「节点 ↔ 对象」的双向回叫,是 OGRE 可替换对象体系(卷三 Entity/Light/Camera 细分)的黏合剂。
为什么双向绑定重要
单向外挂会出问题:对象要知道自己在哪(拾取回查、阴影判定),节点要知道自己挂了谁(渲染遍历、名字定位)。mParentNode + mObjectsByName 双向都在,任何一侧的需求都不用临时遍历对侧。代价是必须保持两侧一致——所以 attachObject/detachObject 严格配对,重名检测发生在设置父指针之后,重名异常可能留下对象侧状态。
重名失败时对象和节点各自记录了什么
attachObject 先用 _notifyAttached 写对象的父指针,再查重和把指针加入节点列表。成功后两侧可互查。若重名抛异常,不能仅凭父指针推断节点列表里已登记该对象。
把正常附着、重复名、合法分离分别画出和记录。检查父指针、节点对象数和监听回调,分离成功后再走需要销毁对象的流程。
附着与重名分支
sequenceDiagram
participant A as 调用方
participant N as SceneNode
participant O as MovableObject
A->>N: attachObject
N->>O: 检查是否已附着
N->>O: _notifyAttached 写父指针
N->>N: 遍历当前对象检查同名
alt 同名
N-->>A: 抛异常,父指针更新在前
else 名称可用
N->>N: 加入对象列表并请求边界更新
Note over N,O: 节点保存引用,对象保存父指针
A->>N: detachObject
N->>N: 移除列表中的引用
N->>O: _notifyAttached nullptr
end
源码定位
OgreMain/include/OgreMovableObject.h:MovableObject(mParentNode/mName/_notifyAttached/isAttached)OgreMain/src/OgreMovableObject.cpp:_notifyAttached及附着/分离通知OgreMain/include/OgreSceneNode.h:SceneNode::attachObject/detachObjectOgreMain/src/OgreSceneNode.cpp:附着与名字表维护实现
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面复现附着双向绑定与名字查重:已附着对象不能重复附着,同名对象被拒,分离后父节点清空。它与 src/05-3-movable-object-attach.cpp 逐字节一致:
// file: src/05-3-movable-object-attach.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/05-3-movable-object-attach.cpp -o bin/05-3-movable-object-attach && ./bin/05-3-movable-object-attach
//
// 复现 SceneNode::attachObject 的双向绑定与 OgreMovableObject 的附着语义:
// 断言未附着 → _notifyAttached 记父节点 → 按名字查重 → 入表 → 失效边界。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <string>
#include <vector>
namespace ogre_repro {
class SceneNode;
// 对应 OgreMovableObject:_notifyAttached / isAttached / getParentSceneNode
class MovableObject {
public:
std::string name;
SceneNode* parentNode = nullptr;
explicit MovableObject(const std::string& n) : name(n) {}
void _notifyAttached(SceneNode* parent) { parentNode = parent; }
bool isAttached() const { return parentNode != nullptr; }
};
// 对应 OgreSceneNode:attachObject / detachObject
class SceneNode {
public:
std::string name;
std::vector<MovableObject*> mObjectsByName;
explicit SceneNode(const std::string& n) : name(n) {}
// 对应 SceneNode::attachObject:断言 + 双向绑定 + 名字查重
bool attachObject(MovableObject* obj) {
if (obj->isAttached()) return false; // 对应 OgreAssert(!isAttached())
obj->_notifyAttached(this);
for (auto o : mObjectsByName)
if (o->name == obj->name) return false; // 对应 ERR_DUPLICATE_ITEM
mObjectsByName.push_back(obj);
return true;
}
void detachObject(MovableObject* obj) {
for (auto it = mObjectsByName.begin(); it != mObjectsByName.end(); ++it)
if (*it == obj) {
mObjectsByName.erase(it);
obj->_notifyAttached(nullptr);
return;
}
}
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
SceneNode node("Tower");
MovableObject obj("Hero");
CHECK(!obj.isAttached());
CHECK(node.attachObject(&obj));
CHECK(obj.isAttached());
CHECK(obj.name == "Hero");
// 已附着的对象不能重复附着
CHECK(!node.attachObject(&obj));
// 同名对象被拒(对应 ERR_DUPLICATE_ITEM)
MovableObject imposter("Hero");
CHECK(!node.attachObject(&imposter));
// 不同名对象可附着
MovableObject other("Ally");
CHECK(node.attachObject(&other));
CHECK_EQ(node.mObjectsByName.size(), 2u);
// 分离:父节点清空
node.detachObject(&obj);
CHECK(!obj.isAttached());
CHECK_EQ(node.mObjectsByName.size(), 1u);
return lab::report("05-3 场景图:MovableObject 附着");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过,断言 10/10 通过。
小结
- MovableObject 是所有可移动/可渲染场景对象的基类,持有
mParentNode与mName。 - attachObject 四步:断言未附着 →
_notifyAttached回叫 → 名字查重 → 入表失效。 - 双向绑定保证「对象知节点、节点知对象」,两侧严格配对维护。
- 可替换对象体系(卷三)都建立在这套附着契约上。
阅读导航:上一节:5.2 SceneNode 与场景图 · 下一节:6.1 ResourceManager 与资源生命周期 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。