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, 0);
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(glm::vec3(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

actor	Trait for PxActor
articulation_base	Wrapper for PxArticulationBase
articulation_cache
articulation_joint
articulation_joint_base
articulation_joint_reduced_coordinate
articulation_link	A link of a reduced coordinate multibody.
articulation_reduced_coordinate	ArticulationReducedCoordinate wrapper for PhysX.
base	Wrapper for PxBase.
body	Utility for handle-based usage
cooking
foundation	Wrapper for PxFoundation class
geometry
heightfield
math
physics	Wrapper interface for Physics
prelude	Prelude for commonly useful types
rigid_actor	Trait for RigidActor
rigid_body
rigid_dynamic	Wrapper implementation for PxRigidDynamic
rigid_static
scene	Wrapper for PhysX Scene
shape	Wrapper for PxShape
traits
transform	This defines utility conversion functions from PhysX data types to glm datatypes for easier usage.
user_data
visual_debugger

Functions

version

[−][src]Crate physx