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)与 OGREQuaternion(w,x,y,z)的存储序。RigidBodyState(MotionState)让 Bullet 每步回调setWorldTransform把位移/旋转写回SceneNode。DynamicsWorld负责刚体注册与原生世界访问,stepSimulation由用户主循环显式驱动。CollisionWorld::rayTest按maxDist(默认 1000)收集命中回调。- 包装持有配置/调度器/宽相的唯一指针,内存管理自动;原生
btWorld通过getBtWorld()暴露。
阅读导航:上一节:11.3 Assimp 资源导入 · 下一节:12.2 内容导入集成 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。