Migrating From PhysX SDK 5.1 to 5.2

This guide highlights all significant parts of the API that have changed in the last release. An application with a working integration of the older version of PhysX should be able to easily migrate to the newer version by following these pointers.

Simulation

The API for the filter callback changed slightly. The pairID parameter in PxSimulationFilterCallback::pairFound(), PxSimulationFilterCallback::pairLost() and PxSimulationFilterCallback::statusChange() is now a PxU64 instead of a PxU32. Please adjust your code accordingly. Make sure your filter callback implementation can be safely called from multiple threads.
PxBVHStructure has been removed. Use PxBVH.
PxBVHStructureDesc has been removed. Use PxBVHDesc.
PxPhysics::createBVHStructure() has been removed, replace with PxPhysics::createBVH().
PxPhysics::getNbBVHStructures() has been removed, replace with PxPhysics::getNbBVHs().
The signature for PxPhysics::createAggregate() has changed. Use maxShape = PX_MAX_U32 for the new parameter to get the same behavior as before.
PxSceneFlag::eSUPPRESS_READBACK is now immutable. Any code changing the flag after scene creation will not work anymore.
PxMassModificationProps was deprecated and has been removed. The replacement is PxConstraintInvMassScale.
PxRegisterImmediateArticulations, PxRegisterArticulationsReducedCoordinate, PxRegisterHeightFields, PxCreateBasePhysics have been removed. Articulations and heightfields are now always enabled.
Deprecated passthrough functions in PxShape such as getGeometryType() and the specialized get<geomType>Geometry() were removed. Calls to these functions should be replaced by accessing the underlying geometry directly with getGeometry().

Cooking

The deprecated PxCooking class has been removed. Use the standalone “immediate cooking” functions instead (e.g. PxCookBVH, PxCreateBVH…). Generally speaking just replace “PxCooking::Function()” with “PxFunction()”.

Articulations

The PxArticulationJointReducedCoordinate limit and drive setters and getters with individual parameters were deprecated and have now been removed. Using the parameter struct versions instead is straightforward:

// replace
joint->setLimit(axis, low, high);

// with
joint->setLimitParams(axis, PxArticulationLimit(low, high));

// and instead of
PxReal low, high;
joint->getLimit(axis, low, high);
// use
PxArticulationLimit limit = joint->getLimitParams(axis);
PxReal low = limit.low;
PxReal high = limit.high;

The drive getters and setters are replaced analogously.

Joints

The joint projection feature was deprecated and has now been removed. There is no direct replacement, so the corresponding code in your project should be removed. A potential alternative to this feature is to increase the number of (position) solver iterations for jointed objects that previously used projection.
The joint contact distance feature was deprecated and has now been removed. The corresponding code in your project should be removed. Joint limits are now always active, which can potentially come with a minor performance hit, but increased joint robustness.
The D6 joint’s twist drive was using the wrong actor’s axis (B instead of A). This has been fixed, and it could affect joint setups in existing scenes. To fix this in existing content it might be enough to flip the joint frames of involved actors, but this may not be possible depending on which other features (joint limits, etc) have been setup for the same joint. In the worst case it might be necessary to re-tune these joints.

Some internal joint functions now use PxTransform32 instead of PxTransform. The code for custom joints might need to be updated. For example:

//PxTransform cA2w, cB2w;       // before
PxTransform32 cA2w, cB2w;       // after
joint::computeJointFrames(cA2w, cB2w, data, body0Transform, body1Transform);

//PxTransform cA2w, cB2w;       // before
PxTransform32 cA2w, cB2w;       // after
joint::ConstraintHelper ch(constraints, invMassScale, cA2w, cB2w, body0WorldOffset, data, bA2w, bB2w);

Vehicles

PxVehiclePhysXRoadGeometryQueryParams::filterData has been renamed to defaultFilterData since there is now the new member filterDataEntries in that struct to give the option to define wheel specific filter data. It is important to set filterDataEntries=NULL to match the behavior of the previous SDK version (in which case defaultFilterData will be used for all wheels). As a consequence, the method PxVehiclePhysXRoadGeometryQueryUpdate() has been adjusted too (see PxVehiclePhysXRoadGeometrySceneQueryComponent::update() for an example of how the parameters are now passed into that method).

Immediate mode

The following deprecated types have been removed and should be replaced with these other types:
- PxFeatherstoneArticulationJointData (deprecated, replace it with PxArticulationJointDataRC)
- PxFeatherstoneArticulationLinkData (deprecated, replace it with PxArticulationLinkDataRC)
- PxFeatherstoneArticulationData (deprecated, replace it with PxArticulationDataRC)
- PxMutableLinkData (deprecated, replace it with PxArticulationLinkMutableDataRC)
- PxLinkData (deprecated, replace it with PxArticulationLinkDerivedDataRC)

Scene queries

Deprecated PxBVH::raycast(), PxBVH::sweep() and PxBVH::overlap() functions have been removed. Use the new versions with callbacks.
The signature for PxQueryFilterCallback::postFilter() has changed. It is possible that existing PxQueryFilterCallback objects that did not implement this postFilter function will stop compiling. In that case, simply add the following function to your callback:
```
virtual PxQueryHitType::Enum postFilter(const PxFilterData&, const PxQueryHit&, const PxShape*, const PxRigidActor*)
{
        return PxQueryHitType::eBLOCK;
}
```
The deprecated PxGeometryQuery::getWorldBounds() function has been removed. Please use PxGeometryQuery::computeGeomBounds() instead.
A deprecated PxGeometryQuery::raycast() function has been removed. Please use the other function with the same name but a different signature.

Soft Bodies

PxBuffer has been removed. The Softbody interface now exposes direct access to all the GPU data buffers, and it is the user`s responsibility to copy the data from host to device and vice-versa. Examples for the usage of the new interface are provided in the soft body snippets and the soft body extensions (PxSoftBodyExt.h).

Serialization, Binary Platform Conversion

The PhysX serialization feature is being reduced to the current needs of Omniverse Physics.

Xml/RepX Serialization

Xml and RepX Serialization is useful as a version agnostic way of serializing PhysX objects. This format was mainly used to create repro cases and tests. The PhysX Visual Debugger (PVD) - version 2 and 3 - employed RepX/Xml serialization for its internal communication format as well as for providing dumps of the physics state that could be loaded back into the PhysX SDK.

Going forward, the RepX/Xml format is replaced by the USD Physics format. PVD 2/3 are being deprecated and replaced by Omni PVD, which is going to rely on the USD Physics format for PhysX state dumps that can be loaded into PhysX using Omniverse Physics.

Deprecated classes and functions:

PxSerializationRegistry::registerRepXSerializer()
PxSerializationRegistry::unregisterRepXSerializer()
PxSerializationRegistry::getRepXSerializer()
PxRepXSerializer
PxCreateRepXObject()
PX_NEW_REPX_SERIALIZER, PX_DELETE_REPX_SERIALIZER
PxRepXObject
PxRepXInstantiationArgs
PxSerialization::PxXmlMiscParameter
PxSerialization::createCollectionFromXml()
PxSerialization::serializeCollectionToXml()

Binary Platform Conversion

Binary conversion is used to re-target the binary data from one platform to another and to support deterministic binary serialization. Going forward binary data needs to be generated on the platform it is consumed on. Along with binary conversion, the binary meta data is being deprecated as well. The dedicated deterministic serialization functionality is being replaced by the regular binary serialization which is targeted to become deterministic itself.

Deprecated classes and functions:

PxBinaryConverter
PxConverterReportMode
PxGetPhysicsBinaryMetaData()
PxSerialization::serializeCollectionToBinaryDeterministic()
PxSerialization::dumpBinaryMetaData()
PxSerialization::createBinaryConverter()
PxBinaryMetaDataCallback
PxSerializationRegistry::registerBinaryMetaDataCallback()