doc/src/declarative/particles.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29   \qmlmodule QtQuick.Particles 2
  30   \title QML Module QtQuick.Particles 2
  31
  32   \brief Elements for the Qt Quick particle system
  33
  34   This QML module contains a particle system for Qt Quick.
  35
  36   For a simple overview of how the system can be used, see \l{qml-particlesystem.html}{Using the Qt Quick Particle System}.
  37
  38   For details on the performance characteristics see \l{qml-particlesystem-performance.html}{Qt Quick Particle System Performance}.
  39
  40 */
  41
  42 /*!
  43     \page qml-particlesystem.html
  44 \inqmlmodule QtQuick 2
  45     \title Using the Qt Quick Particle System
  46
  47     \section1 The ParticleSystem
  48     This particle system contains four main types of QML Elements: ParticleSystem, Painters, Emitters and Affectors.
  49
  50     The ParticleSystem element ties all the other elements together, and manages the shared timeline. Painters, Emitters
  51     and Affectors must all have the same ParticleSystem to be able to interact with each other.
  52
  53     You may have as many ParticleSystems as you want subject to this constraint, so the logical separation is to have
  54     one ParticleSystem for all the elements that you want to interact, or just one if the number of elements is small
  55     and they are easily kept under control..
  56
  57     \section1 Logical Particles
  58     All the particle system elements act on "logical particles". Every particle has a logical representation inside
  59     the particle system, and this is what the elements act upon. Not every logical particle needs to be visualized,
  60     and some logical particles could lead to multiple visual particles being drawn on screen.
  61
  62     \section1 Particle Groups
  63     Every logical particle is a member of a particle group, and each group is identified by a name. If no other
  64     group has been specified, a logical particle belongs to the group with the name "" (the empty string), which
  65     acts the same as any other group. Groups are used for two purposes, for controlling particles and because they
  66     can have stochastic state transitions.
  67
  68     Groups control particles because you can never access an individual particle with any of the particle system
  69     elements. All elements act on groups as a whole, and so any particles that need to behave differently from each
  70     other (aside from the usual stochastic parameter variation) will need to be in different groups.
  71
  72     Particles can also change groups dynamically. When this happens the particles trajectory is unaltered, but it
  73     can be acted upon by different ParticlePainters or Affectors. Particles can either have their group changed by
  74     an Affector, or stochastic state transitions can be defined in a ParticleGroup element.
  75
  76     Generally, groups should only be defined in a ParticleGroup if they require stochastic state transitions. Otherwise,
  77     it is sufficient to have the groups be defined simply by the strings used in the particle/particles properties
  78     of the elements.
  79
  80     \section1 Emitters
  81     Emitters emit logical particles into the system. These particles have a trajectory and lifespan, but no visualization.
  82     These particles are emitted from the location of the Emitter.
  83
  84     TrailEmitters are a special type of emitter which emits particles from the location of other logicial particles. Any logical
  85     particle of the followed type within the bounds of a TrailEmitter will cause particle emission from its location, as if there
  86     were an Emitter on it with the same properties as the TrailEmitter.
  87
  88     \section1 ParticlePainters
  89     Painters are the elements that visualize logical particles. For each logical particle in the groups assigned to it,
  90     which are within its bounds (or outside, if you do not set the clip property on the element) it will be visualized
  91     in a manner dependent on the type of ParticlePainter.  The base type of ParticlePainter does not draw anything.
  92     ImageParticle renders an image at the particle location. CustomParticle allows you to write your own shaders to render
  93     the particles, passing in the logical particle state as vertex data. ItemParticle allows you to visualize logical
  94     particles using arbitrary QML delegates. ModelParticle is similar, but coordinates model data amongst the delegates
  95     in a similar manner to the view classes.
  96
  97     As the ParticlePainter is the QML element visualizing the particles in the scene, it is its Z value which is important
  98     when trying to place particles above or below other elements visually.
  99
 100     \section1 Affectors
 101     Affectors are an optional component of a particle system. They can perform a variety of manipulations to the simulation,
 102     such as altering the trajectory of particles or prematurely ending their life in the simulation. For performance reasons,
 103     it is recommended not to use Affectors in high-volume particle systems.
 104
 105     \section1 Stochastic Parameters
 106     As particle systems benefit from stochastic control of parameters across a large number of instances, several stochastic
 107     helper types are used by the particle system. If you do not wish to have any stochastic variation in these parameters,
 108     then do not specify any variation in these elements.
 109
 110     \section2 Directions
 111     Directions can be specified by angle and magnitude, or by x and y components. While any direction can be specified with
 112     either method, there is a significant difference between varying the x and y components and varying the angle and magnitude.
 113     Varying the x and y components will lead to a rectangular area around the specified point, while varying the angle will lead
 114     to an arc centered on the specified point.
 115
 116     \section2 Shapes
 117     The particle system contains several elements which represent shapes. These elements do not visualize shapes, and are used
 118     for the purpose of selecting a random point within the shape. If you want a specific point with no randomness, use a 0 width
 119     and 0 height shape (which is the default). Otherwise you can use the shape elements provides to specify an area, so that the
 120     result can use a random point selected from that area.
 121 */
 122
 123 /*!
 124     \page qml-particlesystem-performance.html
 125 \inqmlmodule QtQuick 2
 126     \title Qt Quick Particle System Performance Guide
 127
 128     The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired
 129     effect, performance can be improved by lowering the particle count. Conversely, if performance is well withing acceptable
 130     bounds you can increase the number of particles until you hit that point (should that improve the effect).
 131
 132     Note that particle count is often estimated by the particle system, and in some cases explicitly providing hints as to how
 133     many particles will be needed will improve performance. You can do this by setting maximumEmitted on an Emitter, and it is
 134     generally useful for Emitters which do not continuously emit particles.
 135
 136     Like ShaderEffect, the performance of the particle system is largely dependent on the graphics hardware it is running on.
 137     The exception to this is Affectors. For systems not including Affectors, the majority of the performance cost of particles
 138     will be on the GPU. Since the GPU is better at parallelizing large numbers of operations more particles can be drawn at 60FPS
 139     when Affectors are not used.
 140
 141     Affectors, particularly if modifying the particles in javascript, can be relatively slow as well as increasing the CPU cost
 142     of using particles. Avoid using them in high-volume systems where possible. Some easy cases where Affectors can be avoided
 143     are using timed ParticleGroup transitions instead of time-triggered Affectors, or setting acceleration due to gravity in the
 144     acceleration property of the Emitter instead of with a Gravity Affector.
 145 */