1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \keyword Qt Quick Particles
6 \qmlmodule QtQuick.Particles
7 \title Qt Quick Particles QML Types
9 \brief Provides QML types for particle effects
11 This QML module contains a particle system for Qt Quick. To use these types, import the module with the following line:
14 import QtQuick.Particles
17 For a simple overview of how the system can be used, see \l{Using the Qt Quick Particle System}.
19 For details on the performance characteristics see \l{qtquick-particles-performance.html}{Qt Quick Particle System Performance}.
24 \page qtquick-effects-particles.html
25 \title Using the Qt Quick Particle System
27 Documentation for all Particle System types can be found on the \l QtQuick.Particles module page.
29 To use the types from the particles module, import the module with the following line:
32 import QtQuick.Particles
35 \section1 The ParticleSystem
36 This particle system contains four main types of QML types: ParticleSystem, Painters, Emitters and Affectors.
38 The ParticleSystem type ties all the other types together, and manages the shared timeline. Painters, Emitters
39 and Affectors must all have the same ParticleSystem to be able to interact with each other.
41 You may have as many ParticleSystems as you want subject to this constraint, so the logical separation is to have
42 one ParticleSystem for all the types that you want to interact, or just one if the number of types is small
43 and they are easily kept under control..
45 \section1 Logical Particles
46 All the particle system types act on "logical particles". Every particle has a logical representation inside
47 the particle system, and this is what the types act upon. Not every logical particle needs to be visualized,
48 and some logical particles could lead to multiple visual particles being drawn on screen.
50 \section1 Particle Groups
51 Every logical particle is a member of a particle group, and each group is identified by a name. If no other
52 group has been specified, a logical particle belongs to the group with the name "" (the empty string), which
53 acts the same as any other group. Groups are used for two purposes, for controlling particles and because they
54 can have stochastic state transitions.
56 Groups control particles because you can never access an individual particle with any of the particle system
57 types. All types act on groups as a whole, and so any particles that need to behave differently from each
58 other (aside from the usual stochastic parameter variation) will need to be in different groups.
60 Particles can also change groups dynamically. When this happens the particles trajectory is unaltered, but it
61 can be acted upon by different ParticlePainters or Affectors. Particles can either have their group changed by
62 an Affector, or stochastic state transitions can be defined in a ParticleGroup type.
64 Generally, groups should only be defined in a ParticleGroup if they require stochastic state transitions. Otherwise,
65 it is sufficient to have the groups be defined simply by the strings used in the particle/particles properties
69 Emitters emit logical particles into the system. These particles have a trajectory and lifespan, but no visualization.
70 These particles are emitted from the location of the Emitter.
72 TrailEmitters are a special type of emitter which emits particles from the location of other logicial particles. Any logical
73 particle of the followed type within the bounds of a TrailEmitter will cause particle emission from its location, as if there
74 were an Emitter on it with the same properties as the TrailEmitter.
76 \sa {Qt Quick Particles Examples - Emitters}
78 \section1 ParticlePainters
79 Painters are the types that visualize logical particles. For each logical particle in the groups assigned to it,
80 which are within its bounds (or outside, if you do not set the clip property on the type) it will be visualized
81 in a manner dependent on the type of ParticlePainter. The base type of ParticlePainter does not draw anything.
82 ImageParticle renders an image at the particle location. ItemParticle allows you to visualize logical particles
83 using arbitrary QML delegates. ModelParticle is similar, but coordinates model data amongst the delegates in a
84 similar manner to the view classes.
86 As the ParticlePainter is the QML type visualizing the particles in the scene, it is its Z value which is important
87 when trying to place particles above or below other types visually.
90 Affectors are an optional component of a particle system. They can perform a variety of manipulations to the simulation,
91 such as altering the trajectory of particles or prematurely ending their life in the simulation. For performance reasons,
92 it is recommended not to use Affectors in high-volume particle systems.
94 \sa {Qt Quick Particles Examples - Affectors}{Examples Affectors},
95 {Qt Quick Particles Examples - Image Particles}{Examples Image Particles},
96 {Qt Quick Particles Examples - System}{Example Affectors - System}
98 \section1 Stochastic Parameters
99 As particle systems benefit from stochastic control of parameters across a large number of instances, several stochastic
100 helper types are used by the particle system. If you do not wish to have any stochastic variation in these parameters,
101 then do not specify any variation in these types.
104 Directions can be specified by angle and magnitude, or by x and y components. While any direction can be specified with
105 either method, there is a significant difference between varying the x and y components and varying the angle and magnitude.
106 Varying the x and y components will lead to a rectangular area around the specified point, while varying the angle will lead
107 to an arc centered on the specified point.
110 The particle system contains several types which represent shapes. These types do not visualize shapes, and are used
111 for the purpose of selecting a random point within the shape. If you want a specific point with no randomness, use a 0 width
112 and 0 height shape (which is the default). Otherwise you can use the shape types to specify an area, so that the
113 result can use a random point selected from that area.
117 \page qtquick-particles-performance.html
118 \title Particle System Performance Guide
120 The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired
121 effect, performance can be improved by lowering the particle count. Conversely, if performance is well within the acceptable
122 bounds, you can increase the number of particles until you hit that point (should that improve the effect).
124 Note that particle count is often estimated by the particle system, and in some cases explicitly providing hints as to how
125 many particles will be needed will improve performance. You can do this by setting maximumEmitted on an Emitter, and it is
126 generally useful for Emitters which do not continuously emit particles.
128 Like ShaderEffect, the performance of the particle system is largely dependent on the graphics hardware it is running on.
129 The exception to this is Affectors. For systems not including Affectors, the majority of the performance cost of particles
130 will be on the GPU. Since the GPU is better at parallelizing large numbers of operations more particles can be drawn at 60FPS
131 when Affectors are not used.
133 Affectors, particularly if modifying the particles in javascript, can be relatively slow as well as increasing the CPU cost
134 of using particles. Avoid using them in high-volume systems where possible. Some easy cases where Affectors can be avoided
135 are using timed ParticleGroup transitions instead of time-triggered Affectors, or setting acceleration due to gravity in the
136 acceleration property of the Emitter instead of with a Gravity Affector.
1.10.0