Crate physx

Expand description

§🎳 physx

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 here

For 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.

Modules§

Functions§

version

Crate physxCopy item path