Function physx_sys::PxScene_setDominanceGroupPair_mut

pub unsafe extern "C" fn PxScene_setDominanceGroupPair_mut(
    self_: *mut PxScene,
    group1: u8,
    group2: u8,
    dominance: *const PxDominanceGroupPair
)

Specifies the dominance behavior of contacts between two actors with two certain dominance groups.

It is possible to assign each actor to a dominance groups using PxActor::setDominanceGroup.

With dominance groups one can have all contacts created between actors act in one direction only. This is useful, for example, if you want an object to push debris out of its way and be unaffected,while still responding physically to forces and collisions with non-debris objects.

Whenever a contact between two actors (a0, a1) needs to be solved, the groups (g0, g1) of both actors are retrieved. Then the PxDominanceGroupPair setting for this group pair is retrieved with getDominanceGroupPair(g0, g1).

In the contact, PxDominanceGroupPair::dominance0 becomes the dominance setting for a0, and PxDominanceGroupPair::dominance1 becomes the dominance setting for a1. A dominanceN setting of 1.0f, the default, will permit aN to be pushed or pulled by a(1-N) through the contact. A dominanceN setting of 0.0f, will however prevent aN to be pushed by a(1-N) via the contact. Thus, a PxDominanceGroupPair of (1.0f, 0.0f) makes the interaction one-way.

The matrix sampled by getDominanceGroupPair(g1, g2) is initialised by default such that:

if g1 == g2, then (1.0f, 1.0f) is returned if g1 < g2, then (0.0f, 1.0f) is returned if g1 > g2, then (1.0f, 0.0f) is returned

In other words, we permit actors in higher groups to be pushed around by actors in lower groups by default.

These settings should cover most applications, and in fact not overriding these settings may likely result in higher performance.

It is not possible to make the matrix asymetric, or to change the diagonal. In other words:

it is not possible to change (g1, g2) if (g1==g2) if you set

(g1, g2) to X, then (g2, g1) will implicitly and automatically be set to ~X, where:

~(1.0f, 1.0f) is (1.0f, 1.0f) ~(0.0f, 1.0f) is (1.0f, 0.0f) ~(1.0f, 0.0f) is (0.0f, 1.0f)

These two restrictions are to make sure that contacts between two actors will always evaluate to the same dominance setting, regardless of the order of the actors.

Dominance settings are currently specified as floats 0.0f or 1.0f because in the future we may permit arbitrary fractional settings to express ‘partly-one-way’ interactions.

Sleeping: Does NOT wake actors up automatically.