Ensure "global" resources can be deallocated

`🎳 physx-rs`

Rust binding for NVIDIA PhysX, a popular and mature physics engine well-suited for games

Created and maintained by Embark and not officially supported by NVIDIA.

This repository contains 2 crates:

Name	Description	Links
`physx`	High-level interface on top of `physx-sys` 🚧
`physx-sys`	Unsafe bindings to the PhysX C++ API

Why use it?

You want a feature-rich and performant physics engine to use in your project.

Caveats

The high-level physx wrapper is work-in-progress, and only covers a part of PhysX functionality. You can follow our progress and see where contributions are needed in our Tracking Issue for High-Level API Completeness.
Any other features have to be accessed through the unsafe physx-sys crate.
It's a large C++ codebase which requires a C++ toolchain, and comes with a non-trivial build system.

Alternatives

Rapier: a 2D and 3D physics engine for games, animation, and robotics written in Rust. Fully cross-platform, with web support and optional cross-platform determinism on IEEE 754-2008 compliant systems.
nphysics: a 2- and 3-dimensional physics engine for games and animations written in Rust. It is a good option for projects which do not require the full feature set of PhysX or prefer a native Rust solution.

Presentation

Tomasz Stachowiak did a presentation at the Stockholm Rust Meetup on October 2019 about this project that goes through the technical details of how C++ to Rust bindings of physx-sys works:

Usage

The following code example shows how physx can be initialized.

const PX_PHYSICS_VERSION: u32 = physx::version(4, 1, 1);
let mut foundation = Foundation::new(PX_PHYSICS_VERSION);

let mut physics = PhysicsFoundation::default();

let mut scene = physics.create(
    SceneDescriptor {
        gravity: PxVec3::new(0.0, 0.0, -9.81),
        ..SceneDescriptor::new(MySceneUserData::default())
    }
);

You can run an example with cargo run --example ball, which should show the following output:

Information about all wrapper functionality can be found in the physx crate docs.

If you require functionality not covered by the physx wrapper you can use the low level physx-sys crate, which closely maps to the official PhysX SDK. You can find the PhysX user guide here.

Prerequisites

C++ compiler (see the cc crate for requirements)

How to build

git submodule update --init
cargo build --release

Windows Note

It is highly recommended to not enable debug info in release mode when building with MSVC, as the Physx C++ code will take an extremely long time to compile. You can disable this by putting the following in your Cargo.toml

[profile.release.package.physx-sys]
debug = false

How to release (maintainers only)

Install cargo-release
Look at physx/CHANGELOG.md and physx-sys/CHANGELOG.md to determine whether both or only one of the crate needs updating, and what semantic version bump we need
Review the list of changes in the changelogs and compare with the git commit diffs to the previous release and make sure we've captured and described all changes well and that they are semantically correct
Run cargo release --manifest-path <physx|physx-sys>/Cargo.toml <major|minor|patch> to automatically update the CHANGELOG, publish, tag, and push the release. If you are publishing both physx and physx-sys, you can just add the --skip-push flag to avoid pushing each crate individually and then do git push --follow-tags to push both at the same time.

Contributing

We welcome community contributions to this project.

Please read our Contributor Guide for more information on how to get started.

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

	impl<U, M: Material> Drop for PxShape<U, M> {
	fn drop(&mut self) {
	unsafe {
	for material in self.get_materials_mut() {
	drop_in_place(material as *mut _);
	}
	drop_in_place(self.get_user_data_mut());
	PxShape_release_mut(self.as_mut_ptr());
	}
	}
	}

Module	Status	Description
🏃‍♂️ Character	❌	Not relevant for us right now. PRs welcome.
🚏 Common	🚧	Minimal coverage exists.
🎳 Physics	🚧	Most core functionality covered.
😴 Extensions	❌	Extensions can be loaded, but access is primarily through the low-level APIs still. PRs welcome.
🏠 Foundation	🚧	Core parts covered
🍕 Cooking	🚧	Minimal functionality exists
💧 Serializers	❌	No coverage yet. PRs welcome.
🔲 Geomutils	❌	No coverage yet. PRs welcome.
🪲 Pvd	🚧	Basic functionality exists and can be used
❓ Scenequery	❌	No coverage yet. PRs welcome.
⚡ Immediatemode	❌	No coverage yet. PRs welcome.
🚗 Vehicle	❌	Not relevant for us right now. PRs welcome.

	// Decide whether we should use "strugen" to calculate the exact layout of
	// this C++ struct.
	//
	// Ideally we would do this for all types, but we must be able to name them,
	// which is not feasible for anonymous types, or types which the generator
	// doesn't support yet (their cppTypeName will be empty).
	//
	// Note that empty types are only refered to by pointers and references in
	// PhysX, so we can generate dummy contents for them.
	bool shouldCalculateLayout() const {
	return hasDefinition && !cppTypeName.empty() &&
	"struct" == recordType && !fields.empty();
	}

	void fixEmptyStruct() {
	if (!hasVtable && fields.empty()) {
	PodRecordField f;
	f.name = "pxbind_dummy";
	f.decl = "char pxbind_dummy;";
	f.cppType = "char";
	f.rustType = "u8";
	fields.emplace_back(f);
	}
	}

embarkstudios / physx-rs Goto Github PK

physx-rs's Introduction

🎳 physx-rs

Why use it?

Caveats

Alternatives

Presentation

Usage

Prerequisites

How to build

Windows Note

How to release (maintainers only)

Contributing

License

Contribution

physx-rs's People

Contributors

Stargazers

Watchers

Forkers

physx-rs's Issues

The Problem

The Solution

Alternatives

Context

Modules

TODO

Recommend Projects

Recommend Topics

Recommend Org

`🎳 physx-rs`