ParticlePool

class pygamelib.gfx.particles.ParticlePool(size: int = None, emitter_properties: EmitterProperties = None)

Bases: object

The particle pool is a structure that holds a large number of particles and make them available to the emitters.

Its main role is to optimize the performances (both speed and memory usage). It works by pre-instantiating a desired number of particles according to the EmitterProperties that is given to the constructor.

The particle pool is optimized to avoid searching for available particles. It sets its own size to avoid relying on anything but its last known particle made available to the emitter. So unless for specific behavior, it is probably a good idea to let it sets its own size.

It also recycle particles that are finished() to avoid a constant cycle of creation/destruction of a large amount of particle objects.

__init__(size: int = None, emitter_properties: EmitterProperties = None) → None

The constructor takes the following parameters:

Parameters:

• size (int) – The size of the pool in number of particles. For this to be efficient, be sure to have enough particles to cover for enough cycles before your first emitted particles are finished. The ParticleEmitter uses the following rule to size the pool: emit_rate * particle_lifespan. It is the default value if size is not specified.

• emitter_properties (EmitterProperties) – The properties of the particles that needs to be pre-instantiated.

Example:

my_particle_pool = ParticlePool(500, my_properties)

Methods

__init__([size, emitter_properties])	The constructor takes the following parameters:
count_active_particles()	Returns the number of active particle (i.e not finished) in the pool.
get_particles([amount])	Returns the requested amount of particles.
resize(new_size)	Resize the particle pool to a new size.

Attributes

pool	A read-only property that returns the particle pool tuple.

count_active_particles() → int

Returns the number of active particle (i.e not finished) in the pool.

Important

The only way to know the amount of alive particles is to go through the entire pool. Be aware of the performance impact on large particle pools.

Returns:

the number of active particles.

Return type:

int

Example:

if emitter.particles.count_active_particles() > 0:
    emitter.apply_force(gravity)

get_particles(amount: int = None) → tuple

Returns the requested amount of particles.

It is important to know that no particle is created during that call. This method returns available particles in the pool. Particles are recycled after they “died”.

If amount is not specified the pool returns EmitterProperties.emit_number particles.

Parameters:

amount (int) – The amount of particles to return.

Returns:

A tuple containing the desired amount of particles.

Return type:

tuple

Example:

fresh_particles = my_particle_pool.get_particles(30)

property pool: tuple

A read-only property that returns the particle pool tuple.

resize(new_size: int)

Resize the particle pool to a new size.

If the new size is greater than the old one, the pool will be filled by pre-instanciated particles. If it’s shorter however, the extra particles will be destroyed.

Parameters:

new_size (int) – The new size of the pool.

Example:

# Resize the particle pool to hold 100 particles.
my_particle_pool.resize(100)