From 963e769c01237265a403e2d28c1b2691cb45bf99 Mon Sep 17 00:00:00 2001 From: Alan Alpert Date: Mon, 11 Jul 2011 11:20:58 +1000 Subject: 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 Reviewed-by: Martin Jones --- doc/src/declarative/particles.qdoc | 116 +++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/src/declarative/particles.qdoc (limited to 'doc/src') 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. +*/ -- cgit v1.2.3