Expand description
🎳 physx
This is a work in progress 🚧
physx is intended to be an easy to use high-level wrapper for the physx-sys
bindings. The goal of this is to make ownership clearer and leverage the safety of Rust.
The overall goal is to maintain a close mapping to the underlying PhysX API while improving safety and reliability
of the code. This means, for example, that we do not expose the PxLoadExtensions() function but rather attach
this to the Physics builder.
Please also see the repository containing an unsafe low-level binding.
Example
Basic usage
const PX_PHYSICS_VERSION: u32 = physx::version(4, 1, 1);
let mut foundation = Foundation::new(PX_PHYSICS_VERSION);
let mut physics = PhysicsBuilder::default()
.load_extensions(false) // Flip this flag to load extensions during setup
.build(&mut foundation);
let mut scene = physics.create_scene(
SceneBuilder::default()
.set_gravity(Vec3::new(0.0, -9.81, 0.0))
.set_simulation_threading(SimulationThreadType::Dedicated(1)),
);
// Your physics simulation goes hereFor a full example, have a look at the bouncing ball example and compare it to the raw sys example.
How it works
Wrapping a C++ API in Rust is not straightforward, and requires some extra steps
to work. The first, and most basic one is creating a C wrapper over the C++ API.
Using C as an intermediary allows us to leverage a stable ABI through which C++
and Rust can communicate. The physx-sys crate provides this interface.
Since PhysX makes significant use of inheritance, there is no straightforward mapping to Rust code. To simulate
the inheritance, we have a pointer-wrapper called PxType<T>. We implement the functions on each
wrapped PxType<PxRgidiActor> and expose an alias RigidActor.
The deref pattern is used to
simulate inheritance. For example RigidBody::set_angular_damping, can be called from the child RigidDynamic
because RigidDynamic implements Deref<Target = RigidBody>.
// `set_angular_damping` is not defined in `RigidDynamic`, it is defined in `RidigBody`.
// This works because `Deref` is used to emulate inheritance.
let mut sphere_actor: RigidDynamic = unsafe { physics.create_dynamic(..) };
sphere_actor.set_angular_damping(0.5);
// The verbose example to show what happens behind the scenes.
let mut sphere_actor: RigidDynamic = unsafe { physics.create_dynamic(..) };
{
// `RidigDynamic` implements `Deref/DerefMut` to a `RigidBody`.
let sphere_actor: &mut RigidBody = &mut *sphere_actor;
sphere_actor.set_angular_damping(0.5);
}
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Note that the PhysX C++ SDK has it’s own BSD 3 license and depends on additional C++ third party libraries.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.