1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
//! # 🎳 physx-sys //! //! ![Build Status](https://github.com/EmbarkStudios/physx-rs/workflows/CI/badge.svg) //! [![Crates.io](https://img.shields.io/crates/v/physx-sys.svg)](https://crates.io/crates/physx-sys) //! [![Docs](https://docs.rs/physx-sys/badge.svg)](https://docs.rs/physx-sys) //! [![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-v1.4%20adopted-ff69b4.svg)](../CODE_OF_CONDUCT.md) //! [![Embark](https://img.shields.io/badge/embark-open%20source-blueviolet.svg)](http://embark.games) //! //! Unsafe automatically-generated Rust bindings for [NVIDIA PhysX 4.1](https://github.com/NVIDIAGameWorks/PhysX) C++ API. //! //! Please also see the [repository](https://github.com/EmbarkStudios/physx-rs) containing a work-in-progress safe wrapper. //! //! ## Presentation //! //! [Tomasz Stachowiak](https://github.com/h3r2tic) did a presentation at the Stockholm Rust Meetup on October 2019 //! about this project that goes through the tecnical details of how C++ to Rust bindings of `physx-sys` works: //! //! [![](http://img.youtube.com/vi/RxtXGeDHu0w/0.jpg)](http://www.youtube.com/watch?v=RxtXGeDHu0w "An unholy fusion of //! Rust and C++ in physx-rs (Stockholm Rust Meetup, October 2019)") //! //! //! ## Basic usage //! //! ```Rust //! unsafe { //! let foundation = physx_create_foundation(); //! let physics = physx_create_physics(foundation); //! //! let mut scene_desc = PxSceneDesc_new(PxPhysics_getTolerancesScale(physics)); //! scene_desc.gravity = PxVec3 { //! x: 0.0, //! y: -9.81, //! z: 0.0, //! }; //! //! let dispatcher = PxDefaultCpuDispatcherCreate(2, null_mut()); //! //! scene_desc.cpuDispatcher = dispatcher as *mut PxCpuDispatcher; //! scene_desc.filterShader = Some(PxDefaultSimulationFilterShader); //! //! let scene = PxPhysics_createScene_mut(physics, &scene_desc); //! //! // Your physics simulation goes here //! } //! ``` //! //! ## Examples //! //! ### [Ball](examples/ball.rs) //! //! A simple example to showcase how to use physx-sys. It can be run with `cargo run --examples ball`. //! //! ``` //! o //! //! o //! o //! //! o //! ooooooooo //! o oo oo //! o o //! o o o //! o oo //! o o o //! o ooooooo //! o o oo oo //! o o o oo oo //! o o o o ooooooooo //! o o o oo oooooooooo oo //! //! ``` //! //! ## How it works //! //! The binding is generated using a custom C++ app written against clang's //! [libtooling](https://clang.llvm.org/docs/LibTooling.html). It queries the compiler's abstract syntax tree, and maps //! the C++ PhysX functions and types to Rust using heuristics chosen specifically for this SDK. It is not a general //! C++ <-> Rust binding generator, and using it on other projects *will* likely crash and burn. //! //! Since C++ does not have a standardized and stable ABI, it's generally not safe to call it from Rust code; since //! PhysX exposes a C++ interface, we can't use it directly. That's why `physx-sys` generates both a Rust interface as //! well as a plain C wrapper. The C code is compiled into a static library at build time, and Rust then talks to C. //! //! In order to minimize the amount of work required to marshall data between the C wrapper and the original C++ API, we //! generate a **bespoke C wrapper for each build target**. The wrapper is based on metadata about structure layout //! extracted directly from compiling and running a tiny program against the PhysX SDK using the specific C++ compiler //! used in the build process. //! //! The build process comprises a few steps: //! //! 1. The `pxbind` utility uses `clang` to extract metadata about PhysX functions and types, and generates partial //! Rust and C bindings as `physx_generated.hpp` and `physx_generated.rs`. Those contain all function definitions, and //! a small subset of types. It also generates a C++ utility called `structgen` by emitting `structgen.cpp`. //! 2. `structgen` is compiled against the PhysX SDK, and generates all the remaining type wrappers. For each struct, it //! queries the size and offset of its members, and generates `structgen_out.hpp` and `structgen_out.rs`. The types are //! "plain old data" structs which will perfectly match the memory layout of the C++ types. //! 3. All the generated C types are compiled together to form `physx_api`, a static library for Rust to link with. //! 4. The Rust wrapper is compiled, and linked with PhysX and the C wrapper. //! //! Steps *2..4* are performed completely automatically from within `build.rs`, while step *1* is only necessary when //! upgrading the PhysX SDK or modifying the generator. As such, building and running `pxbind` is a manual task, and is //! currently only supported on \*nix systems. //! //! ## License //! //! Licensed under either of //! //! * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) //! * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) //! //! at your option. //! //! Note that the [PhysX C++ SDK](https://github.com/NVIDIAGameWorks/PhysX) has it's //! [own BSD 3 license](https://gameworksdocs.nvidia.com/PhysX/4.1/documentation/physxguide/Manual/License.html) and //! depends on [additional C++ third party libraries](https://github.com/NVIDIAGameWorks/PhysX/tree/4.1/externals). //! //! ### 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. // BEGIN - Embark standard lints v0.2. // do not change or add/remove here, but one can add exceptions after this section // for more info see: <https://github.com/EmbarkStudios/rust-ecosystem/issues/59> #![deny(unsafe_code)] #![warn( clippy::all, clippy::await_holding_lock, clippy::dbg_macro, clippy::debug_assert_with_mut_call, clippy::doc_markdown, clippy::empty_enum, clippy::enum_glob_use, clippy::exit, clippy::explicit_into_iter_loop, clippy::filter_map_next, clippy::fn_params_excessive_bools, clippy::if_let_mutex, clippy::imprecise_flops, clippy::inefficient_to_string, clippy::let_unit_value, clippy::linkedlist, clippy::lossy_float_literal, clippy::macro_use_imports, clippy::map_flatten, clippy::map_unwrap_or, clippy::match_on_vec_items, clippy::match_wildcard_for_single_variants, clippy::mem_forget, clippy::mismatched_target_os, clippy::needless_borrow, clippy::needless_continue, clippy::option_option, clippy::pub_enum_variant_names, clippy::ref_option_ref, clippy::rest_pat_in_fully_bound_structs, clippy::string_to_string, clippy::suboptimal_flops, clippy::todo, clippy::unnested_or_patterns, clippy::unused_self, clippy::verbose_file_reads, future_incompatible, nonstandard_style, rust_2018_idioms )] // END - Embark standard lints v0.2 // crate-specific exceptions: #![allow( unsafe_code, non_upper_case_globals, non_camel_case_types, non_snake_case, clippy::doc_markdown, // TODO: fixup comments and docs (though annoyingly complains about "PhysX") clippy::unreadable_literal, clippy::unused_unit, clippy::upper_case_acronyms )] #[cfg(feature = "structgen")] include!(concat!(env!("OUT_DIR"), "/structgen_out.rs")); #[cfg(all( not(feature = "structgen"), target_os = "linux", target_arch = "x86_64", ))] include!("generated/x86_64-unknown-linux/structgen.rs"); #[cfg(all( not(feature = "structgen"), target_os = "android", target_arch = "aarch64", ))] include!("generated/aarch64-linux-android/structgen.rs"); #[cfg(all( not(feature = "structgen"), target_os = "macos", target_arch = "x86_64", ))] include!("generated/x86_64-apple-darwin/structgen.rs"); #[cfg(all( not(feature = "structgen"), target_os = "macos", target_arch = "aarch64", ))] include!("generated/aarch64-apple-darwin/structgen.rs"); #[cfg(all( not(feature = "structgen"), target_os = "windows", target_arch = "x86_64", target_env = "msvc", ))] include!("generated/x86_64-pc-windows-msvc/structgen.rs"); include!("physx_generated.rs"); use std::ffi::c_void; pub const fn version(major: u32, minor: u32, patch: u32) -> u32 { (major << 24) + (minor << 16) + (patch << 8) } pub type CollisionCallback = unsafe extern "C" fn(*mut c_void, *const PxContactPairHeader, *const PxContactPair, u32); pub type TriggerCallback = unsafe extern "C" fn(*mut c_void, *const PxTriggerPair, u32); pub type ConstraintBreakCallback = unsafe extern "C" fn(*mut c_void, *const PxConstraintInfo, u32); pub type WakeSleepCallback = unsafe extern "C" fn(*mut c_void, *const *const PxActor, u32, bool); pub type AdvanceCallback = unsafe extern "C" fn(*mut c_void, *const *const PxRigidBody, *const PxTransform, u32); // Function pointers in Rust are normally not nullable (which is why they don't require unsafe to call) // but we need them to be, so we simply wrap them in Option<>. An Option<funcptr> is luckily represented // by the compiler as a simple pointer with null representing None, so this is compatible with the C struct. #[repr(C)] pub struct SimulationEventCallbackInfo { // Callback for collision events. pub collision_callback: Option<CollisionCallback>, pub collision_user_data: *mut c_void, // Callback for trigger shape events (an object entered or left a trigger shape). pub trigger_callback: Option<TriggerCallback>, pub trigger_user_data: *mut c_void, // Callback for when a constraint breaks (such as a joint with a force limit) pub constraint_break_callback: Option<ConstraintBreakCallback>, pub constraint_break_user_data: *mut c_void, // Callback for when an object falls asleep or is awoken. pub wake_sleep_callback: Option<WakeSleepCallback>, pub wake_sleep_user_data: *mut c_void, // Callback to get the next pose early for objects (if flagged with eENABLE_POSE_INTEGRATION_PREVIEW). pub advance_callback: Option<AdvanceCallback>, pub advance_user_data: *mut c_void, } impl Default for SimulationEventCallbackInfo { fn default() -> Self { Self { collision_callback: None, collision_user_data: std::ptr::null_mut(), trigger_callback: None, trigger_user_data: std::ptr::null_mut(), constraint_break_callback: None, constraint_break_user_data: std::ptr::null_mut(), wake_sleep_callback: None, wake_sleep_user_data: std::ptr::null_mut(), advance_callback: None, advance_user_data: std::ptr::null_mut(), } } } /// return 0 = `PxQueryHitType::eNONE` /// return 1 = `PxQueryHitType::eTOUCH` /// return 2 = `PxQueryHitType::eBLOCK` pub type RaycastHitCallback = unsafe extern "C" fn( *const PxRigidActor, *const PxFilterData, *const PxShape, hit_flags: u32, *const c_void, ) -> u32; #[repr(C)] pub struct FilterShaderCallbackInfo { pub attributes0: u32, pub attributes1: u32, pub filterData0: PxFilterData, pub filterData1: PxFilterData, pub pairFlags: *mut PxPairFlags, pub constantBlock: *const std::ffi::c_void, pub constantBlockSize: u32, } pub type SimulationFilterShader = unsafe extern "C" fn(*mut FilterShaderCallbackInfo) -> u16; pub type AllocCallback = unsafe extern "C" fn(u64, *const c_void, *const c_void, u32, *const c_void) -> *mut c_void; pub type DeallocCallback = unsafe extern "C" fn(*const c_void, *const c_void); extern "C" { pub fn physx_create_foundation() -> *mut PxFoundation; pub fn physx_create_foundation_with_alloc( allocator: *mut PxDefaultAllocator, ) -> *mut PxFoundation; pub fn physx_create_physics(foundation: *mut PxFoundation) -> *mut PxPhysics; pub fn get_default_allocator() -> *mut PxDefaultAllocator; pub fn get_default_error_callback() -> *mut PxDefaultErrorCallback; /// Destroy the returned callback object using PxQueryFilterCallback_delete. pub fn create_raycast_filter_callback( actor_to_ignore: *const PxRigidActor, ) -> *mut PxQueryFilterCallback; /// Destroy the returned callback object using PxQueryFilterCallback_delete. pub fn create_raycast_filter_callback_func( callback: RaycastHitCallback, userdata: *mut c_void, ) -> *mut PxQueryFilterCallback; pub fn create_alloc_callback( alloc_callback: AllocCallback, dealloc_callback: DeallocCallback, userdata: *mut c_void, ) -> *mut PxAllocatorCallback; pub fn get_alloc_callback_user_data(alloc_callback: *mut PxAllocatorCallback) -> *mut c_void; pub fn get_default_simulation_filter_shader() -> *mut c_void; /// Create a C++ proxy callback which will forward contact events to `Callback`. /// The returned pointer must be freed by calling `destroy_contact_callback` when done using. #[deprecated] pub fn create_contact_callback( callback: CollisionCallback, userdata: *mut c_void, ) -> *mut PxSimulationEventCallback; /// Deallocates the PxSimulationEventCallback that has previously been created #[deprecated()] pub fn destroy_contact_callback(callback: *mut PxSimulationEventCallback); /// New interface to handle simulation events, replacing create_contact_callback. pub fn create_simulation_event_callbacks( callbacks: *const SimulationEventCallbackInfo, ) -> *mut PxSimulationEventCallback; pub fn get_simulation_event_info( callback: *mut PxSimulationEventCallback, ) -> *mut SimulationEventCallbackInfo; pub fn destroy_simulation_event_callbacks(callback: *mut PxSimulationEventCallback); /// Override the default filter shader in the scene with a custom function. /// If call_default_filter_shader_first is set to true, this will first call the /// built-in PhysX filter (that matches Physx 2.8 behavior) before your callback. pub fn enable_custom_filter_shader( scene_desc: *mut PxSceneDesc, shader: SimulationFilterShader, call_default_filter_shader_first: u32, ); }