Foundation and Common

• PxCreatePlane used to take an (n,d) pair, now it takes a PxPlane. The first three elements are the same, but the d parameter must be negated.
• PxStream has been split into PxOutputStream and PxInputStream, and these must be implemented anew by the user if APIs are used that need them.
• There are new helpers PxShortestRotation, and PxDiagonalize.
• The serialization API ( PxCollection, PxSerializable) has seen major changed with work still ongoing. As this API is not yet finalized we cannot provide migration information yet.

Geometry

We added a number of new capabilities to the geometry library, but existing code should not need to be adapted. New things include:

• PxTransformFromSegment
• PxConvexMesh::getLocalBounds
• PxTriangleMesh::getLocalBounds
• PxHeightField::modifySamples, getTriangleNormal
• PxMeshQuery
• PxTransformFromPlaneEquation, PxPlaneEquationFromTransform
• PxTriangle

Core PhysX

• The way to create the Physics SDK has changed. The PxCreatePhysics call now should be preceeded by a call to PxCreateFoundation, which takes the allocator and error callback parameters that used to go into createPhysics. Instead PxCreatePhysics now takes a profile zone manager created using PxProfileZoneManager::createProfileZoneManager. It is important to create and pass this profile zone manager in order to set up the Visual Remote Debugger for profiling.
• Perhaps the most fundamental change for the API is the rewrite of the type casting system. The PxActor::is(PxActorType) style functions are replaced with isKindOf(const char * typeName), const char* getConcreteTypeName(), is<Class>() template functions (e.g. is<PxCloth>()), and specially named inline functions (e.g. PxActor::isCloth()).
• PxAggregate::getMaxSize has been renamed to getMaxNbActors, and getCurrentSize has been renamed getNbActors for clarity.
• The PxBatchQuery raycast parameters have been reordered.
• There is a new user implemented interface class PxConstraintVisualizer, and the PxConstraintVisualize callback function now takes one of those instead of a PxRenderBuffer.
• PxContactPoint::featureIndex0/1 has been renamed internalFaceIndex0/1, and PxContactSet::getFeatureIndex0/1 has been renamed getInternalFaceIndex0/1.
• The class PxContactStreamIterator has been deleted, and replaced by a completely rewritten contact query mechanism. It is best if the user reads up on the new API and implements it from scratch, it is quite dissimilar to the previous incarnation. See the class PxSimulationEventCallback and in particular ::onContact to start to refactor code.
• The empty default implementations of event callbacks have been removed to prevent confusion. This means that users must provide their own (blank) implementations of all events in a user class they subclass, even ones they are not interested in. Providing default blank implementations in the SDK exposed the user to hard to find bugs if we changed an event signature from one release to another.
• Users of continuous collision detection should note that PxPairFlag::eSWEPT_CONTACT_GENERATION and PxPairFlag::eSWEPT_INTEGRATION_FULL no longer exist. We have rewritten the CCD algorithm such that it no longer has its own contact generation, and it no longer supports angular sweeps. Hence use of eSWEPT_CONTACT_GENERATION should simply be removed, and eSWEPT_INTEGRATION_FULL should be replaced with eSWEPT_INTEGRATION_LINEAR.
• RbPairStatsType::eSWEPT_CONTACT_PAIRS removed together with swept contact generation.
• We also stopped supporting anisotropic friction, so PxMaterialFlag, PxCombineMode, and all function calls of PxMaterial relating to anisotropic friction have been removed. Users should remove the corresponding calls.
• PxPhysics::getMetaData been changed into PxGetSDKMetaData to make it be an optionally linkable component.
• PxPhysics::releaseUserReferences, releaseCollection deprecated. Users should simply call release() on the appropriate object.
• PxPhysics::addCollection now takes a reference parameter instead of a pointer to indicate that a null pointer is not an option.
• The functions PxPhysics::createParticleSystem and createParticleFluid take parameters directly rather than descriptors.
• The functions PxPhysics::createTriangleMesh, createConvexMesh, and the stream version of createClothFabric now take a PxInputStream rather than a general PxStream, which has been removed. To migrate these function calls, the user must implement the new PxInputStream class.
• The PxPhysics::createClothFabric creation parameters for the non-stream version have changed a lot. The number nbFibers and nbIndices parameters have been removed because it always equals nbSets (which is new). particleIndices has been renamed indices. restValues and nbRestValues are newly added. None of the parameters may be NULL.
• PxPhysics::getProfileZoneManager returns a pointer instead of a reference.
• PxRigidDynamic::moveKinematic has been renamed to setKinematicTarget.
• The prototype of PxGetFoundation has been moved from the Physics API to the Foundation API.
• PxScene::overlapAny has been removed. Use instead overlapMultiple with hitBufferSize = 1.
• The pruning structure options PxPruningStructure::eOCTREE and eQUADTREE have been removed, because they are now in general inferior in performance to the AABB_TREE options. The PxSceneDesc::maxBounds, upAxis, and subdivisionLevel properties were also removed as part of this because they were only used for these two pruning modes.
• We removed PxScene::getNbAttachments, getAttachments, this was part of the removed deformable simulation feature.
• PxSweepCache is deprecated in this release and will be removed in the next. We found that it provides no significant benefit.

There are also a number of new features:

• There is a new API for optional components: PxRegisterArticulations, PxRegisterPCM, PxRegisterHeightFields, PxCreateBasePhysics, PxGetSDKMetaData. This way some rarely used features can avoid getting linked into the executable on certain platforms.
• There is a new function PxGetPhysics.
• There are new functions PxScene::set/getTimestamp(). Saving and loading the time stamp makes the simulation be more deterministic.
• There are new PxSceneDesc::contactReportStreamBufferSize and PxScene::get/setNbContactDataBlocks, getMaxNbContactDataBlocksUsed functions (and PxSceneDesc::nbContactDataBlocks, maxNbContactDataBlocks) for some advanced memory management possibilities.
• There are new flags PxSceneFlag:: modes eENABLE_ONE_DIRECTIONAL_FRICTION, eENABLE_TWO_DIRECTIONAL_FRICTION, eDISABLE_CONTACT_REPORT_BUFFER_RESIZE, eENABLE_PCM, to enable a new friction model and a new contact generation algorithm, among other things.
• The new flag PxSceneQueryFlag::eINITIAL_OVERLAP_KEEP controls whether how scene query should behave when it comes to initial overlaps.
• PxShape::getGeometry is a more general way to retrieve shape geometry.

Cooking

• The biggest change to cooking is that the functions PxCooking::cookTriangleMesh, cookConvexMesh, and cookClothFabric now take the new class PxOutputStream not and not a PxStream as before. Users must implement a subclass of PxOutputStream. Note that we provide a default implementation in the form of PxDefaultFileOutputStream.
• The ConvX tool has been replaced by the new class PxBinaryConverter (see PxCooking::createBinaryConverter) function which works the same way to convert binary serialized files between platforms.
• The PxCreateCooking function now takes a foundation reference instead of a pointer to denote that a null pointer value is not valid.

Deformables

• The deformables feature that has appeared as deprecated in the early versions of PhysX 3.x has been removed. We decided to reboot deformables as the more streamlined and simplified Cloth feature.

Particles

• The only significant change to the particles API is that it no longer uses descriptors for creation. The classes PxParticleBaseDesc, and PxParticleFluidDesc have been deleted, and the create functions take the parameters immediately.
• There are also two new functions: PxParticleBase::setParticleReadDataFlag and PxParticleFluid::setRestParticleDistance.

Cloth

• The function PxCloth::setParticles can now also update the previous particle state. This lets the user easily define the velocity of the particles as the difference between the two positions. The cloth simulation really does not store velocities explicitly, but rather only two consecutive positions, hence this somewhat odd interface.

• PxCloth::getCollisionData now also takes a planesBuffer, and a convexMaskBuffer. These buffers retrieve additional collision information, but passing NULL should make it possible to ignore them.

• PxClothFabric::scale/getRestlengths have been renamed to scale/getRestvalues.

• Aside from this, there are a number of new features:

  • There is a new struct PxClothParticleSeparationConstraint (see also PxCloth::get/setSeparationConstraints, getNbSeparationConstraints). This is a new separations constraints feature that enforces each particle to stay inside a sphere.
  • The new function PxCloth::clearInterpolation lets the user easily set the effective velocity of particles to zero. This should be called whenever the character animation is discontinuous.
  • There are new PxCloth::get/setParticleAccelerations, getNbParticleAccelerations functions that effectively permit the user to apply forces to individual particles.
  • New PxCloth::getNb/set/remove/addCollisionPlane(s) and PxCloth::getNb/remove/addCollisionConvex permit the definition of convex shapes built from planes.
  • There are a bunch of new cloth properties to experiment with such as PxCloth::get/setInertiaScale, PxCloth::get/setFrictionCoefficient, PxCloth::get/setDragCoefficient, PxCloth::get/setCollisionMassScale.
  • The PxClothFabric now exposed a number of new internal arrays with getter functions.
  • The new PxClothMeshVertFlag and PxClothMeshDesc::vertFlags lets attached vertices be defined for the cooker from which it will try to generate zero stretch constraint chains. This feature is still experimental and these settings are not required for general vertex attachment.

Extensions

• We provide new default implementations for user implemented functionality in the form of PxDefaultMemoryOutputStream, PxDefaultMemoryInputData, PxDefaultFileOutputStream, PxDefaultFileInputData.
• The class PxDefaultSimulationFilterShader was significantly extended with set/PxGetGroupCollisionFlag, set/PxGetGroup, set/PxGetFilterOps, get/PxSetFilterBool, get/PxsetFilterConstants, and set/PxGetGroupsMask, this should implement 2.8 style group filtering for users migrating from that old version.
• PxDumpMetaData now dumps to a stream, not to a file, for increased flexibility.
• New versions of PxRigidBodyExt::updateMassAndInertia, and setMassAndUpdateInertia were added that permit specifying individual shape densities, not just a uniform density. Old versions are still available for uniform density.
• The new helpers PxCloneStatic, PxCloneDynamic, and PxScaleRigidActor have been added.

Virtual Remote Debugger Interface

• The function PxVisualDebuggerExt::connect has been renamed createConnection.
• PxVisualDebugger::updateCamera now takes names for cameras directly and it is not necessary to allocate cameras. Unseen names passed to the function will automatically be registered.
• Added new functions PxVisualDebugger::setVisualizeConstraints, isVisualizingConstraints to let user determine if joints should be visualized in PVD.
• The function PxVisualDebugger::setJointVisualizationScale has been deleted. Joints can now be scaled in PVD using the Preferences -> Gizmo Scale setting.

Character Controller

• PxBoxControllerDesc representation changed from an extents vector to separate floats, which are hopefully more intuitive. Applicable accessors have been renamed.
• The default mode of the capsule controller was changed from PxCapsuleClimbingMode::eCONSTRAINED to PxCapsuleClimbingMode::eEASY. This is to be consistent with the default behavior of e.g. box controllers, which are blocked by obstacles greater than the stepOffset. Also, stepOffsets greater than the capsule controller's entire height are now forbidden.
• The PxControllerDesc::upDirection is now a vector rather than a 3 value enum. PxCCTUpAxis has been removed. This enables arbitrary up vectors for character controllers -- they no longer have to be aligned to the world axes. Applicable accessors have been updated.
• The various functions changing the height or radius of a controller do not automatically update the controller's position anymore, as some of them did on the past. There is now a new helper function, PxController::resize(), to do this.
• The function PxController::move now needs the user to pass an elapsed time parameter. This is needed to get proper interactions between the character (may be updated with variable timesteps) and kinematic platforms controlled by the SDK (updated with fixed timesteps). When the character jumps away from a moving kinematic platform, the character controller code needs to compute its velocity. It needs a correct elapsed time value to do that. If the controller being migrated never needs to jump away from moving kinematic platforms, this parameter is not used, and an arbitrary value may be passed.
• The function PxController::move also needs a a PxControllerFilters, a new class. This stores all kinds of filtering information to filter out collisions with potentially colliding objects, including a filter callback. This class has a constructor to initialize itself to defaults, one can just pass a default object to get default behavior.
• Finally the function PxController::move now also takes an optional PxObstacleContext, which you can leave NULL to keep your prior behavior. This object could be used to define obstacles like invisible walls for the character controller that you do not need to add to the simulation for efficiency reasons.
• Some versions of PhysX 3.1 still shipped with a dynamic character controller which admittedly did not work as well as the kinematic controller, and there was a lot of overlap between the functionality. We decided to stop maintaining this code path and it was removed from 3.2. The great number of improvements to the kinematic character controller should make it possible for applications to migrate over to it.
• There is a new function PxControllerManager::computeInteractions(elapsedTime). This is needed to properly resolve interactions between characters when they overlap (which can happen from time to time, for various reasons). One can call this pretty much at any time, once per frame. It needs a proper elapsed time between frames value here so that interactions are resolved in a way that do not depend on the frame rate. Nothing bad would happen if one passed a fixed time value, though. If there is only one character in the scene, it is guaranteed that characters will never overlap, then this function need not be called.

Meanwhile a great many new features have been added to the character controller:

• See the new PxCCTNonWalkableMode and PxController::get/setNonWalkableMode() for two options for how to handle non-walkable areas.
• See the new PxControllerState, and PxController::getState(PxControllerState) for basic state information like the currently touching shape, what the controller is standing on, etcetera.
• See the new PxControllerStats and PxController::getStats(PxControllerStats) for simulation statistics like the number of collision iterations performed.
• See the new new PxControllerManager::createObstacleContext() (and also PxControllerObstacleHit and PxUserControllerHitReport::onObstacleHit) for a way to collide with user defined obstacles outside of the simulation scene. This is covered in more detail on the character controller page of this manual.
• The class PxControllersHit now has contact point information between controllers (position, normal).
• We added PxControllerDesc::density, and scaleCoeff variables to let user have more control over kinematic actor that character controller creates.
• The new PxControllerDesc::volumeGrowth lets the user control caching of geometry to improve performance.
• The new PxControllerBehaviorCallback (see also PxControllerDesc::behaviorCallback) lets the user set behavior flags for object interaction to specify whether the controller should ride along on the object it stands on or slide along its surface.
• There is a new PxControllerDesc::groupsBitmask (and PxController::get/setGroupsBitmask()) to control collision filtering.
• Convenience functions like PxController::getScene() and the new PxController::getFootPosition() to retrieve foot position (bottom point of shape) are now available.
• There is the new PxControllerDebugRenderFlags (see also PxControllerManager::setDebugRenderingFlags()) to control what geometry to send to debug renderer, plus PxControllerManager::getRenderBuffer() to get debug render buffer.
• There is a new PxExtendedVec3::toVec3() to convert an extended precision position to a regular PxVec3.