Initial stab at docs for QtQuick.Particles 2.0

Change-Id: I3c53f7998dff95616a994edf19094fa4007d74ab
Reviewed-on: http://codereview.qt.nokia.com/1388
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Martin Jones <martin.jones@nokia.com>

1 files changed, 116 insertions, 0 deletions

diff --git a/doc/src/declarative/particles.qdoc b/doc/src/declarative/particles.qdoc
new file mode 100644
index 0000000000..9f1da69eb8
--- /dev/null
+++ b/doc/src/declarative/particles.qdoc
@@ -0,0 +1,116 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** 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-particles.html}{Using the Qt Quick Particle System}.
+
+*/
+
+/*!
+    \page qml-particlesystem.html
+    \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 state changed by
+    an Affector, or stochastic state transitions can be defined in the group definition (in the particleStates property).
+    Generally, groups should only be defined in that property 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.
+
+    FollowEmitters 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 FollowEmitter will cause particle emission from its location, as if there
+    were an Emitter on it with the same properties as the FollowEmitter.
+
+    \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 dependant 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 specfied 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.
+*/