《OGRE 3D 渲染引擎原理与架构》5.3 MovableObject 与附着

MovableObject 是所有可渲染/可移动场景对象的基类,不透明对象表与名字表让 SceneNode 能定位它。attachObject 的步骤是断言、回叫、查重、入表、失效边界。lab 用 C++ 复现附着双向绑定与名字查重语义。

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 的执行顺序值得细读,它把约束都藏在步骤里:

  1. 断言未附着:OgreAssert(!obj->isAttached(), ...)——一个对象同一时刻只能挂在一个节点上;
  2. 回叫:obj->_notifyAttached(this)——让对象先记住父节点;
  3. 查重:遍历 mObjectsByName,发现同名对象抛 ERR_DUPLICATE_ITEM——同一节点上名字必须唯一;
  4. 入表 + 失效: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

源码定位

上游引用固定到 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 与资源生命周期 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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