Crate physx[−][src]
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 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
Trait for PxActor
Wrapper for PxArticulationBase
A link of a reduced coordinate multibody.
PxArticulationReducedCoordinate wrapper for PhysX.
Wrapper for PxBase.
Wrapper for PxFoundation class
Wrapper interface for PxPhysics
Prelude for commonly useful types
Trait for RigidActor
Wrapper implementation for PxRigidDynamic
Wrapper for PhysX PxScene
Wrapper for PxShape
Macros
Macro for quickly defining Class<…> impls for new type wrappers. The type must be repr(transparent), and have the Px object in a field named obj. Will not work if the type parameters have trait bounds.