Defined in include/PxBroadPhase.h

class PxBroadPhaseRegions

Broadphase regions.

An API to manage broadphase regions. Only needed for the MBP broadphase (PxBroadPhaseType::eMBP).

Public Functions

virtual PxU32 getNbRegions() const = 0

Returns number of regions currently registered in the broad-phase.


Number of regions

virtual PxU32 getRegions(PxBroadPhaseRegionInfo *userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Gets broad-phase regions.

  • userBuffer – [out] Returned broad-phase regions

  • bufferSize – [in] Size of provided userBuffer.

  • startIndex – [in] Index of first desired region, in [0 ; getNbRegions()[


Number of written out regions.

virtual PxU32 addRegion(const PxBroadPhaseRegion &region, bool populateRegion, const PxBounds3 *bounds, const float *distances) = 0

Adds a new broad-phase region.

The total number of regions is limited to PxBroadPhaseCaps::mMaxNbRegions. If that number is exceeded, the call is ignored.

The newly added region will be automatically populated with already existing objects that touch it, if the ‘populateRegion’ parameter is set to true. Otherwise the newly added region will be empty, and it will only be populated with objects when those objects are added to the simulation, or updated if they already exist.

Using ‘populateRegion=true’ has a cost, so it is best to avoid it if possible. In particular it is more efficient to create the empty regions first (with populateRegion=false) and then add the objects afterwards (rather than the opposite).

Objects automatically move from one region to another during their lifetime. The system keeps tracks of what regions a given object is in. It is legal for an object to be in an arbitrary number of regions. However if an object leaves all regions, or is created outside of all regions, several things happen:

  • collisions get disabled for this object

  • the object appears in the getOutOfBoundsObjects() array

If an out-of-bounds object, whose collisions are disabled, re-enters a valid broadphase region, then collisions are re-enabled for that object.

See also

PxBroadPhaseRegion getOutOfBoundsObjects()

  • region – [in] User-provided region data

  • populateRegion – [in] True to automatically populate the newly added region with existing objects touching it

  • bounds – [in] User-managed array of bounds

  • distances – [in] User-managed array of distances


Handle for newly created region, or 0xffffffff in case of failure.

virtual bool removeRegion(PxU32 handle) = 0

Removes a broad-phase region.

If the region still contains objects, and if those objects do not overlap any region any more, they are not automatically removed from the simulation. Instead, the PxBroadPhaseCallback::onObjectOutOfBounds notification is used for each object. Users are responsible for removing the objects from the simulation if this is the desired behavior.

If the handle is invalid, or if a valid handle is removed twice, an error message is sent to the error stream.


handle – [in] Region’s handle, as returned by addRegion


True if success

virtual PxU32 getNbOutOfBoundsObjects() const = 0
virtual const PxU32 *getOutOfBoundsObjects() const = 0

Protected Functions

inline PxBroadPhaseRegions()
inline virtual ~PxBroadPhaseRegions()