Most visited

Recently visited

ParticleEmitter

public class ParticleEmitter
extends Object

java.lang.Object
   ↳ com.viro.core.ParticleEmitter


ParticleEmitter enables developers to create and configure quad emitters for building complex and intricate particle effects. Some examples are smoke, rain, confetti, and fireworks.

ParticleEmitters are particle factories that create, contain and recycle a pool of particles. Groups of particle systems can be used in conjunction with one another to create a composite effect. For example, a campfire may include a flame emitter, a smoke emitter, and an ember or sparks emitter.

For an extended discussion of particle systems in Viro, refer to the Particle Effects Guide.

Summary

Nested classes

class ParticleEmitter.EmissionBurst

EmissionBurst defines moments of instantaneous particle creation. 

enum ParticleEmitter.Factor

Factor is used to distinguish between various particle emission properties that can either be set as a rate per second or per meter

class ParticleEmitter.ParticleEmitterBuilder

Builder for creating ParticleEmitter objects. 

interface ParticleEmitter.ParticleModifier

ParticleModifier is used by various ParticleEmitter properties to set not only how particles will initially behave, but how they will behave over time or across distance. 

class ParticleEmitter.ParticleModifierColor

ParticleModifier for color properties. 

class ParticleEmitter.ParticleModifierFloat

ParticleModifier for floating point properties. 

class ParticleEmitter.ParticleModifierVector

ParticleModifier for Vector properties. 

interface ParticleEmitter.SpawnVolume

Interface for volumes that can be defined for spawning particles. 

class ParticleEmitter.SpawnVolumeBox

For spawning particles across or within a box. 

class ParticleEmitter.SpawnVolumeEllipsoid

For spawning particles across or within an ellipsoid. 

class ParticleEmitter.SpawnVolumePoint

For spawning particles at a particular point in the parent Node's coordinate system. 

class ParticleEmitter.SpawnVolumeSphere

For spawning particles aross or within a sphere. 

Public constructors

ParticleEmitter(ViroContext viroContext, Surface surface)

This constructor is deprecated. use ParticleEmitter(ViroContext, Quad) instead

ParticleEmitter(ViroContext viroContext, Quad quad)

Create a new ParticleEmitter with individual particles that resemble the provided Quad.

Public methods

static ParticleEmitter.ParticleEmitterBuilder builder(ViroContext viroContext, Surface surface)

This method is deprecated. use ERROR(/ParticleEmitterBuilder#ParticleEmitterBuilder(ViroContext, Quad)) instead

static ParticleEmitter.ParticleEmitterBuilder builder(ViroContext viroContext, Quad quad)

Builder for ParticleEmitter objects.

void dispose()

Release native resources associated with this ParticleEmitter.

Material.BlendMode getBlendMode()

Return the Material.BlendMode used by particles from this ParticleEmitter.

float getBloomThreshold()

Get the bloom threshold, the brightness at which particles from this ParticleEmitter will begin to bloom.

int getDelay()

Get the delay in milliseconds to apply between emission cycles.

int getDuration()

Get the duration of each emission cycle in milliseconds.

List<ParticleEmitter.EmissionBurst> getEmissionBursts()

Get the ParticleEmitter.EmissionBursts for this ParticleSystem, which define moments of instantaneous particle creation.

float[] getEmissionRatePerMeter()

Get the number of particles emitted per meter traveled by this ParticleEmitter during an emission cycle.

float[] getEmissionRatePerSecond()

Get the number of particles emitted per second by this ParticleEmitter during an emission cycle.

int getMaxParticles()

Get the maximum number of live particles allowed for this ParticleEmitter.

float[] getParticleLifetime()

Get the lifetime of particles in milliseconds.

boolean getSpawnOnSurface()

Return true if particles are only generated on the surface of the ParticleEmitter's ParticleEmitter.SpawnVolume.

ParticleEmitter.SpawnVolume getSpawnVolume()

Return the {@link SpawnVolume, which defines the volume over which particles will be created for this ParticleEmitter.

boolean isFixedToEmitter()

Returns true if the particles in this ParticleEmitter are fixed to the emitter's location.

boolean isPaused()

Returns true if the ParticleEmitter is not running.

void pause()

Pause the ParticleEmitter.

void resetEmissionCycle()

Resets this ParticleEmitter to the beginning of its emission cycle.

void run()

Run the ParticleEmitter.

void setAccelerationModifier(ParticleEmitter.ParticleModifierVector modifier)

Set the acceleration of the particles generated by this ParticleEmitter.

void setBlendMode(Material.BlendMode blendMode)

Set the Material.BlendMode to use for particles from this ParticleEmitter.

void setBloomThreshold(float threshold)

Set the brightness value at which particles from this ParticleEmitter will begin to bloom.

void setColorModifier(ParticleEmitter.ParticleModifierColor modifier)

Set the color of the particles generated by this ParticleEmitter.

void setDelay(int delayMillis)

Set the delay in milliseconds to apply before this ParticleEmitter starts a new emission cycle.

void setDuration(int durationMillis)

Set the duration of each emission cycle in milliseconds.

void setEmissionBursts(List<ParticleEmitter.EmissionBurst> bursts)

Set ParticleEmitter.EmissionBursts for this ParticleSystem for instantaneous particle creation.

void setEmissionRatePerMeter(int min, int max)

Set the number of particles this ParticleEmitter spawns per meter traveled, during an emission cycle.

void setEmissionRatePerSecond(int min, int max)

Set the number of particles this emitter spawns per second, during an emission cycle.

void setExplosiveImpulse(float impulse, Vector position, float decelerationPeriod)

Set an explosive impulse, which simulates the effect of a detonation or other impulsive force.

void setFixedToEmitter(boolean fixed)

Set whether the particles generated from this ParticleEmitter are fixed to the emitter's location, or are free.

void setLoop(boolean loop)

Set to true if the emitter should restart emitting particles at the end of each emission cycle, after the delay.

void setMaxParticles(int maxParticles)

Set the maximum number of live particles that can exist at any moment from this ParticleEmitter.

void setOpacityModifier(ParticleEmitter.ParticleModifierFloat modifier)

Set the opacity of the particles generated by this ParticleEmitter.

void setParticleLifetime(int min, int max)

Set the lifetime of each particle, in milliseconds.

void setRotationModifier(ParticleEmitter.ParticleModifierFloat modifier)

Set the rotation of the particles generated by this ParticleEmitter.

void setScaleModifier(ParticleEmitter.ParticleModifierVector modifier)

Set the scale of the particles generated by this ParticleEmitter.

void setSpawnVolume(ParticleEmitter.SpawnVolume volume, boolean spawnOnSurface)

Set the ParticleEmitter.SpawnVolume, which defines the volume over which particles will be created for this ParticleEmitter.

void setVelocityModifier(ParticleEmitter.ParticleModifierVector modifier)

Set the velocity of the particles generated by this ParticleEmitter.

Public constructors

ParticleEmitter

ParticleEmitter (ViroContext viroContext, 
                Surface surface)

This constructor is deprecated.
use ParticleEmitter(ViroContext, Quad) instead

Create a new ParticleEmitter with individual particles that resemble the provided Surface. To be used, the ParticleEmitter needs to be added to a Node through setParticleEmitter(ParticleEmitter). The ParticleEmitter will conform to all the transforms of its parent Node, meaning it can be moved and oriented with the scene graph.

Parameters
viroContext ViroContext: The ViroContext is required to generate particles.

surface Surface: Surface representing how each individual particle should appear. The Surface may be textured as well.

ParticleEmitter

ParticleEmitter (ViroContext viroContext, 
                Quad quad)

Create a new ParticleEmitter with individual particles that resemble the provided Quad. To be used, the ParticleEmitter needs to be added to a Node through setParticleEmitter(ParticleEmitter). The ParticleEmitter will conform to all the transforms of its parent Node, meaning it can be moved and oriented with the scene graph.

Parameters
viroContext ViroContext: The ViroContext is required to generate particles.

quad Quad: Quad representing how each individual particle should appear. The Quad may be textured as well.

Public methods

builder

ParticleEmitter.ParticleEmitterBuilder builder (ViroContext viroContext, 
                Surface surface)

This method is deprecated.
use ERROR(/ParticleEmitterBuilder#ParticleEmitterBuilder(ViroContext, Quad)) instead

Builder for ParticleEmitter objects.

Parameters
viroContext ViroContext

surface Surface

Returns
ParticleEmitter.ParticleEmitterBuilder

builder

ParticleEmitter.ParticleEmitterBuilder builder (ViroContext viroContext, 
                Quad quad)

Builder for ParticleEmitter objects.

Parameters
viroContext ViroContext

quad Quad

Returns
ParticleEmitter.ParticleEmitterBuilder

dispose

void dispose ()

Release native resources associated with this ParticleEmitter.

getBlendMode

Material.BlendMode getBlendMode ()

Return the Material.BlendMode used by particles from this ParticleEmitter.

Returns
Material.BlendMode The Material.BlendMode used by this ParticleEmitter.

getBloomThreshold

float getBloomThreshold ()

Get the bloom threshold, the brightness at which particles from this ParticleEmitter will begin to bloom. See setBloomThreshold(float) for discussion.

Returns
float The bloom threshold.

getDelay

int getDelay ()

Get the delay in milliseconds to apply between emission cycles.

Returns
int The delay in milliseconds.

getDuration

int getDuration ()

Get the duration of each emission cycle in milliseconds.

Returns
int The duration in milliseconds.

getEmissionBursts

List<ParticleEmitter.EmissionBurst> getEmissionBursts ()

Get the ParticleEmitter.EmissionBursts for this ParticleSystem, which define moments of instantaneous particle creation. See setEmissionBursts(List) for discussion.

Returns
List<ParticleEmitter.EmissionBurst> List of each ParticleEmitter.EmissionBurst used in this ParticleSystem.

getEmissionRatePerMeter

float[] getEmissionRatePerMeter ()

Get the number of particles emitted per meter traveled by this ParticleEmitter during an emission cycle. This value is picked randomly from the returned uniform distribution. See setEmissionRatePerMeter(int, int) for discussion.

Returns
float[] The float[] with the minimum and maximum number of particles emitted per meter.

getEmissionRatePerSecond

float[] getEmissionRatePerSecond ()

Get the number of particles emitted per second by this ParticleEmitter during an emission cycle. This value is picked randomly from the returned uniform distribution. See setEmissionRatePerSecond(int, int) for discussion.

Returns
float[] The float[] with the minimum and maximum number of particles emitted per second.

getMaxParticles

int getMaxParticles ()

Get the maximum number of live particles allowed for this ParticleEmitter. See setMaxParticles(int) for discussion.

Returns
int The maximum number of particles.

getParticleLifetime

float[] getParticleLifetime ()

Get the lifetime of particles in milliseconds. This lifetime of each particle is picked randomly from the returned uniform distribution. See setParticleLifetime(int, int) for discussion.

Returns
float[] The float[] with the minimum and maximum lifetime of each particle, in milliseconds.

getSpawnOnSurface

boolean getSpawnOnSurface ()

Return true if particles are only generated on the surface of the ParticleEmitter's ParticleEmitter.SpawnVolume.

Returns
boolean True if particles only spawn on the surface, false if they spawn within the volume as well.

getSpawnVolume

ParticleEmitter.SpawnVolume getSpawnVolume ()

Return the {@link SpawnVolume, which defines the volume over which particles will be created for this ParticleEmitter. See {@link #setSpawnVolume(SpawnVolume, boolean)} for discussion.

Returns
ParticleEmitter.SpawnVolume The ParticleEmitter.SpawnVolume on or within which particles are generated.

isFixedToEmitter

boolean isFixedToEmitter ()

Returns true if the particles in this ParticleEmitter are fixed to the emitter's location. See setFixedToEmitter(boolean) for discussion.

Returns
boolean True if the particles are fixed to the emitter location.

isPaused

boolean isPaused ()

Returns true if the ParticleEmitter is not running.

Returns
boolean True if the ParticleEmitter is paused.

pause

void pause ()

Pause the ParticleEmitter. This will immediately cease the generation of new particles, but existing particles will live out their remaining lifetimes.

resetEmissionCycle

void resetEmissionCycle ()

Resets this ParticleEmitter to the beginning of its emission cycle. This will also clear all existing particles.

run

void run ()

Run the ParticleEmitter. This will wait for delay milliseconds then start the first emission cycle. The cycle will continue for its set duration, and then another cycle will start after the delay if loop is enabled. Emissions can be stopped at any time by invoking pause().

setAccelerationModifier

void setAccelerationModifier (ParticleEmitter.ParticleModifierVector modifier)

Set the acceleration of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierVector provided will define the initial acceleration of the particles, and may also indicate how acceleration will change over time or over distance. Each Vector in the modifier defines the X, Y, and Z accelearation.

By default, ParticleEmitter radiates particles in a fountain-like fashion. By using setVelocityModifier(ParticleModifierVector) and setAccelerationModifier(ParticleModifierVector) a variety of more complex animations can be achieved. For example, falling, swaying snow can be achieved with a fixed acceleration of -9.81 and a randomized initial horizontal velocity. A similar configuration can be used to make steam particles emanate from a kettle.

>

Parameters
modifier ParticleEmitter.ParticleModifierVector: The ParticleEmitter.ParticleModifierVector describing acceleration behavior for the particles.

setBlendMode

void setBlendMode (Material.BlendMode blendMode)

Set the Material.BlendMode to use for particles from this ParticleEmitter. BlendMode determines how a pixel's color, as it is being rendered, interacts with the color of the pixel already in the framebuffer.

Default is ALPHA.

Parameters
blendMode Material.BlendMode: The BlendMode to use for this Material.

setBloomThreshold

void setBloomThreshold (float threshold)

Set the brightness value at which particles from this ParticleEmitter will begin to bloom.

Bloom is an effect that makes surfaces appear to glow by applying a Gaussian blur and additive blend.

This value specifies at what 'brightness' the particles should start to bloom. Brightness is effectively the magnitude of the final color of a particle (modified for the human eye: specifically it is the dot product of the final color with (0.2126, 0.7152, 0.0722)).

For example, if this property is set to 0.0, then all particles will bloom. If this property is set to 1.0, then only those pixels of the particle whose brightness exceeds 1.0 (after lights are applied) will bloom.

Default is -1.0, which disables bloom.

Parameters
threshold float: The bloom threshold value to set. Set to less than zero to disable bloom entirely.

setColorModifier

void setColorModifier (ParticleEmitter.ParticleModifierColor modifier)

Set the color of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierColor provided will define the initial color of the particles, and may also indicate how color will change over time or over distance.

Parameters
modifier ParticleEmitter.ParticleModifierColor: The ParticleEmitter.ParticleModifierColor describing color behavior for the particles.

setDelay

void setDelay (int delayMillis)

Set the delay in milliseconds to apply before this ParticleEmitter starts a new emission cycle. Particles are produced during each emission cycle.

Default is 0 milliseconds.

Parameters
delayMillis int: The delay in milliseconds.

setDuration

void setDuration (int durationMillis)

Set the duration of each emission cycle in milliseconds. Particles are produced continually during each emission cycle.

The default is 2000 milliseconds.

Parameters
durationMillis int: The duration in milliseconds.

setEmissionBursts

void setEmissionBursts (List<ParticleEmitter.EmissionBurst> bursts)

Set ParticleEmitter.EmissionBursts for this ParticleSystem for instantaneous particle creation. In addition to emitting particles at a constant rate via setEmissionRatePerMeter(int, int) and setEmissionRatePerSecond(int, int), certain particle effects may require the ability to instantaneously spawn N number of particles all at once in a single burst. Fireworks, sparks, and explosions are some examples. To specify a burst, create ParticleEmitter.EmissionBurst objects. In each ParticleEmitter.EmissionBurst you can specify a time (or distance traveled) at which to burst a number of particles, in repetition if needed. These bursts are done in conjunction with emission rates, and are also subjected to the same setMaxParticles(int) constraint.

There are no bursts assigned by default.

Parameters
bursts List: The ParticleEmitter.EmissionBurst bursts to use in this ParticleSystem.

setEmissionRatePerMeter

void setEmissionRatePerMeter (int min, 
                int max)

Set the number of particles this ParticleEmitter spawns per meter traveled, during an emission cycle. The value is chosen randomly from the uniform distribution defined by min and max.

How fast an emitter produces particles is determined by either setEmissionRatePerSecond(int, int) or setEmissionRatePerMeter(int, int) (in which the particle output is proportional to how fast the emitter itself is moving). Depending on the effect you wish to create, you may decide to one or both properties. For example, in a situation where steam particles are emitted from a train upon movement, setEmissionRatePerMeter(int, int) is the sensible choice. This is also true if you, say, have a spaceship that emits more smoke as it accelerates.

Default value is min 0, max 0, meaning zero particles produced per meter traveled.

Parameters
min int: The minimum number of particles to emit per meter.

max int: The maximum number of particles to emit per meter.

setEmissionRatePerSecond

void setEmissionRatePerSecond (int min, 
                int max)

Set the number of particles this emitter spawns per second, during an emission cycle. The value is chosen randomly from the uniform distribution defined by min and max.

How fast an emitter produces particles is determined by either setEmissionRatePerSecond(int, int) or setEmissionRatePerMeter(int, int) (in which the particle output is proportional to how fast the emitter itself is moving). Depending on the effect you wish to create, you may decide to one or both properties. For example, in a situation where steam particles are emitted from a train upon movement, setEmissionRatePerMeter(int, int) is the sensible choice. This is also true if you, say, have a spaceship that emits more smoke as it accelerates.

Default value is min 10, max 10.

Parameters
min int: The minimum number of particles to emit per second.

max int: The maximum number of particles to emit per second.

setExplosiveImpulse

void setExplosiveImpulse (float impulse, 
                Vector position, 
                float decelerationPeriod)

Set an explosive impulse, which simulates the effect of a detonation or other impulsive force.

Impulsive forces are defined by a detonation position and an impulse. The impulse is specified in newton seconds and determines the strength of the force. The detonation point is set in the coordinate system of the ParticleEmitter's parent Node. The closer particles are to the detonation point, the larger their explosive force.

The behavior of an explosion may also be tuned with the decelerationPeriod parameter. This enables a "dampening deceleration effect" against the explosive impulse force, in order to slow down the explosion. The decelerationPeriod defines the timeframe in milliseconds within which the particles will decelerate from their initial velocity to 0.0 m/s. This is particularly useful for fireworks, which explode outward then slow down / are dampened after a specific length of time.

Note that setting an explosive impulse automatically invalidates any velocity set via setVelocityModifier(ParticleModifierVector), as an explosion directly manipulates an object's velocity. Likewise, if a >decelerationPeriod is provided, it will invalidate the acceleration set via setAccelerationModifier(ParticleModifierVector).

Parameters
impulse float: The impulsive force, in newton seconds.

position Vector: The detonation position.

decelerationPeriod float: The deceleration period in milliseconds. Set to less than zero to not use a deceleration period.

setFixedToEmitter

void setFixedToEmitter (boolean fixed)

Set whether the particles generated from this ParticleEmitter are fixed to the emitter's location, or are free. When true, Viro uses the emitter's current position to determine each particle's appearance and movement; when false, Viro uses each particle's individual spawn location.

When false, particles are not "locked" to the emitter: they can float away. For example, smoke particles from a moving train would continue floating upward from the location they were spawned. When true, the smoke particles would be "locked" to the train's emitter: they would always move with the train in reference to the emitter's location.

Default is true.

Parameters
fixed boolean: True to fix particles to the emitter location.

setLoop

void setLoop (boolean loop)

Set to true if the emitter should restart emitting particles at the end of each emission cycle, after the delay.

Default is true.

Parameters
loop boolean: True to continually run emission cycles.

setMaxParticles

void setMaxParticles (int maxParticles)

Set the maximum number of live particles that can exist at any moment from this ParticleEmitter. This includes particles created by setEmissionRatePerSecond(int, int), setEmissionRatePerMeter(int, int), and setEmissionBursts(List). When the cap is reached, new particles will only be spawned as existing particles die off.

Default value is 500.

Parameters
maxParticles int: The maximum number of life particles for this ParticleEmitter.

setOpacityModifier

void setOpacityModifier (ParticleEmitter.ParticleModifierFloat modifier)

Set the opacity of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierFloat provided will define the initial opacity of the particles, and may also indicate how the opacity will change over time or over distance.

Parameters
modifier ParticleEmitter.ParticleModifierFloat: The ParticleEmitter.ParticleModifierFloat describing opacity behavior for the particles.

setParticleLifetime

void setParticleLifetime (int min, 
                int max)

Set the lifetime of each particle, in milliseconds. The lifetime for each particle will be chosen randomly from the uniform distribution defined by min and max.

How long a particle lives for (or how fast a particle dies) is defined by its lifetime. Specifying the particle lifetime and the particle emisssion rate (via setEmissionRatePerMeter(int, int) or setEmissionRatePerSecond(int, int)) determines the eventual steady state of the ParticleEmitter. In this steady state, there will be a roughly constant number of existing, spawned particles for the emitter.

Default value is min 2000, max 2000.

Parameters
min int: The minimum lifetime of a particle, in milliseconds.

max int: The maximum lifetime of a particle, in milliseconds.

setRotationModifier

void setRotationModifier (ParticleEmitter.ParticleModifierFloat modifier)

Set the rotation of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierVector provided will define the initial rotation of the particles, and may also indicate how rotation will change over time or over distance. Each Vector in the modifier defines the X, Y, and Z Euler angle rotation in radians.

Parameters
modifier ParticleEmitter.ParticleModifierFloat: The ParticleEmitter.ParticleModifierVector describing rotation behavior for the particles.

setScaleModifier

void setScaleModifier (ParticleEmitter.ParticleModifierVector modifier)

Set the scale of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierVector provided will define the initial scale of the particles, and may also indicate how scale will change over time or over distance. Each Vector in the modifier defines the X, Y, and Z scale.

Parameters
modifier ParticleEmitter.ParticleModifierVector: The ParticleEmitter.ParticleModifierVector describing scale behavior for the particles.

setSpawnVolume

void setSpawnVolume (ParticleEmitter.SpawnVolume volume, 
                boolean spawnOnSurface)

Set the ParticleEmitter.SpawnVolume, which defines the volume over which particles will be created for this ParticleEmitter.

By default, ParticleEmitter spawns particles at the location of the emitter. This is useful for effects tied to a single source, like smoke rising from a chimney. However, other effects may require more complex spawn volumes; for example, spawning snow or rain over an area of land.

By setting a spawn volume, you can specify the shape within which to spawn particles. Supported shapes are ParticleEmitter.SpawnVolumeBox with width, height, and length, ParticleEmitter.SpawnVolumeSphere with radius, ParticleEmitter.SpawnVolumeEllipsoid with x,y,z ellipsoid length, and ParticleEmitter.SpawnVolumePoint. All particles will spawn in a uniformly distributed pattern within the shape.

Finally, there may be effects that require particles to spawn on the surface of a shape, rather than within it. For example, fireworks require particles to be spawned on the surface of a sphere. To achieve this effect, set spawnOnSurface to true. Particles will be spawned in a uniformly distributed fashion on the surface of the specified shape.

Parameters
volume ParticleEmitter.SpawnVolume: The ParticleEmitter.SpawnVolume on or within which to generate particles.

spawnOnSurface boolean: True to only spawn particles on the surface of the volume, false to spawn particles within the volume as well.

setVelocityModifier

void setVelocityModifier (ParticleEmitter.ParticleModifierVector modifier)

Set the velocity of the particles generated by this ParticleEmitter. The ParticleEmitter.ParticleModifierVector provided will define the initial velocity of the particles, and may also indicate how velocity will change over time or over distance. Each Vector in the modifier defines the X, Y, and Z velocity.

By default, ParticleEmitter radiates particles in a fountain-like fashion. By using setVelocityModifier(ParticleModifierVector) and setAccelerationModifier(ParticleModifierVector) a variety of more complex animations can be achieved. For example, falling, swaying snow can be achieved with a fixed acceleration of -9.81 and a randomized initial horizontal velocity. A similar configuration can be used to make steam particles emanate from a kettle.

>

Parameters
modifier ParticleEmitter.ParticleModifierVector: The ParticleEmitter.ParticleModifierVector describing velocity behavior for the particles.

Hooray!