Emitter shapes

ParticleEmitter object can be initialized with a variety of shapes, either primitives or meshes. Those shapes control the positions and normals (travel direction) for any spawned particles.

A shape is assigned to the emitter through the ParticleEmitter::SetShape method. All shape types derive from ParticleEmitterShape class. All shape classes have a Create() method that accepts a structure with various options allowing you to further customize the properties of the spawned particles.

SPtr<ParticleEmitter> emitter = B3DMakeShared<ParticleEmitter>();

// An emitter with the sphere shape
ParticleSphereShapeSettings sphereShape;
sphereShape.Radius = 0.3f;
emitter->SetShape(ParticleEmitterSphereShape::Create(sphereShape));

In this manual we'll go over all the available shapes.

Sphere

Emits particles from a sphere shape. Particles are spawned either on sphere surface, its shell or the entirety of the sphere volume. Particle normals are set to be outward facing from the sphere center.

Represented with the ParticleEmitterSphereShape and initialization options provided through ParticleSphereShapeSettings.

Use ParticleSphereShapeSettings::Radius to control the size of the sphere, and ParticleSphereShapeSettings::Thickness to control from which part of the sphere to spawn the particles. 0 means spawn from sphere surface, 1 means spawn on entire sphere volume, while values between represent an area of the sphere shell of some thickness.

ParticleSphereShapeSettings shapeSettings;
shapeSettings.Radius = 0.5f; // Size of the sphere
shapeSettings.Thickness = 0.1f; // Spawn particles on sphere shell (shell width being 10% of sphere radius)

SPtr<ParticleEmitterSphereShape> shape = ParticleEmitterSphereShape::Create(shapeSettings);

Hemisphere

Equivalent in every way to the sphere shape, except the particles are only emitted from one half of the sphere.

Represented with the ParticleEmitterHemisphereShape and initialization options provided through ParticleHemisphereShapeSettings.

ParticleHemisphereShapeSettings shapeSettings;
shapeSettings.Radius = 0.5f; // Size of the hemisphere
shapeSettings.Thickness = 0.1f; // Spawn particles on hemisphere shell (shell width being 10% of hemisphere radius)

SPtr<ParticleEmitterHemisphereShape> shape = ParticleEmitterHemisphereShape::Create(shapeSettings);

Cone

Emits particles from a cone or a conical frustum (cone with a top cut off). The particles can be spawned on the cone base (the pointy bit), entire cone volume, or cone shell (some percent of the volume).

Represented with the ParticleEmitterConeShape and initialization options provided through ParticleConeShapeSettings.

Use ParticleConeShapeSettings::Angle and ParticleConeShapeSettings::Length to control the basic shape of the cone.

ParticleConeShapeSettings shapeSettings;
shapeSettings.Angle = Degree(45.0f);
shapeSettings.Length = 1.0f;

SPtr<ParticleEmitterConeShape> shape = ParticleEmitterConeShape::Create(shapeSettings);

Use ParticleConeShapeSettings::Type to control should particles be spawned on the cone volume, or only its base.

shapeSettings.Type = ParticleEmitterConeType::Base; // Spawn only on the base
//shapeSettings.Type = ParticleEmitterConeType::Volume; // Or the entire volume

Base

If spawning on the base, the length parameter of the cone is ignored, while the angle parameter only controls the direction (normals) of the particles.

Normally the cone base is pointy, meaning all your particles will spawn on the same spot. You can set a non-zero ParticleConeShapeSettings::Radius parameter which will cut off the cone top, making a conical frustum. Your particles will then spawn anywhere on the base within the radius.

shapeSettings.Radius = 0.2f;

Volume

If spawning on the volume the particles will spawn anywhere within the cone volume. Similar to the sphere, you can use ParticleConeShapeSettings::Thickness parameter to limit spawning on an outer part of the volume (values between 0 and 1), entire volume (value 1) or just the surface (value 0).

Additionally you can also control the angular portion of the cone that can spawn particles through ParticleConeShapeSettings::Arc (normal cone having a 360 degree angle).

shapeSettings.Thickness = 0.1f;
shapeSettings.Arc = Degree(180.0f); // Spawn only on one half of the cone

Emission mode

Finally, you get to control the emission mode through ParticleConeShapeSettings::Mode. Emission mode gives you more control over particle spawning by providing a way to spawn particles non-randomly (sequentially).

ParticleEmissionMode::Type controls which of the emission mode to use. Use ParticleEmissionModeType::Loop and ParticleEmissionModeType::PingPong to spawn particles sequentially on the shape. Use ParticleEmissionMode::Interval to control how far apart should the spawned particles be, and ParticleEmissionMode::Speed to control how fast should the particles move around the shape.

Use ParticleEmissionModeType::Random to spawn the particles randomly, which is the default behaviour. You also get extra control to limit the random spawns to a specific interval through ParticleEmissionMode::Interval, which means the particles will only spawn on certain positions on the shape.

Finally ParticleEmissionModeType::Spread will spread out all particles spawned during a single burst over the entire shape, optionally using ParticleEmissionMode::Interval to limit the spawn positions.

// Spawn particles moving around the cone base
shapeSettings.Mode.Type = ParticleEmissionModeType::Loop;
shapeSettings.Mode.Speed = 90.0f; // 90 degrees per second
shapeSettings.Mode.Interval = 10.0f; // At 10 degree intervals

Box

Emits particles from a box shape. Particles are spawned either on box volume, surface or its edges. Particle normals are set to the positive Z direction always.

Represented with the ParticleEmitterBoxShape and initialization options provided through ParticleBoxShapeSettings.

Use ParticleBoxShapeSettings::Extents to specify the size of the box, and ParticleBoxShapeSettings::Type to control from which part of the box should the particles be emitted from.

ParticleBoxShapeSettings shapeSettings;
shapeSettings.Extents = Vector3::kOne * 0.5f; // Unit-sized box
shapeSettings.Type = ParticleEmitterBoxType::Volume; // Spawn in the entire box volume

SPtr<ParticleEmitterBoxShape> shape = ParticleEmitterBoxShape::Create(shapeSettings);

Circle

Emits particles from a 2D circle shape. Particles are spawned either on circle edge, its entire surface or a circle shell. Particle normals are set to the positive Z direction always.

Represented with the ParticleEmitterCircleShape and initialization options provided through ParticleCircleShapeSettings.

Use ParticleCircleShapeSettings::Radius to control the size of the circle, and ParticleCircleShapeSettings::Thickness to control from which part of the circle to spawn the particles. 0 means spawn from circle edge, 1 means spawn on entire circle surface, while values between represent an area of the circle shell of some thickness.

Additionally you can also control the angular portion of the circle that can spawn particles through ParticleCircleShapeSettings::Arc (normal circle having a 360 degree angle).

Finally you can control emission mode through ParticleCircleShapeSettings::Mode. The description of mode parameter is the same as for the cone, except the particles will be spawned along the circle edge instead of the cone base, and the speed/interval parameters represent distance instead of an angle.

ParticleCircleShapeSettings shapeSettings;
shapeSettings.Radius = 1.0f;
shapeSettings.Arc = Degree(300.0f); // "Pie" shape (circle with a part cut out)
shapeSettings.Thickness = 0.0f; // Spawn only on circle edges

SPtr<ParticleEmitterCircleShape> shape = ParticleEmitterCircleShape::Create(shapeSettings);

Rectangle

Emits particles from a 2D rectangle shape. Particles are always spawned on rectangle surface. Particle normals are set to the positive Z direction always.

Represented with the ParticleEmitterRectShape and initialization options provided through ParticleRectShapeSettings.

Use ParticleRectShapeSettings::Extents to control the size of the rectangle, which is also the only option provided by this shape.

ParticleRectShapeSettings shapeSettings;
shapeSettings.Extents = Vector2::kOne * 0.5f;

SPtr<ParticleEmitterRectShape> shape = ParticleEmitterRectShape::Create(shapeSettings);

Line

Emits particles from a line shape. Particle normals are set to the positive Z direction always.

Represented with the ParticleEmitterLineShape and initialization options provided through ParticleLineShapeSettings.

Use ParticleLineShapeSettings::Length to control the length of the line. You can also control emission mode through ParticleLineShapeSettings::Mode. The description of mode parameter is the same as for the cone and circle, except the particles will be spawned along the line instead of the cone/circle.

ParticleLineShapeSettings shapeSettings;
shapeSettings.Length = 1.0f;

SPtr<ParticleEmitterLineShape> shape = ParticleEmitterLineShape::Create(shapeSettings);

Static mesh

Emits particles from a surface of a static (non-animated) mesh. Particles can be emitted from anywhere on the surface, or limited to mesh vertices or edges. Particle normals are set to the normals specified by the mesh.

Represented with the ParticleEmitterStaticMeshShape and initialization options provided through ParticleStaticMeshShapeSettings.

Use ParticleStaticMeshShapeSettings::Mesh to specify the mesh resource to emit from. This option is required. The mesh should ideally be imported with CPU caching enabled, so its data can be read by the particle system without having to do an expensive GPU read.

Use ParticleStaticMeshShapeSettings::Type to control should the emission happen on mesh triangles (entire surface), edges or vertices.

Finally, enable ParticleStaticMeshShapeSettings::Sequential if you want particle positions to be chosen in the order they are specified in the mesh, instead of randomly. This option is only relevant when emitting from mesh vertices and allows you to provide an exact list of vertices to emit particles at, for complete control over their spawning process.

HMesh mesh = ...; // Import or create a mesh

ParticleStaticMeshShapeSettings shapeSettings;
shapeSettings.Mesh = mesh;
shapeSettings.Type = ParticleEmitterMeshType::Triangle;

SPtr<ParticleEmitterStaticMeshShape> shape = ParticleEmitterStaticMeshShape::Create(shapeSettings);

Skinned mesh

Provides the exact same functionality as the static mesh shape, except the mesh can be animated.

Represented with the ParticleEmitterSkinnedMeshShape and initialization options provided through ParticleSkinnedMeshShapeSettings.

Accepts the same options as the static mesh shape, except for the mesh property it accepts a Renderable in ParticleSkinnedMeshShapeSettings::Renderable.

HRenderable renderable = ...; // Set up the component and animate it

ParticleSkinnedMeshShapeSettings shapeSettings;
shapeSettings.Renderable = renderable;
shapeSettings.Type = ParticleEmitterMeshType::Triangle;

SPtr<ParticleEmitterSkinnedMeshShape> shape = ParticleEmitterSkinnedMeshShape::Create(shapeSettings);