《OGRE 3D 渲染引擎原理与架构》12.1 Bullet 物理集成

12.1 讲 OGRE 的 Bullet 组件包装。convert 处理 btQuaternion 与 OGRE 四元数的序互换;RigidBodyState 是 MotionState,物理变换写回 SceneNode;DynamicsWorld 提供 addRigidBody/getBtWorld,stepSimulation 由用户主循环调用。lab 复现双向同步与射线命中,17 项断言。

12.1 Bullet 物理集成

OGRE 的 Components/Bullet 不是物理引擎本身,而是对 Bullet Physics 的一层简化包装:头文件 OgreBullet.h 提供 convert 双向转换函数、RigidBodyState(MotionState)与 CollisionWorld/DynamicsWorld。核心价值有两点:一是类型转换——btQuaternion 存储序是 x,y,z,w,OGRE Quaternion 是 w,x,y,z,convert 负责互换;二是把物理变换自动同步到 SceneNode——RigidBodyState::setWorldTransform 是 Bullet 每步回调,把刚体的位移与旋转写回 OGRE 节点。世界步进(stepSimulation)不由包装调用,由你的主循环显式驱动。

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

本章是「引擎混合使用」的最后一环:前面章节都在 OGRE 内部;本节把 OGRE 与第三方物理库对接。lab 复现四元数序互换、MotionState 双向同步、刚体注册与射线命中收集。

convert:btQuaternion 与 OGRE 四元数的序互换

OgreBullet.h 顶部的四个 convert 内联函数定义了双向转换。注意 btQuaternion(q.x, q.y, q.z, q.w) 构造的实参顺序是 x,y,z,w——对应 OGRE 四元数的虚部在前;反向 Quaternion(q.w(), q.x(), q.y(), q.z()) 把 w 放回第一个位置:

// Components/Bullet/include/OgreBullet.h:convert(v14.6.3 源码摘录,已删减)
inline btQuaternion convert(const Quaternion& q) { return btQuaternion(q.x, q.y, q.z, q.w); }
inline btVector3 convert(const Vector3& v) { return btVector3(v.x, v.y, v.z); }

inline Quaternion convert(const btQuaternion& q) { return Quaternion(q.w(), q.x(), q.y(), q.z()); }
inline Vector3 convert(const btVector3& v) { return Vector3(v.x(), v.y(), v.z()); }

RigidBodyState:MotionState 把物理结果写回 SceneNode

RigidBodyState 继承 btMotionState,构造时绑一个 Node*。getWorldTransform 把节点的当前方位/位置转成 btTransform;setWorldTransform 是 Bullet 每步更新刚体后回调的重写——它取出 btTransform 的旋转与原点,以 rot.w(), rot.x(), rot.y(), rot.z() 与 pos.x(), pos.y(), pos.z() 写回节点。这样渲染树每帧读到的就是最新物理姿态:

// Components/Bullet/include/OgreBullet.h:RigidBodyState(v14.6.3 源码摘录,已删减)
class _OgreBulletExport RigidBodyState : public btMotionState
{
    Node* mNode;

public:
    RigidBodyState(Node* node) : mNode(node) {}

    void getWorldTransform(btTransform& ret) const override
    {
        ret = btTransform(convert(mNode->getOrientation()), convert(mNode->getPosition()));
    }

    void setWorldTransform(const btTransform& in) override
    {
        btQuaternion rot = in.getRotation();
        btVector3 pos = in.getOrigin();
        mNode->setOrientation(rot.w(), rot.x(), rot.y(), rot.z());
        mNode->setPosition(pos.x(), pos.y(), pos.z());
    }
};

DynamicsWorld:addRigidBody 与原生世界的步进

DynamicsWorld 继承 CollisionWorld(后者持有 btCollisionWorld* mBtWorld 与配置/调度器/宽相的唯一指针)。它提供 addRigidBody(mass, ent, colliderType, ...) 把实体注册成刚体、attachRigidBody 附加已有刚体,以及 getBtWorld() 返回原生 btDynamicsWorld*。注释特别说明 stepSimulation 不在包装里——调用方在自己的主循环里拿 getBtWorld() 去步进。CollisionWorld::rayTest 带 maxDist(默认 1000)收集射线命中回调:

// Components/Bullet/include/OgreBullet.h:DynamicsWorld(v14.6.3 源码摘录,已删减)
class _OgreBulletExport DynamicsWorld : public CollisionWorld
{
    std::unique_ptr<btConstraintSolver> mSolver;

public:
    explicit DynamicsWorld(const Vector3& gravity);
    DynamicsWorld(btDynamicsWorld* btWorld) : CollisionWorld(btWorld) {}

    /** Add an Entity as a rigid body to the DynamicsWorld
    * @param mass the mass of the object
    * @param ent the entity to control
    * @param ct the collider type
    * @param listener a listener to call on collision with other objects
    * @param group the collision group
    * @param mask the collision mask
    */
    btRigidBody* addRigidBody(float mass, Entity* ent, ColliderType ct, CollisionListener* listener = nullptr,
                              int group = 1, int mask = -1);
    btRigidBody* addKinematicRigidBody(Entity* ent, ColliderType ct, int group = 1, int mask = -1);

    void attachRigidBody(btRigidBody *rigidBody, Entity *ent, CollisionListener* listener = nullptr,
                              int group = 1, int mask = -1);
    btDynamicsWorld* getBtWorld() const { return static_cast<btDynamicsWorld*>(mBtWorld); }
};

以及 CollisionWorld::rayTest 的默认最大距离:

// Components/Bullet/include/OgreBullet.h:CollisionWorld(v14.6.3 源码摘录,已删减)
    btCollisionObject* addCollisionObject(Entity* ent, ColliderType ct, int group = 1, int mask = -1);

    void rayTest(const Ray& ray, RayResultCallback* callback, float maxDist = 1000);
    void attachCollisionObject(btCollisionObject *collisionObject, Entity *ent, int group = 1, int mask = -1);

源码定位

  • Components/Bullet/include/OgreBullet.h:convert(43-47 行)
  • Components/Bullet/include/OgreBullet.h:RigidBodyState(52-71 行)
  • Components/Bullet/include/OgreBullet.h:CollisionWorld::rayTest(137 行)
  • Components/Bullet/include/OgreBullet.h:DynamicsWorld(181-221 行)

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

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

RigidBodyStateRepro 复现 getWorldTransform/setWorldTransform 的四元数序互换与节点同步;DynamicsWorldRepro 复现 addRigidBody 返回 id、stepSimulation 由用户主循环显式调用(包装不自动步进)、rayTest 按 maxDist 收集命中。它与 src/12-1-bullet-physics.cpp 逐字节一致:

// file: src/12-1-bullet-physics.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/12-1-bullet-physics.cpp -o bin/12-1-bullet-physics && ./bin/12-1-bullet-physics
//
// 复现 Bullet 组件包装(Components/Bullet/include/OgreBullet.h 43-71 的
//   convert 与 RigidBodyState、121-139 的 CollisionWorld::rayTest、181-221
//   的 DynamicsWorld::addRigidBody/getBtWorld):RigidBodyState 把 Bullet
//   的变换写回 SceneNode(四元数序 btQuaternion x,y,z,w ↔ OGRE w,x,y,z);
//   getBtWorld() 返回原生世界,stepSimulation 由用户主循环调用;rayTest
//   以 maxDist 收集命中回调。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <string>
#include <utility>
#include <vector>

namespace ogre_repro {

struct NodeRepro {  // 对应 Ogre::Node:位置 + 四元数(w,x,y,z)
    float pos[3] = {0, 0, 0};
    float rot[4] = {1, 0, 0, 0};  // w,x,y,z
    void setPosition(float x, float y, float z) {
        pos[0] = x;
        pos[1] = y;
        pos[2] = z;
    }
    void setOrientation(float w, float x, float y, float z) {
        rot[0] = w;
        rot[1] = x;
        rot[2] = y;
        rot[3] = z;
    }
};

struct BtTransformRepro {  // 对应 btTransform:旋转(x,y,z,w)+ 原点
    float rot[4] = {0, 0, 0, 1};
    float origin[3] = {0, 0, 0};
};

// 对应 OgreBullet.h 52-71 的 RigidBodyState:MotionState 与 Node 双向同步
class RigidBodyStateRepro {
public:
    explicit RigidBodyStateRepro(NodeRepro* node) : mNode(node) {}

    void getWorldTransform(BtTransformRepro& ret) const {
        ret.rot[0] = mNode->rot[1];  // x
        ret.rot[1] = mNode->rot[2];  // y
        ret.rot[2] = mNode->rot[3];  // z
        ret.rot[3] = mNode->rot[0];  // w
        ret.origin[0] = mNode->pos[0];
        ret.origin[1] = mNode->pos[1];
        ret.origin[2] = mNode->pos[2];
    }

    void setWorldTransform(const BtTransformRepro& in) {
        mNode->setOrientation(in.rot[3], in.rot[0], in.rot[1], in.rot[2]);
        mNode->setPosition(in.origin[0], in.origin[1], in.origin[2]);
    }

private:
    NodeRepro* mNode;
};

struct RigidBodyRepro {
    uint32_t id;
    float mass;
    std::string entityName;
    float x;  // 简化的一维位置,用于射线命中
};

struct EntityHit {
    std::string name;
    float distance;
};

// 对应 OgreBullet.h 181-221 的 DynamicsWorld(瘦身)
class DynamicsWorldRepro {
public:
    explicit DynamicsWorldRepro(float gravityY) : mGravityY(gravityY) {}

    // 对应 DynamicsWorld::addRigidBody:返回新刚体 id
    uint32_t addRigidBody(float mass, std::string entName, float x) {
        mBodies.push_back({mNextId++, mass, std::move(entName), x});
        return mBodies.back().id;
    }

    // 对应 getBtWorld():原生世界步进由用户在主循环调用
    void stepSimulation(float dt) { (void)dt; ++mStepCalls; }

    // 对应 CollisionWorld::rayTest:沿正 x 的射线按 maxDist 收集命中
    std::vector<EntityHit> rayTest(float maxDist) const {
        std::vector<EntityHit> hits;
        for (const auto& b : mBodies) {
            if (b.x >= 0.0f && b.x <= maxDist)
                hits.push_back({b.entityName, b.x});
        }
        return hits;
    }

    uint32_t stepCalls() const { return mStepCalls; }
    float gravityY() const { return mGravityY; }

private:
    std::vector<RigidBodyRepro> mBodies;
    uint32_t mNextId = 1;
    uint32_t mStepCalls = 0;
    float mGravityY;
};

}  // namespace ogre_repro

int main() {
    using namespace ogre_repro;

    // 重力初值 + 用户主循环手动步进
    DynamicsWorldRepro world(-9.81f);
    CHECK(world.gravityY() < 0.0f);
    world.stepSimulation(1.0f / 60.0f);
    world.stepSimulation(1.0f / 60.0f);
    CHECK_EQ(world.stepCalls(), 2u);  // stepSimulation 不是包装提供的

    // addRigidBody:动态刚体与静态地面
    const uint32_t boxId = world.addRigidBody(10.0f, "Box", 10.0f);
    const uint32_t groundId = world.addRigidBody(0.0f, "Ground", 50.0f);
    CHECK(boxId != groundId);
    CHECK(boxId >= 1u && groundId >= 1u);

    // RigidBodyState:Node → Bullet 变换
    NodeRepro node;
    node.setPosition(1, 2, 3);
    node.setOrientation(1, 0, 0, 0);  // 单位四元数
    RigidBodyStateRepro state(&node);
    BtTransformRepro t;
    state.getWorldTransform(t);
    CHECK_EQ(t.origin[0], 1.0f);
    CHECK_EQ(t.origin[1], 2.0f);
    CHECK_EQ(t.origin[2], 3.0f);
    CHECK_EQ(t.rot[0], 0.0f);  // bt 四元数序 x,y,z,w
    CHECK_EQ(t.rot[3], 1.0f);  // w

    // Bullet 变换 → Node:物理结果写回场景节点
    BtTransformRepro moved;
    moved.origin[0] = 5;
    moved.origin[1] = 6;
    moved.origin[2] = 7;
    state.setWorldTransform(moved);
    CHECK_EQ(node.pos[0], 5.0f);
    CHECK_EQ(node.pos[1], 6.0f);
    CHECK_EQ(node.pos[2], 7.0f);
    CHECK_EQ(node.rot[0], 1.0f);  // w 保持单位

    // rayTest:默认 maxDist=1000 收集两个命中,20 内只 Box
    const std::vector<EntityHit> all = world.rayTest(1000.0f);
    CHECK_EQ(all.size(), 2u);
    CHECK(all[0].name == "Box" && all[1].name == "Ground");
    CHECK_EQ(world.rayTest(20.0f).size(), 1u);
    CHECK_EQ(world.rayTest(5.0f).size(), 0u);  // maxDist 过滤

    return lab::report("12.1 Bullet 物理集成");
}

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

小结

  • convert 系列内联函数互换 btQuaternion(x,y,z,w) 与 OGRE Quaternion(w,x,y,z) 的存储序。
  • RigidBodyState(MotionState)让 Bullet 每步回调 setWorldTransform 把位移/旋转写回 SceneNode。
  • DynamicsWorld 负责刚体注册与原生世界访问,stepSimulation 由用户主循环显式驱动。
  • CollisionWorld::rayTest 按 maxDist(默认 1000)收集命中回调。
  • 包装持有配置/调度器/宽相的唯一指针,内存管理自动;原生 btWorld 通过 getBtWorld() 暴露。

阅读导航:上一节:11.3 Assimp 资源导入 · 下一节:12.2 内容导入集成 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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