From 2d4e6ff9dd1e0e3410c4dc002c25d80fecfeafd2 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 9 Feb 2012 17:31:02 +0100 Subject: Doc: Overhaul of doc/src/declarative and QtQuick2 docs. -Consolidated model/view documentation into one. -Added a new navigation for all overviews (grouped the pages) -New front page that shows the grouping -Separated the Qt C++ from the main QML overviews -Consolidated Qt C++ into the "declarative runtime" section -New articles about JavaScript, the engine, and plugins -Fixed the older examples. New snippet comments -Renamed some of the articles -kept the qtquick2 qmlmodule -"Qt Quick Elements" Moved contents of doc/src/declarative into respective module dirs. -Qt Quick 2, LocalStorage, Particles, and QML are now separate. -Removed unused or duplicate documentation. -edited C++ examples -removed navigation and "\inqmlmodule QtQuick 2" for those pages that are not in Qt Quick 2 -fixed doc/src/ licenses to header.FDL from qtbase Change-Id: Ib36f9c07565d91160fa8d04f9670c438f684b82a Reviewed-by: Sergio Ahumada --- doc/src/particles/particles.qdoc | 145 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 doc/src/particles/particles.qdoc (limited to 'doc/src/particles') diff --git a/doc/src/particles/particles.qdoc b/doc/src/particles/particles.qdoc new file mode 100644 index 0000000000..d51bcdf11f --- /dev/null +++ b/doc/src/particles/particles.qdoc @@ -0,0 +1,145 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule QtQuick.Particles 2 + \title QML Module QtQuick.Particles 2 + + \brief Elements for the Qt Quick particle system + + This QML module contains a particle system for Qt Quick. + + For a simple overview of how the system can be used, see \l{qml-particlesystem.html}{Using the Qt Quick Particle System}. + + For details on the performance characteristics see \l{qml-particlesystem-performance.html}{Qt Quick Particle System Performance}. + +*/ + +/*! + \page qml-particlesystem.html +\inqmlmodule QtQuick.Particles 2 + \title Using the Qt Quick Particle System + + \section1 The ParticleSystem + This particle system contains four main types of QML Elements: ParticleSystem, Painters, Emitters and Affectors. + + The ParticleSystem element ties all the other elements together, and manages the shared timeline. Painters, Emitters + and Affectors must all have the same ParticleSystem to be able to interact with each other. + + You may have as many ParticleSystems as you want subject to this constraint, so the logical separation is to have + one ParticleSystem for all the elements that you want to interact, or just one if the number of elements is small + and they are easily kept under control.. + + \section1 Logical Particles + All the particle system elements act on "logical particles". Every particle has a logical representation inside + the particle system, and this is what the elements act upon. Not every logical particle needs to be visualized, + and some logical particles could lead to multiple visual particles being drawn on screen. + + \section1 Particle Groups + Every logical particle is a member of a particle group, and each group is identified by a name. If no other + group has been specified, a logical particle belongs to the group with the name "" (the empty string), which + acts the same as any other group. Groups are used for two purposes, for controlling particles and because they + can have stochastic state transitions. + + Groups control particles because you can never access an individual particle with any of the particle system + elements. All elements act on groups as a whole, and so any particles that need to behave differently from each + other (aside from the usual stochastic parameter variation) will need to be in different groups. + + Particles can also change groups dynamically. When this happens the particles trajectory is unaltered, but it + can be acted upon by different ParticlePainters or Affectors. Particles can either have their group changed by + an Affector, or stochastic state transitions can be defined in a ParticleGroup element. + + Generally, groups should only be defined in a ParticleGroup if they require stochastic state transitions. Otherwise, + it is sufficient to have the groups be defined simply by the strings used in the particle/particles properties + of the elements. + + \section1 Emitters + Emitters emit logical particles into the system. These particles have a trajectory and lifespan, but no visualization. + These particles are emitted from the location of the Emitter. + + TrailEmitters are a special type of emitter which emits particles from the location of other logicial particles. Any logical + particle of the followed type within the bounds of a TrailEmitter will cause particle emission from its location, as if there + were an Emitter on it with the same properties as the TrailEmitter. + + \section1 ParticlePainters + Painters are the elements that visualize logical particles. For each logical particle in the groups assigned to it, + which are within its bounds (or outside, if you do not set the clip property on the element) it will be visualized + in a manner dependent on the type of ParticlePainter. The base type of ParticlePainter does not draw anything. + ImageParticle renders an image at the particle location. CustomParticle allows you to write your own shaders to render + the particles, passing in the logical particle state as vertex data. ItemParticle allows you to visualize logical + particles using arbitrary QML delegates. ModelParticle is similar, but coordinates model data amongst the delegates + in a similar manner to the view classes. + + As the ParticlePainter is the QML element visualizing the particles in the scene, it is its Z value which is important + when trying to place particles above or below other elements visually. + + \section1 Affectors + Affectors are an optional component of a particle system. They can perform a variety of manipulations to the simulation, + such as altering the trajectory of particles or prematurely ending their life in the simulation. For performance reasons, + it is recommended not to use Affectors in high-volume particle systems. + + \section1 Stochastic Parameters + As particle systems benefit from stochastic control of parameters across a large number of instances, several stochastic + helper types are used by the particle system. If you do not wish to have any stochastic variation in these parameters, + then do not specify any variation in these elements. + + \section2 Directions + Directions can be specified by angle and magnitude, or by x and y components. While any direction can be specified with + either method, there is a significant difference between varying the x and y components and varying the angle and magnitude. + Varying the x and y components will lead to a rectangular area around the specified point, while varying the angle will lead + to an arc centered on the specified point. + + \section2 Shapes + The particle system contains several elements which represent shapes. These elements do not visualize shapes, and are used + for the purpose of selecting a random point within the shape. If you want a specific point with no randomness, use a 0 width + and 0 height shape (which is the default). Otherwise you can use the shape elements provides to specify an area, so that the + result can use a random point selected from that area. +*/ + +/*! + \page qml-particlesystem-performance.html +\inqmlmodule QtQuick 2 + \title Qt Quick Particle System Performance Guide + + The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired + effect, performance can be improved by lowering the particle count. Conversely, if performance is well within the acceptable + bounds, you can increase the number of particles until you hit that point (should that improve the effect). + + Note that particle count is often estimated by the particle system, and in some cases explicitly providing hints as to how + many particles will be needed will improve performance. You can do this by setting maximumEmitted on an Emitter, and it is + generally useful for Emitters which do not continuously emit particles. + + Like ShaderEffect, the performance of the particle system is largely dependent on the graphics hardware it is running on. + The exception to this is Affectors. For systems not including Affectors, the majority of the performance cost of particles + will be on the GPU. Since the GPU is better at parallelizing large numbers of operations more particles can be drawn at 60FPS + when Affectors are not used. + + Affectors, particularly if modifying the particles in javascript, can be relatively slow as well as increasing the CPU cost + of using particles. Avoid using them in high-volume systems where possible. Some easy cases where Affectors can be avoided + are using timed ParticleGroup transitions instead of time-triggered Affectors, or setting acceleration due to gravity in the + acceleration property of the Emitter instead of with a Gravity Affector. +*/ -- cgit v1.2.3