I set this repo to public after working on it for a quite a while now with the intent to properly open source it at some point.

I'm not too happy with the design of this first iteration, so I decided to create this issue in order to track the rewrite process and write down what I've learnt from the underlying C API, its idioms, and how they could translate into a nicer, safe, idiomatic, Rust wrapper...

API coverage

The wrapper should provide coverage to most (not all) API functions. I thing these are the most important ones (list is still a work in progress):

(Everything missing is still accessible through the raw unsafe FFI bindings)

World, bodies, & collisions

• NewtonCreate
• NewtonCreateDynamicBody
• NewtonCreateKinematicBody
• NewtonCreateBox
• NewtonCreateChamferCylinder
• NewtonCreateCapsule
• NewtonCreateCone
• NewtonCreateCylinder
• NewtonCreateNull
• NewtonCreateSphere
• NewtonCreateCompoundCollision
• NewtonCreateHeightFieldCollision

(all functions to modify physical properties and forces are also included)

Collision detection

• NewtonWorldConvexCast
• NewtonWorldRayCast

Materials

Newton models material interactions as a fully connected graph.

• NewtonMaterialCreateGroupID

Iterators

It is very easy to raise a core dump or segmentation fault error if bodies or materials are destroyed (freed) while using these iterator functions:

• NewtonWorldGetFirstBody
• NewtonWorldGetNextBody
• NewtonWorldGetFirstMaterial
• NewtonWorldGetNextMaterial

Simulation step

• NewtonUpdate
• NewtonUpdateAsync (Simulation can run in multiple threads, but these are not managed by Rust)

Callbacks

newton-dynamics is callback based. Most types have an userdata void* pointer to store application state code. I think these are the most useful callbacks:

• NewtonBodyGetForceAndTorqueCallback
• NewtonBodySetTransformCallback

(Other callbacks that track objects life-cycle might be useful for internal use by the wrapper)

Closures

The C API uses function pointers as closures in some of the API calls. These can be implemented using regular Rust closures (FnMut):

• NewtonWorldForEachBodyInAABBDo
• NewtonCollisionForEachPolygonDo

Mutability & borrowing

Because Bodies, Collisions, and World are implemented as smart pointers (they are self-owned), the first iteration of the wrapper used dynamic borrow checking, through the use of RwLock. Because of this decission, in order to mutate a body, you need to acquire locks for both the body and the world:

let world = ...;
let body = ...;

let mut body = body.write()?;
let mut world = world.write()?; // Runtime error: world is already locked by the previous line

This design decision might change or not depending on how handling of objects ends up being implemented in the next iteration.