#include <CUParticleSystem.h>

Public Member Functions
	ParticleSystem ()

	~ParticleSystem ()

void	dispose ()

bool	init (size_t capacity)

bool	initWithMesh (size_t capacity, const Mesh< ParticleVertex > &mesh)

bool	initWithMesh (size_t capacity, Mesh< ParticleVertex > &&mesh)

bool	initWithData (const std::shared_ptr< JsonValue > data, bool buffer=true)

const Particle3 *	getParticles () const

const ParticleInstance *	getInstances () const

const Mesh< ParticleVertex > &	getMesh () const

void	setMesh (const Mesh< ParticleVertex > &mesh)

void	setMesh (Mesh< ParticleVertex > &&mesh)

const std::unordered_map< std::string, ParticleEmitter > &	getEmitters () const

void	addEmitter (const std::string key, const ParticleEmitter &data)

void	removeEmitter (const std::string key)

const std::shared_ptr< InstanceBuffer >	getInstanceBuffer () const

size_t	getCapacity () const

size_t	getAllocated () const

bool	is2d () const

void	set2d (bool value)

ParticleAllocator	getAllocator () const

void	setAllocator (ParticleAllocator func)

ParticleDeallocator	getDeallocator () const

void	setDeallocator (ParticleDeallocator func)

ParticleUpdater	getUpdater () const

void	setUpdater (ParticleUpdater func)

void	update (float delta, const Vec3 camera)

void	draw (const std::shared_ptr< Shader > &shader)

Static Public Member Functions
static std::shared_ptr< ParticleSystem >	alloc (size_t capacity)

static std::shared_ptr< ParticleSystem >	allocWithMesh (size_t capacity, const Mesh< ParticleVertex > &mesh)

static std::shared_ptr< ParticleSystem >	allocWithMesh (size_t capacity, Mesh< ParticleVertex > &&mesh)

static std::shared_ptr< ParticleSystem >	allocWithData (const std::shared_ptr< JsonValue > data, bool buffer=true)

Friends
class	ParticleLoader

Detailed Description

This class implements a (3d) particle system.

A particle system is a graphics::Mesh instanced many times to display a large collection of images. Instances are particles, which are represented the Particle3 class.

Particle simulation is defined via a user-defined ParticleUpdater function. Without this function, no instance data will be created for the particles, so nothing can be rendered to the screen.

While we do not support user-defined particles, it is possible to add user data to a particle object with the function types ParticleAllocator and ParticleDeallocator. In fact, ParticleAllocator is required to emit any particles. Without it, no particles will be created. On the other hand, ParticleDeallocator is optional and only required to prevent possible memory leaks.

Each particle system has its own InstanceBuffer. This is done for performance reasons. This is different that a SpriteBatch which has a single buffer that would be used for all objects of the same time. This particle system and its internal buffer should be combined with a particle shader to display this particles.

While particle systems are designed for 3d particles, they work perfectly well in 2d scene graphs. In that case, the particle classes should always set the z-value for the particle instances to 0. In addition, you should call set2d to prevent unnecessary z-sorting.

Constructor & Destructor Documentation

◆ ParticleSystem()

cugl::graphics::ParticleSystem::ParticleSystem ( )

Creates a new unitialized particle system.

This particle system has degenerate values for all attributes. No particles will be generated until it is initialized.

◆ ~ParticleSystem()

cugl::graphics::ParticleSystem::~ParticleSystem ( )

inline

Deletes this particle system, disposing all of the resources.

Member Function Documentation

◆ addEmitter()

void cugl::graphics::ParticleSystem::addEmitter	(	const std::string	key,
		const ParticleEmitter &	data
	)

Adds an emitter to the particle system.

This method will do nothing if the key is already in use by another emitter. The emitter will be immediately integrated into the simulation.

Parameters

key	The key identifing this emitter
data	The emitter data

◆ alloc()

static std::shared_ptr< ParticleSystem > cugl::graphics::ParticleSystem::alloc ( size_t capacity )

inlinestatic

Returns a newly allocated particle system with the given capacity.

The particle system will have an empty template and no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

Parameters

capacity The particle capacity

Returns: a newly allocated particle system with the given capacity.

◆ allocWithData()

static std::shared_ptr< ParticleSystem > cugl::graphics::ParticleSystem::allocWithData	(	const std::shared_ptr< JsonValue >	data,
		bool	buffer = `true`
	)

inlinestatic

Returns a newly allocated particle system from the given JsonValue

The JsonValue should either be an array or an JSON object. If it is an array, the elements should all be float arrays of length four, representing the individual ParticleVertex vertices. These vertices will be interpretted as a triangle fan.

On the other hand, if it is a JSON object, it supports the following attributes:

"capacity":  An int with the maximum capacity
"mesh":      An array or JSON object representing the mesh (see below)
"emitters":  An object with key/emitter pairs

All attributes except "capacity" are optional. If "emitters" is missing or empty, there are no emitters. The values in the key/value pairs for the emitter are per the specification for ParticleEmitter.

If the "mesh" is missing, the mesh template is empty. If it is an array, the elements should all be float arrays of length four, representing the individual ParticleVertex vertices. Otherwise, it should have the following attributes:

"vertices":      An array of float arrays of length four
"indices":       An intenger list of triangle indices (in multiples of 3)
"triangulator":  One of 'monotone', 'earclip', 'delaunay', 'fan', or 'strip'

All attributes are optional. If "vertices" are missing, the mesh will be empty. If both "indices" and "triangulator" are missing, the mesh will use a triangle fan. The "triangulator" choice will only be applied if the "indices" are missing.

The particle system will only create a graphics buffer if buffer is true. This is to handle cases where the sprite mesh is created in a separate thread (as OpenGL only allows graphics buffers to be made on the main thread).

Note that the JSON does not a provide a way to specify the user-defined allocation and update functions. No particles will be generated until these are set.

Parameters

data	The JSON object specifying the particle system
buffer	Whether to create a graphics buffer

Returns: a newly allocated particle system from the given JsonValue

◆ allocWithMesh() [1/2]

static std::shared_ptr< ParticleSystem > cugl::graphics::ParticleSystem::allocWithMesh	(	size_t	capacity,
		const Mesh< ParticleVertex > &	mesh
	)

inlinestatic

Returns a newly allocated particle system with the given capacity and mesh.

The particle system will have no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

This version of the initializer will acquire the resources of the original mesh. Use std::move to use this initializer.

Parameters

capacity	The particle capacity
mesh	The template mesh to copy

Returns: a newly allocated particle system with the given capacity and mesh.

◆ allocWithMesh() [2/2]

static std::shared_ptr< ParticleSystem > cugl::graphics::ParticleSystem::allocWithMesh	(	size_t	capacity,
		Mesh< ParticleVertex > &&	mesh
	)

inlinestatic

Returns a newly allocated particle system with the given capacity and mesh.

The particle system will have no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

This version of the initializer will acquire the resources of the original mesh. Use std::move to use this initializer.

Parameters

capacity	The particle capacity
mesh	The template mesh to acquire

Returns: a newly allocated particle system with the given capacity and mesh.

◆ dispose()

void cugl::graphics::ParticleSystem::dispose ( )

Disposes the emitters and allocation lists for this particle system.

You must reinitialize the particle system to use it.

◆ draw()

void cugl::graphics::ParticleSystem::draw ( const std::shared_ptr< Shader > & shader )

Draws the render buffer with the given shader.

Parameters

shader The shader to draw with

◆ getAllocated()

size_t cugl::graphics::ParticleSystem::getAllocated ( ) const

inline

Returns the number of particles currently allocated.

Returns: the number of particles currently allocated.

◆ getAllocator()

ParticleAllocator cugl::graphics::ParticleSystem::getAllocator ( ) const

inline

Returns the allocation function associated with this system.

If this function pointer is null, no particles will be allocated from any of the emitters.

Returns: the allocation function associated with this system.

◆ getCapacity()

size_t cugl::graphics::ParticleSystem::getCapacity ( ) const

inline

Returns the capacity of this particle system.

The capacity the maximum number of particles that can be allocated at any given time.

Returns: the capacity of this particle system.

◆ getDeallocator()

ParticleDeallocator cugl::graphics::ParticleSystem::getDeallocator ( ) const

inline

Returns the deallocation function associated with this system.

This function pointer is optional. It is only needed to clean up particles where memory was previously allocated. If there is no chance of a memory leak, it can be omitted.

Returns: the deallocation function associated with this system.

◆ getEmitters()

const std::unordered_map< std::string, ParticleEmitter > & cugl::graphics::ParticleSystem::getEmitters ( ) const

inline

Returns the emitters for this particle system.

Each emitter is identified by a user-specified key. It is safe to change the attributes of an emitter mid-simulation, but any changes will only be applied to new particles, not existing ones.

Returns: the emitters for this particle system.

◆ getInstanceBuffer()

const std::shared_ptr< InstanceBuffer > cugl::graphics::ParticleSystem::getInstanceBuffer ( ) const

inline

Returns the instance buffer for this particle system.

This buffer is used to render the particles. It should be combined with the particle shader.

Returns: the instance buffer for this particle system.

◆ getInstances()

const ParticleInstance * cugl::graphics::ParticleSystem::getInstances ( ) const

inline

Returns the array of instance data.

This array should be passed to the shader for drawing. This array will have getCapacity length. However, only the first getAllocated elements will be in use.

Returns: the array of instance data.

◆ getMesh()

const Mesh< ParticleVertex > & cugl::graphics::ParticleSystem::getMesh ( ) const

inline

Returns the mesh template associated with this particle system.

This mesh can be safely changed mid-simulation. It only affects how particles are rendered, not their state. However, changing the mesh affects the getInstanceBuffer. Therefore, the mesh should never be modified directly. Changes should go through setMesh.

Returns: the mesh template associated with this particle system.

◆ getParticles()

const Particle3 * cugl::graphics::ParticleSystem::getParticles ( ) const

inline

Returns the array of particles.

This array will have getCapacity length. However, only the first getAllocated elements will be in use.

Returns: the array of particles.

◆ getUpdater()

ParticleUpdater cugl::graphics::ParticleSystem::getUpdater ( ) const

inline

Returns the update function associated with this system.

If this function pointer is null, no instance data will be created for the particles, so nothing can be rendered to the screen. Indeed, the result of getInstances is undefined if this value is null.

Returns: the update function associated with this system.

◆ init()

bool cugl::graphics::ParticleSystem::init ( size_t capacity )

Initializes this particle system to have the given capacity.

The particle system will have an empty mesh and no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

Parameters

capacity The particle capacity

Returns: true if initialization was successful

◆ initWithData()

bool cugl::graphics::ParticleSystem::initWithData	(	const std::shared_ptr< JsonValue >	data,
		bool	buffer = `true`
	)

Initializes a particle template from the given JsonValue

The JsonValue should either be an array or an JSON object. If it is an array, the elements should all be float arrays of length four, representing the individual ParticleVertex vertices. These vertices will be interpretted as a triangle fan.

On the other hand, if it is a JSON object, it supports the following attributes:

"capacity":  An int with the maximum capacity
"mesh":      An array or JSON object representing the mesh (see below)
"emitters":  An object with key/emitter pairs

All attributes except "capacity" are optional. If "emitters" is missing or empty, there are no emitters. The values in the key/value pairs for the emitter are per the specification for ParticleEmitter.

If the "mesh" is missing, the mesh template is empty. If it is an array, the elements should all be float arrays of length four, representing the individual ParticleVertex vertices. Otherwise, it should have the following attributes:

"vertices":      An array of float arrays of length four
"indices":       An intenger list of triangle indices (in multiples of 3)
"triangulator":  One of 'monotone', 'earclip', 'delaunay', 'fan', or 'strip'

All attributes are optional. If "vertices" are missing, the mesh will be empty. If both "indices" and "triangulator" are missing, the mesh will use a triangle fan. The "triangulator" choice will only be applied if the "indices" are missing.

The particle system will only create a graphics buffer if buffer is true. This is to handle cases where the sprite mesh is created in a separate thread (as OpenGL only allows graphics buffers to be made on the main thread).

Note that the JSON does not a provide a way to specify the user-defined allocation and update functions. No particles will be generated until these are set.

Parameters

data	The JSON object specifying the particle system
buffer	Whether to create a graphics buffer

Returns: true if initialization was successful

◆ initWithMesh() [1/2]

bool cugl::graphics::ParticleSystem::initWithMesh	(	size_t	capacity,
		const Mesh< ParticleVertex > &	mesh
	)

Initializes this particle system with the given capacity and mesh.

The particle system will have no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

This version of the initializer will copy the original mesh.

Parameters

capacity	The particle capacity
mesh	The template mesh to copy

Returns: true if initialization was successful

◆ initWithMesh() [2/2]

bool cugl::graphics::ParticleSystem::initWithMesh	(	size_t	capacity,
		Mesh< ParticleVertex > &&	mesh
	)

Initializes this particle system with the given capacity and mesh.

The particle system will have no emitters. It will also have no user-defined update or allocation functions. It will not generate any particles until all of these are set.

This version of the initializer will acquire the resources of the original mesh. Use std::move to use this initializer.

Parameters

capacity	The particle capacity
mesh	The template mesh to acquire

Returns: true if initialization was successful

◆ is2d()

bool cugl::graphics::ParticleSystem::is2d ( ) const

inline

Returns whether this particle system is optimized for 2d.

A 2d particle system has no z-value and does not require z-sorting.

Returns: whether this particle system is optimized for 2d

◆ removeEmitter()

void cugl::graphics::ParticleSystem::removeEmitter ( const std::string key )

Removes the emitter with the given key.

Any particles previously created by the emitter will remain part of the simultation until their life value reaches 0. This method will have no effect if there is no emitter with the given key.

Parameters

key	The key identifing the emitter

◆ set2d()

void cugl::graphics::ParticleSystem::set2d ( bool value )

inline

Sets whether this particle system is optimized for 2d.

A 2d particle system has no z-value and does not require z-sorting.

Parameters

value Whether this particle system is optimized for 2d

◆ setAllocator()

void cugl::graphics::ParticleSystem::setAllocator ( ParticleAllocator func )

inline

Sets the allocation function associated with this system.

If this function pointer is null, no particles will be allocated from any of the emitters.

Parameters

func	The allocation function associated with this system.

◆ setDeallocator()

void cugl::graphics::ParticleSystem::setDeallocator ( ParticleDeallocator func )

inline

Sets the desllocation function associated with this system.

This function pointer is optional. It is only needed to clean up particles where memory was previously allocated. If there is no chance of a memory leak, it can be omitted.

Parameters

func	The deallocation function associated with this system.

◆ setMesh() [1/2]

void cugl::graphics::ParticleSystem::setMesh ( const Mesh< ParticleVertex > & mesh )

Sets the mesh template associated with this particle system.

This mesh can be safely changed mid-simulation. It only affects how particles are rendered, not their state. However, changing the mesh affects the getInstanceBuffer. Therefore, the mesh should never be modified directly. Changes should go through setMesh.

Parameters

mesh	The particle mesh template

◆ setMesh() [2/2]

void cugl::graphics::ParticleSystem::setMesh ( Mesh< ParticleVertex > && mesh )

Sets the mesh template associated with this particle system.

This mesh can be safely changed mid-simulation. It only affects how particles are rendered, not their state. However, changing the mesh affects the getInstanceBuffer. Therefore, the mesh should never be modified directly. Changes should go through setMesh.

Parameters

mesh	The particle mesh template

◆ setUpdater()

void cugl::graphics::ParticleSystem::setUpdater ( ParticleUpdater func )

inline

Sets the update function associated with this system.

If this function pointer is null, no instance data will be created for the particles, so nothing can be rendered to the screen. Indeed, the result of getInstances is undefined if this value is null.

Parameters

func	The update function associated with this system.

◆ update()

void cugl::graphics::ParticleSystem::update	(	float	delta,
		const Vec3	camera
	)

Updates the simulation by the given amount of time.

Most of the work of this method is implemented by the particle class. This method manages particle emission (with delay) and camera distance.

Parameters

delta	The time passed in the simulation
camera	The camera position in world space

The documentation for this class was generated from the following file:

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUParticleSystem.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ParticleSystem()

◆ ~ParticleSystem()

Member Function Documentation

◆ addEmitter()

◆ alloc()

◆ allocWithData()

◆ allocWithMesh() [1/2]

◆ allocWithMesh() [2/2]

◆ dispose()

◆ draw()

◆ getAllocated()

◆ getAllocator()

◆ getCapacity()

◆ getDeallocator()

◆ getEmitters()

◆ getInstanceBuffer()

◆ getInstances()

◆ getMesh()

◆ getParticles()

◆ getUpdater()

◆ init()

◆ initWithData()

◆ initWithMesh() [1/2]

◆ initWithMesh() [2/2]

◆ is2d()

◆ removeEmitter()

◆ set2d()

◆ setAllocator()

◆ setDeallocator()

◆ setMesh() [1/2]

◆ setMesh() [2/2]

◆ setUpdater()

◆ update()