ParticleSystem.h

Go to the documentation of this file.

/*
Copyright 2007-2025. Algoryx Simulation AB.
 
All AGX source code, intellectual property, documentation, sample code,
tutorials, scene files and technical white papers, are copyrighted, proprietary
and confidential material of Algoryx Simulation AB. You may not download, read,
store, distribute, publish, copy or otherwise disseminate, use or expose this
material unless having a written signed agreement with Algoryx Simulation AB, or having been
advised so by Algoryx Simulation AB for a time limited evaluation, or having purchased a
valid commercial license from Algoryx Simulation AB.
 
Algoryx Simulation AB disclaims all responsibilities for loss or damage caused
from using this software, unless otherwise stated in written agreements with
Algoryx Simulation AB.
*/
 
#ifndef AGX_PARTICLESYSTEM_H
#define AGX_PARTICLESYSTEM_H
 
#include <agx/Referenced.h>
#include <agx/Component.h>
#include <agx/Bound.h>
#include <agx/Physics/ParticleEntity.h>
#include <agx/Physics/ParticlePairContactEntity.h>
#include <agx/Physics/ParticleGeometryContactEntity.h>
#include <agx/Material.h>
#include <agx/Emitter.h>
#include <agxStream/Serializable.h>
#include <agx/Task.h>
#include <agxCollide/Geometry.h>
#include <agxCollide/Space.h>
#include <typeinfo>
#include <agx/Logger.h>
 
namespace agxData
{
  typedef agx::SymmetricPair<agx::Physics::ParticlePtr> ParticlePair;
}
 
namespace agxIO
{
  class Image;
}
 
namespace agxSDK
{
  class Simulation;
}
 
AGX_TYPE_BINDING( agxData::ParticlePair, "ParticlePair" )
 
namespace agx
{
  AGX_DECLARE_POINTER_TYPES( ParticleSystem );
  AGX_DECLARE_VECTOR_TYPES( ParticleSystem );
  typedef agx::SetVector< agx::ref_ptr<agx::ParticleSystem> > ParticleSystemRefSetVector;
 
 
  class AGXPHYSICS_EXPORT ParticleSystem : public Component, public agxStream::Serializable
  {
  public:
    static Model* ClassModel();
 
    virtual bool setUpdateTask( Task* updateTask );
 
    Task* getUpdateTask();
 
    virtual void addNotification( agxSDK::Simulation* simulation );
 
    Physics::ParticlePtr createParticle();
 
    agxData::EntityRange createParticles( size_t numParticles );
 
    Physics::ParticlePtr getParticle( agx::Index particleId );
 
    void destroyParticle( Physics::ParticlePtr particle );
 
    void destroyParticles( const Physics::ParticlePtrVector& particles );
    void destroyParticles( const agxData::EntityPtrVector& particles );
 
    void destroyParticles( agxData::EntityRange particles );
 
    bool removeParticle( Physics::ParticlePtr particle );
 
    bool isValid( Physics::ParticlePtr particle ) const;
 
    bool isParticleGeometryContactValid( Physics::ParticleGeometryContactPtr contact );
 
    bool isParticlePairContactValid( Physics::ParticlePairContactPtr contact );
 
#if (!defined SWIG ) || ( defined SWIGCSHARP || defined SWIGJAVA)
    const agx::Physics::ParticlePtrArray getParticles() const;
    agx::Physics::ParticlePtrArray getParticles();
#endif
 
    agxData::EntityRange spawnParticles( const agx::Vec3Vector& positions );
 
    agx::Physics::ParticlePtrVector spawnParticlesInBound( const agx::Bound3& bound, Real radius, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInBound( const agx::Bound3& bound, agx::Emitter::DistributionTable* sourceTable, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInBoundHCP( const agx::Bound3& bound, Real radius, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInBoundHCP( const agx::Bound3& bound, agx::Emitter::DistributionTable* sourceTable, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInGeometry( agxCollide::Geometry* geometry, Real radius, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInGeometryHCP( agxCollide::Geometry* geometry, Real radius, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInGeometry( agxCollide::Geometry* geometry, agx::Emitter::DistributionTable* sourceTable, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    agx::Physics::ParticlePtrVector spawnParticlesInGeometryHCP( agxCollide::Geometry* geometry, agx::Emitter::DistributionTable* sourceTable, const agx::Vec3& spacing, agx::Real jitterFactor = agx::Real( 0 ) );
 
    void colorParticlesWithLevelsInBound( const agx::Bound3& bound, const agx::Vec4fVector& colors );
 
    size_t getNumParticles() const;
 
    Real getParticleRadius() const;
 
    Real getParticleMass() const;
 
    void setParticleRadius( Real radius, bool updateExistingParticles = false );
 
    virtual void setParticleMass( Real mass, bool updateExistingParticles = false );
 
    void setMaterial( Material* material, bool updateExistingParticles = false );
 
    agx::Physics::ParticlePtrVector removeParticlesOutsideBound( const agx::Bound3& bound );
 
    Material* getMaterial();
    const Material* getMaterial() const;
 
    void evaluateParticleDefaultMass();
 
    agxData::EntityStorage* getParticleStorage();
 
    const agxData::EntityStorage* getParticleStorage() const;
 
    agxData::EntityStorage* getParticlePairContactStorage();
 
    agxData::EntityStorage* getGeometryParticleContactListStorage();
 
    agxData::EntityStorage* getParticleGeometryContactStorage();
 
    agx::Vector<agx::Physics::ParticleGeometryContactPtr> getParticleGeometryContacts();
 
    agx::Vector<agx::Physics::ParticlePairContactPtr> getParticleParticleContacts();
 
    size_t getNumParticleGeometryContacts();
 
    size_t getNumParticleParticleContacts();
 
    size_t getNumActiveParticleParticleContacts();
 
    size_t getNumActiveParticleGeometryContacts();
 
    Vec3 sumForceMagnitudes( RigidBody* body );
 
    // Returns the total contact forces between the particles in the system
    agx::Real getTotalParticleParticleContactForces();
 
    // Returns the total particle-geometry contact forces in the system.
    agx::Real getTotalParticleGeometryContactForces();
 
    // Calculates the total particle volume in the particle system
    agx::Real calculateTotalParticleVolume() const;
 
    agx::Real calculateTotalParticleMass() const;
 
    agx::Real calculateMeanRadius() const;
 
 
    void setEnableCollisions( const agxCollide::Geometry* geometry, bool flag );
 
    bool getEnableCollisions( const agxCollide::Geometry* geometry ) const;
 
    const agxCollide::GeometryHashVector& getDisabledCollisions() const;
 
 
    void addCollisionGroup( agx::UInt32 id, bool updateExistingParticles = true );
    void addCollisionGroup( const agx::Name& id, bool updateExistingParticles = true );
 
    void removeCollisionGroup( agx::UInt32 id, bool updateExistingParticles = true );
    void removeCollisionGroup( const agx::Name& id, bool updateExistingParticles = true );
 
    void addCollisionGroupParticle( agx::UInt32 id, agx::Physics::ParticlePtr ptr );
    void addCollisionGroupParticle( const agx::Name& id, agx::Physics::ParticlePtr ptr );
 
    void removeCollisionGroupParticle( agx::UInt32 id, agx::Physics::ParticlePtr ptr );
    void removeCollisionGroupParticle( const agx::Name& id, agx::Physics::ParticlePtr ptr );
 
    bool hasCollisionGroupParticle( agx::UInt32 id, agx::Physics::ParticlePtr ptr ) const;
    bool hasCollisionGroupParticle( const agx::Name& id, agx::Physics::ParticlePtr ptr ) const;
 
    bool hasCollisionGroup( agx::UInt32 id ) const;
    bool hasCollisionGroup( const agx::Name& id ) const;
 
    agx::Physics::CollisionGroupSetPtr getCollisionGroupSet() const;
 
    const agx::Bound3& getParticleBound();
 
    bool hasCustomBuffer( const agx::String& buffername, const agx::String& formatName );
 
    void addCustomBufferReal( const agx::String& buffername );
 
    void setCustomBufferValueReal( agx::Index id, const agx::String& buffername, agx::Real val );
 
    agx::Real getCustomBufferValueReal( agx::Index id, const agx::String& buffername );
 
    void addCustomBufferInt( const agx::String& buffername );
 
    void setCustomBufferValueInt( agx::Index id, const agx::String& buffername, agx::Int val );
 
    agx::Int getCustomBufferValueInt( agx::Index id, const agx::String& buffername );
 
    void addCustomBufferReal32( const agx::String& buffername );
 
    void setCustomBufferValueReal32( agx::Index id, const agx::String& buffername, agx::Real32 val );
 
    agx::Real32 getCustomBufferValueReal32( agx::Index id, const agx::String& buffername );
 
    void addCustomBufferVec3( const agx::String& buffername );
 
    void setCustomBufferValueVec3( agx::Index id, const agx::String& buffername, agx::Vec3 val );
 
    agx::Vec3 getCustomBufferValueVec3( agx::Index id, const agx::String& buffername );
 
    agx::Physics::ParticlePairContactPtr createParticlePairContact( agx::Physics::ParticlePtr p1, agx::Physics::ParticlePtr p2 );
    agx::Physics::ParticleGeometryContactPtr createParticleGeometryContact( agx::Physics::ParticlePtr particle, agx::Physics::GeometryPtr geometry );
 
    virtual void destroySingleParticle( agx::Index particleId );
 
    virtual void setSingleParticleRadius( agx::Index particleId, agx::Real radius );
 
    virtual agx::Real getSingleParticleRadius( agx::Index particleId );
 
    virtual void setSingleParticleMass( agx::Index particleId, agx::Real mass );
 
    virtual agx::Real getSingleParticleMass( agx::Index particleId );
 
    virtual void setSingleParticleColor( agx::Index particleId, const agx::Vec4f& color );
 
    virtual agx::Vec4f getSingleParticleColor( agx::Index particleId );
 
    virtual void setSingleParticleVelocity( agx::Index particleId, const agx::Vec3& velocity );
 
    virtual agx::Vec3 getSingleParticleVelocity( agx::Index particleId );
 
    virtual agx::Vec3 getSingleParticlePosition( agx::Index particleId );
 
    virtual void setSingleParticleForce( agx::Index particleId, const agx::Vec3& force );
 
    virtual agx::Vec3 getSingleParticleForce( agx::Index particleId );
 
    void applyAirForceDragSimple( agx::Real cd, agx::Real cr );
 
    bool particleExistsWithId( agx::Index id );
 
    agx::Index getParticleIdFromIndex( agx::Index index ) const;
 
    void clearAllParticles();
 
    void updateShouldRender();
 
    void commitColorBuffer();
 
    void commitAllBuffers();
 
    void attach();
 
    void detach();
 
    // private
    void _setGravityTask( Task* task );
    void setSpace( agxCollide::Space* space );
    void clearContactData();
 
 
 
    DOXYGEN_START_INTERNAL_BLOCK()
 
    agx::Vector<agx::Physics::ParticlePtr> createParticlesFromImage( agxIO::Image* image, agx::Real particleRadius, const agx::Vec3& center, agx::Real radiusJitter );
 
    static Vec3u calculateFilledBoundPacking( agx::Vec3Vector& result, agx::Bound3 bound, const agx::Vec3& spacing, agx::Real boundarySpacing = agx::Real( 0 ), agx::Real jitterFactor = agx::Real( 0 ) );
    static size_t calculateFilledBoundPackingHCP( agx::Vec3Vector& result, agx::Bound3 bound, const agx::Vec3& distance, agx::Real boundarySpacing = agx::Real( 0 ), agx::Real jitterFactor = agx::Real( 0 ) );
    static void calculateFilledGeometryPacking( agx::Vec3Vector& result, agxCollide::Geometry* geometry, const agx::Vec3& spacing, agx::Real boundarySpacing = agx::Real( 0 ), agx::Real jitterFactor = agx::Real( 0 ) );
    static void calculateFilledGeometryPackingHCP( agx::Vec3Vector& result, agxCollide::Geometry* geometry, const agx::Vec3& spacing, agx::Real boundarySpacing = agx::Real( 0 ), agx::Real jitterFactor = agx::Real( 0 ) );
 
    template<typename T>
    void addCustomBufferT( const agx::String& name );
 
    template<typename T>
    void setCustomBufferValueT( agx::Index id, const agx::String& buffername, const T valueT );
 
    template<typename T>
    T getCustomBufferValueT( agx::Index id, const agx::String& buffername );
 
    agxSDK::Simulation* getSimulation() const;
 
    agx::Physics::ParticlePtrVector convertRangeToParticlePtrVector( agxData::EntityRange& entityRange );
 
    AGXSTREAM_DECLARE_SERIALIZABLE( agx::ParticleSystem );
 
    DOXYGEN_END_INTERNAL_BLOCK()
 
  protected:
    ParticleSystem( const String& model, Device* device = CpuDevice::instance() );
    ParticleSystem(); // Only used for restoring from serialization
 
    virtual ~ParticleSystem();
 
    void init( bool createMaterial = true );
    void setCollisionGroupSet( agx::Physics::CollisionGroupSetPtr );
    void invalidLicenseCallback();
    TaskGroupRef m_updateTask;
    void setRadiusOnParticles( agxData::EntityRange& entityRange, agx::Real radius );
 
  protected:
    AGX_DECLARE_POINTER_TYPES( MaterialUuidBufferListener );
    class AGXPHYSICS_EXPORT MaterialUuidBufferListener : public agxData::Buffer::EventListener, public agx::Referenced
    {
    public:
      MaterialUuidBufferListener( ParticleSystem* system, agxSDK::Simulation* simulation );
      bool isJournalPlayback();
      void setSimulation( agxSDK::Simulation* sim );
      virtual void updateCallback( agxData::Buffer* buffer ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agx::Index index ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agx::IndexRange range ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agxData::Array< agx::Index > indexSet ) override;
 
    protected:
      virtual ~MaterialUuidBufferListener();
      // Variables
    private:
      agx::observer_ptr<agx::ParticleSystem>  m_system;
      agxSDK::Simulation*                     m_simulation;
    };
 
    AGX_DECLARE_POINTER_TYPES( UpdateRenderingListener );
    class AGXPHYSICS_EXPORT UpdateRenderingListener : public agxData::Buffer::EventListener, public agx::Referenced
    {
    public:
      UpdateRenderingListener( ParticleSystem* system, agxSDK::Simulation* simulation );
      bool isJournalPlayback();
      void setSimulation( agxSDK::Simulation* sim );
      virtual void updateCallback( agxData::Buffer* buffer ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agx::Index index ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agx::IndexRange range ) override;
      virtual void updateCallback( agxData::Buffer* buffer, agxData::Array< agx::Index > indexSet ) override;
 
    protected:
      virtual ~UpdateRenderingListener();
      // Variables
    private:
      agx::observer_ptr<agx::ParticleSystem>  m_system;
      agxSDK::Simulation* m_simulation;
    };
 
  protected:
    agxData::EntityStorageRef m_particleStorage;
  private:
    agxData::EntityStorageRef m_particleCellStorage;
    agxData::EntityStorageRef m_cellBlockStorage;
    agxData::EntityStorageRef m_particleZoneStorage;
    agxData::EntityStorageRef m_collisionParticleStorage;
    agxData::EntityStorageRef m_particleGeometryContactStorage;
    agxData::EntityStorageRef m_particlePairContactStorage;
    agxData::EntityStorageRef m_geometryParticleContactListStorage;
 
    agxData::BufferRef m_materialUuidBuffer;
    agxData::BufferRef m_stateBuffer;
    agxData::BufferRef m_cellBlockPermutation;
    agxData::BufferRef m_deadCellBlocks;
    agxData::BufferRef m_particlesWithMissingTargetCell;
    agxData::BufferRef m_cellBlockOverlapPairs;
    agxData::ValueRef m_particleBound;
    agxData::ValueRef m_collisionGroupSet;
    agxData::ValueRef m_defaultRadius;
    agxData::ValueRef m_defaultMass;
    agxData::ValueRef m_defaultMaterial;
 
    MaterialRef m_material;
    TaskRef m_gravityTask;
    bool m_initialized;
    bool m_dirtyBound;
 
    agx::TaskRef m_updateBoundTask;
 
    agxCollide::GeometryHashVector m_disabledCollisionsHash;
    agxCollide::SpaceRef m_space;
 
    MaterialUuidBufferListenerRef m_uuidMaterialListenerRef;
    UpdateRenderingListenerRef m_updateRenderingListenerRef;
 
    agxData::ValueObserver m_invMassValue;
    void massChanged( agxData::Value* massValue );
    agxData::Value::Event::CallbackType m_massChangedCallback;
  };
 
  /* Implementation */
  AGX_FORCE_INLINE Task* ParticleSystem::getUpdateTask() { return m_updateTask; }
 
  AGX_FORCE_INLINE const agx::Physics::ParticlePtrArray ParticleSystem::getParticles() const
  {
    return m_particleStorage->getInstances<Physics::ParticlePtr>();
  }
 
  AGX_FORCE_INLINE agx::Physics::ParticlePtrArray ParticleSystem::getParticles()
  {
    return m_particleStorage->getInstances<Physics::ParticlePtr>();
  }
 
  AGX_FORCE_INLINE agxData::EntityStorage* ParticleSystem::getParticleStorage() { return m_particleStorage; }
  AGX_FORCE_INLINE const agxData::EntityStorage* ParticleSystem::getParticleStorage() const { return m_particleStorage; }
  AGX_FORCE_INLINE agxData::EntityStorage* ParticleSystem::getParticleGeometryContactStorage() { return m_particleGeometryContactStorage; }
  AGX_FORCE_INLINE agxData::EntityStorage* ParticleSystem::getGeometryParticleContactListStorage() { return m_geometryParticleContactListStorage; }
  AGX_FORCE_INLINE agxData::EntityStorage* ParticleSystem::getParticlePairContactStorage() { return m_particlePairContactStorage; }
 
  AGX_FORCE_INLINE const agxCollide::GeometryHashVector& ParticleSystem::getDisabledCollisions() const { return m_disabledCollisionsHash; }
  // AGX_FORCE_INLINE bool ParticleSystem::hasCollisionGroup( agx::UInt32 id ) const { return m_collisionGroups.contains(id); }
  inline agx::Physics::CollisionGroupSetPtr ParticleSystem::getCollisionGroupSet() const { return m_collisionGroupSet->get<Physics::CollisionGroupSetPtr>(); }
 
  // Real
  AGX_FORCE_INLINE void ParticleSystem::addCustomBufferReal( const agx::String& buffername ) { addCustomBufferT<agx::Real>( buffername ); }
  AGX_FORCE_INLINE void ParticleSystem::setCustomBufferValueReal( agx::Index id, const agx::String& buffername, agx::Real val ) { setCustomBufferValueT<agx::Real>( id, buffername, val ); }
  AGX_FORCE_INLINE agx::Real ParticleSystem::getCustomBufferValueReal( agx::Index id, const agx::String& buffername ) { return getCustomBufferValueT<agx::Real>( id, buffername ); }
 
  // Int
  AGX_FORCE_INLINE void ParticleSystem::addCustomBufferInt( const agx::String& buffername ) { addCustomBufferT<agx::Int>( buffername ); }
  AGX_FORCE_INLINE void ParticleSystem::setCustomBufferValueInt( agx::Index id, const agx::String& buffername, agx::Int val ) { setCustomBufferValueT<agx::Int>( id, buffername, val ); }
  AGX_FORCE_INLINE agx::Int ParticleSystem::getCustomBufferValueInt( agx::Index id, const agx::String& buffername ) { return getCustomBufferValueT<agx::Int>( id, buffername ); }
 
  // Real32
  AGX_FORCE_INLINE void ParticleSystem::addCustomBufferReal32( const agx::String& buffername ) { addCustomBufferT<agx::Real32>( buffername ); }
  AGX_FORCE_INLINE void ParticleSystem::setCustomBufferValueReal32( agx::Index id, const agx::String& buffername, agx::Real32 val ) { setCustomBufferValueT<agx::Real32>( id, buffername, val ); }
  AGX_FORCE_INLINE agx::Real32 ParticleSystem::getCustomBufferValueReal32( agx::Index id, const agx::String& buffername ) { return getCustomBufferValueT<agx::Real32>( id, buffername ); }
 
  // Vec3
  AGX_FORCE_INLINE void ParticleSystem::addCustomBufferVec3( const agx::String& buffername ) { addCustomBufferT<agx::Vec3>( buffername ); }
  AGX_FORCE_INLINE void ParticleSystem::setCustomBufferValueVec3( agx::Index id, const agx::String& buffername, agx::Vec3 val ) { setCustomBufferValueT<agx::Vec3>( id, buffername, val ); }
  AGX_FORCE_INLINE agx::Vec3 ParticleSystem::getCustomBufferValueVec3( agx::Index id, const agx::String& buffername ) { return getCustomBufferValueT<agx::Vec3>( id, buffername ); }
}
 
// AGX_PARTICLESYSTEM_H
#endif