PxAggregate

Defined in include/PxAggregate.h

class PxAggregate : public PxBase

Class to aggregate actors into a single broad-phase entry.

A PxAggregate object is a collection of PxActors, which will exist as a single entry in the broad-phase structures. This has 3 main benefits:

1) it reduces “broad phase pollution” by allowing a collection of spatially coherent broad-phase entries to be replaced by a single aggregated entry (e.g. a ragdoll or a single actor with a large number of attached shapes).

2) it reduces broad-phase memory usage

3) filtering can be optimized a lot if self-collisions within an aggregate are not needed. For example if you don’t need collisions between ragdoll bones, it’s faster to simply disable filtering once and for all, for the aggregate containing the ragdoll, rather than filtering out each bone-bone collision in the filter shader.

See also

PxActor, PxPhysics.createAggregate

Public Functions

virtual void release() = 0

Deletes the aggregate object.

Deleting the PxAggregate object does not delete the aggregated actors. If the PxAggregate object belongs to a scene, the aggregated actors are automatically re-inserted in that scene. If you intend to delete both the PxAggregate and its actors, it is best to release the actors first, then release the PxAggregate when it is empty.

virtual bool addActor(PxActor &actor, const PxBVH *bvh = NULL) = 0

Adds an actor to the aggregate object.

A warning is output if the total number of actors is reached, or if the incoming actor already belongs to an aggregate.

If the aggregate belongs to a scene, adding an actor to the aggregate also adds the actor to that scene.

If the actor already belongs to a scene, a warning is output and the call is ignored. You need to remove the actor from the scene first, before adding it to the aggregate.

Note

When a BVH is provided the actor shapes are grouped together. The scene query pruning structure inside PhysX SDK will store/update one bound per actor. The scene queries against such an actor will query actor bounds and then make a local space query against the provided BVH, which is in actor’s local space.

Parameters
  • actor[in] The actor that should be added to the aggregate

  • bvh[in] BVH for actor shapes. return true if success

virtual bool removeActor(PxActor &actor) = 0

Removes an actor from the aggregate object.

A warning is output if the incoming actor does not belong to the aggregate. Otherwise the actor is removed from the aggregate. If the aggregate belongs to a scene, the actor is reinserted in that scene. If you intend to delete the actor, it is best to call PxActor::release() directly. That way the actor will be automatically removed from its aggregate (if any) and not reinserted in a scene.

Parameters

actor[in] The actor that should be removed from the aggregate return true if success

virtual bool addArticulation(PxArticulationReducedCoordinate &articulation) = 0

Adds an articulation to the aggregate object.

A warning is output if the total number of actors is reached (every articulation link counts as an actor), or if the incoming articulation already belongs to an aggregate.

If the aggregate belongs to a scene, adding an articulation to the aggregate also adds the articulation to that scene.

If the articulation already belongs to a scene, a warning is output and the call is ignored. You need to remove the articulation from the scene first, before adding it to the aggregate.

Parameters

articulation[in] The articulation that should be added to the aggregate return true if success

virtual bool removeArticulation(PxArticulationReducedCoordinate &articulation) = 0

Removes an articulation from the aggregate object.

A warning is output if the incoming articulation does not belong to the aggregate. Otherwise the articulation is removed from the aggregate. If the aggregate belongs to a scene, the articulation is reinserted in that scene. If you intend to delete the articulation, it is best to call PxArticulationReducedCoordinate::release() directly. That way the articulation will be automatically removed from its aggregate (if any) and not reinserted in a scene.

Parameters

articulation[in] The articulation that should be removed from the aggregate return true if success

virtual PxU32 getNbActors() const = 0

Returns the number of actors contained in the aggregate.

You can use getActors() to retrieve the actor pointers.

See also

PxActor getActors()

Returns

Number of actors contained in the aggregate.

virtual PxU32 getMaxNbActors() const = 0

Retrieves max amount of actors that can be contained in the aggregate.

See also

PxPhysics::createAggregate()

Returns

Max actor size.

virtual PxU32 getMaxNbShapes() const = 0

Retrieves max amount of shapes that can be contained in the aggregate.

See also

PxPhysics::createAggregate()

Returns

Max shape size.

virtual PxU32 getActors(PxActor **userBuffer, PxU32 bufferSize, PxU32 startIndex = 0) const = 0

Retrieve all actors contained in the aggregate.

You can retrieve the number of actor pointers by calling getNbActors()

See also

PxShape getNbShapes()

Parameters
  • userBuffer[out] The buffer to store the actor pointers.

  • bufferSize[in] Size of provided user buffer.

  • startIndex[in] Index of first actor pointer to be retrieved

Returns

Number of actor pointers written to the buffer.

virtual PxScene *getScene() = 0

Retrieves the scene which this aggregate belongs to.

See also

PxScene

Returns

Owner Scene. NULL if not part of a scene.

virtual bool getSelfCollision() const = 0

Retrieves aggregate’s self-collision flag.

Returns

self-collision flag

virtual bool setEnvironmentID(PxU32 envID) = 0

Sets the environment ID for this aggregate.

The environment ID is an extra built-in filter group for the GPU broadphase. Aggregates will only collide with actors or aggregates that have the same environment ID.

The default value is PX_INVALID_U32. Aggregates with this ID will collide with other actors or aggregates, regardless of which environment they are a part of.

The environment ID must be set before adding the aggregate to a scene, and cannot change while the aggregate is in the scene.

If it is not PX_INVALID_U32, the environment ID must be smaller than 1<<24, i.e. the system does not support more than 1<<24 environments.

Aggregated actors must have a default environment ID (PX_INVALID_U32). The environment ID of the aggregate is used in the broadphase, not the environment IDs from aggregated actors.

Default: PX_INVALID_U32

See also

getEnvironmentID()

Note

This is not available for CPU broadphases.

Parameters

envID[in] Environment ID for this aggregate.

Returns

True if success.

virtual PxU32 getEnvironmentID() const = 0

Returns the environment ID for this aggregate.

See also

setEnvironmentID()

Returns

Environment ID for this aggregate.

inline virtual const char *getConcreteTypeName() const final override

Returns string name of dynamic type.

Returns

Class name of most derived type of this object.

template<class T>
inline T *is()
template<class T>
inline const T *is() const
inline PxType getConcreteType() const

Returns concrete type of object.

See also

PxConcreteType

Returns

PxConcreteType::Enum of serialized object

inline void setBaseFlag(PxBaseFlag::Enum flag, bool value)

Set PxBaseFlag

Parameters
  • flag[in] The flag to be set

  • value[in] The flags new value

inline void setBaseFlags(PxBaseFlags inFlags)

Set PxBaseFlags

See also

PxBaseFlags

Parameters

inFlags[in] The flags to be set

inline PxBaseFlags getBaseFlags() const

Returns PxBaseFlags.

See also

PxBaseFlags

Returns

PxBaseFlags

inline virtual bool isReleasable() const

Whether the object is subordinate.

A class is subordinate, if it can only be instantiated in the context of another class.

See also

PxSerialization::isSerializable

Returns

Whether the class is subordinate

Public Members

void *userData

user can assign this to whatever, usually to create a 1:1 relationship with a user object.

Protected Functions

inline PxAggregate(PxType concreteType, PxBaseFlags baseFlags)
inline PxAggregate(PxBaseFlags baseFlags)
inline virtual ~PxAggregate()
inline virtual bool isKindOf(const char *name) const

Returns whether a given type name matches with the type of this instance.

template<class T>
inline bool typeMatch() const

Protected Attributes

PxType mConcreteType
PxBaseFlags mBaseFlags
PxU32 mBuiltInRefCount