- Qt Creator Manual
- Particles
- Qt Creator Manual 5.0.3

Loader3D ◦ Particle System

# Particles

A particle system enables you to use sprites, 3D models, or images to create effects that are hard to reproduce with conventional rendering techniques. This includes chaotic systems, natural phenomena, or processes caused by chemical reactions. For example, you can simulate fire, smoke, sparks, explosions, flowing water, fog, snow, stars, and galaxies.

The Qt Design Studio particle system contains the following main types of components:

- Particle System
- Logical Particles
- Particle Emitters
- Particle Affectors
- Particle Directions

## Adding a Particle System

Preset particle components are available in Library > Components > Qt Quick 3D Particles 3D after you add the QtQuick3D.Particles3D module to your project, as instructed in Adding and Removing Modules.

When you add an instance of the Particle System component to a scene, Qt Design Studio automatically adds instances of the Sprite Particle, Emitter, and Vector Direction components for you.

The Sprite Particle is a visual 2D texture particle. To use 3D model particles, add instances of the Model Particle component to the particle system. It is important to define the amount of particles to use in Properties > Particle > Max amount, so that the optimal buffer sizes get allocated. You can also specify the color and opacity of the particles, as well as the speed at which they fade in and out.

The Emitter component emits the sprite or model particles. You can specify particle shape and the area where they are emitted. Use variation in particle size and rotation for more natural results. Further, define the life span and initial direction of speed of the emitted particles.

Usually, affectors are used to make particle movement more interesting. For example, you could add an instance of the Gravity component to simulate falling objects, an instance of the Wander component to simulate flying objects that follow wavy curves, or an instance of the Point Rotator to simulate windy weather.

To add a particle system that emits sprite particles:

1. Select Library > Assets > to add your sprites, 3D models, textures, and other graphical assets to the project.
2. Drag-and-drop an instance of the Particle System component from Library to a scene component instance in Navigator.
3. Drag-and-drop an instance of the Texture component from Library > Components > Qt Quick 3D to the sprite particle instance in Navigator.
4. Drag-and-drop the sprite image from Library > Assets to the texture instance in Navigator.
5. Select the sprite particle instance in Navigator to display its properties in Properties.
6. In Sprite, select the texture instance.
7. Select the emitter instance in Navigator to display its properties in Properties.
8. In Particle, select the particle instance to emit.
9. Select the vector 3D instance in Navigator to display its properties in Properties.
10. In Direction, set the emitted particle velocity towards the target vector.

Add instances of other components according to your use case. The following section describes how to modify particle system component property values by using the simulation of fire as an example.

## Example: Fire

In this section, we explore using particle system components and modifying their property values, such as particle source images and their color, life span, and fading effects, to simulate fire.

We will need the following assets:

- Two images of flames: flame_01.png and flame_03.png
- An image of smoke: smoke_01.png

We will also need instances of the following components:

- Particle System (one instance)
- Sprite Particle (four instances)
- Emitter (four instances)
- Vector Direction (four instances)
- Texture (four instances)

We start by creating a Qt Quick 3D Application project and adding the assets to it. We then follow the instructions above to add the Particle System component instance, which provides us with our first Emitter, Sprite Particle, and Vector Direction instances.

We add a Texture component instance with flame_01.png as the source, and then add the texture as the sprite to use for the sprite particle. We now have all the component instances we need for our first emitter. To keep all the component instances together, we drag-and-drop the sprite particle instance to the emitter instance in Navigator.

We need more than one particle to realistically simulate a fire, so we will add three more emitter instances to the particle system. We can copy-paste the first instance in Navigator, and just modify two of the texture instances to use flame_03.png as the source and one of them to use smoke_01.png as the source. We use three different flame particles to be able to layer them and to hide the fact that two of them actually use the same texture.

We can now start playing with the particle system component properties to achieve the artistic effect that we want. To see how the changes in property values affect the simulation, we will open the live preview by selecting on the main toolbar (or by pressing Alt+P).

First, we will specify property values for the Particle System component. We want to spawn some particles before the simulation starts, so that the fire will be roaring at start. To achieve this, we set the value of Properties > Particle System > Start Time to 2000 milliseconds. We will use the default values for the other properties.

Then, we will specify how individual particles are spawned. We set the value of Properties > Particle Emitter > Emit rate to 40.00 for the flame particles and 20.00 for the smoke particle, because we want to have more flames than smoke.

To increase the visibility of the smoke at the top, we set the value of Life span to 1200 milliseconds for the smoke particles and 900, 1000, and 600 milliseconds for the flame particles. Further, we set Life span variation to 100, 200, and 300 for the flame particles to have some of them expire sooner than others.

To scale the particles during their lifespan, we set Particle scale to 2.00 for all particles and Particle end scale to 5.00 for the flame particles and to 6.00 for the smoke particles.

We can now modify the appearance of the particles by setting their color in Properties > Particle. We select transparent yellow, orange, and transparent gray in Color and set values for Color variation to use slightly different colors for the individual particles.

We set Fade in effect and Fade out effect values to FadeOpacity to change particle opacity between 0 and 1 over the time specified in milliseconds in Fade in duration and Fade out duration. Fading duration is calculated into the particle lifespan, and therefore the smoke particles are actually never fully visible with our settings.

To specify that the particle texture should always be aligned face towards the screen, we enable Properties > Sprite Particle > Billboard for all the particle component instances.

Finally, we will specify the direction in which the particles move by modifying the property values of the Vector Direction component instances in Properties > Particle Vector Direction.

In Direction, we set Y to 100.00 to make particles move up, and Z to -100.00 to make them move in the direction opposite to the target vector. We set the Direction value to -50.00 for one of the flame particles and to -80.00 for the smoke particle.

We set the Direction Variation values for the different vector direction instances to 10.00, 8.00, and 12.00 to make some flames spread wider than others. You can try different values until you get the effect you want.

## Performance Considerations

The particles are designed to be usable on a variety of hardware on desktops, as well as mobile and embedded devices. However, in addition to rendering the maximum amount of particle elements on the screen, extensibility to different use-cases, rendering quality, integration with the other UI elements, are also important.

Currently, the rendering runs on GPU, while the particle system logic runs on CPU. However, the stateless particle system enables you to move the system logic onto GPU if that seems beneficial. The initial measurements indicate that the system is quite well balanced between CPU and GPU. The stateless system also enables animating particles by using a timeline. The model particles use instanced rendering to boost the performance. Therefore, OpenGL ES 2.0 isn't sufficient to make rendering performant, and at least OpenGL ES 3.0, Vulkan, or some other modern backend is required.

To get a more concrete view on the actual performance, the video below shows a particles Testbed application running on four different Android devices. These devices and their chipsets and GPUs could be considered to be lower-end to mid-range, confirming that the particles can perform well also on affordable hardware.

## Summary of 3D Particles

Note: The Particles 3D components are released as a tech preview feature in Qt Design Studio 2.2, and their functionality will be improved in future releases.

The following table lists preset particle components.

Icon | Name | Purpose
--- | --- | ---
| Attractor | Attracts particles towards a specific point.
| Emit Burst | Generates declarative emitter bursts.
| Emitter | Emits logical particles.
| Gravity | Accelerates particles to a vector of the specified magnitude in the specified direction.
| Model Blend Particle | Blends a particle effect with an instance of a Model component.
| Model Particle | Creates a particle that uses an instance of a Model component.
| Model Shape | Provides 3D shapes from a model to emitters and affectors.
| Particle Shape | Provides 3D shapes to emitters and affectors.
| Particle System | Creates a particle system that includes particle, emitter, and affector components.
| Point Rotator | Rotates particles around a pivot point.
| Sprite Particle | Creates particles that use a 2D sprite texture.
| Sprite Sequence | Provides image sequence features for Sprite Particle component instances.
| Target Direction | Specifies a direction towards the target position.
| Trail Emitter | Emits logical particles from other particles.
| Vector Direction | Specifies a direction towards the target direction.
| Wander | Applies random wave curves to particles.

Loader3D ◦ Particle System