diff options
29 files changed, 761 insertions, 3 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. +*/ diff --git a/src/declarative/particles/qsgangleddirection.cpp b/src/declarative/particles/qsgangleddirection.cpp index 78bf02468f..ffd434f980 100644 --- a/src/declarative/particles/qsgangleddirection.cpp +++ b/src/declarative/particles/qsgangleddirection.cpp @@ -43,6 +43,56 @@ #include <cmath> QT_BEGIN_NAMESPACE const qreal CONV = 0.017453292519943295; +/*! + \qmlclass AngledDirection QSGAngledDirection + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits StochasticDirection + \brief The AngledDirection element allows you to specify a direction that varies in angle + + The AngledDirection element allows both the specification of a direction by angle and magnitude, + as well as varying the parameters by angle or magnitude. +*/ +/*! + \qmlproperty real QtQuick.Particles2::AngledDirection::angle + This property specifies the base angle for the direction. + The angle of this direction will vary by no more than angleVariation + from this angle. + + Angle is specified by degrees clockwise from straight right. + + The default value is zero. +*/ +/*! + \qmlproperty real QtQuick.Particles2::AngledDirection::magnitude + This property specifies the base magnitude for the direction. + The magnitude of this direction will vary by no more than magnitudeVariation + from this magnitude. + + Magnitude is specified in units of pixels per second. + + The default value is zero. +*/ +/*! + \qmlproperty real QtQuick.Particles2::AngledDirection::angleVariation + This property specifies the maximum angle variation for the direction. + The angle of the direction will vary by up to angleVariation clockwise + and anticlockwise from the value specified in angle. + + Angle is specified by degrees clockwise from straight right. + + The default value is zero. +*/ +/*! + \qmlproperty real QtQuick.Particles2::AngledDirection::magnitudeVariation + This property specifies the base magnitude for the direction. + The magnitude of this direction will vary by no more than magnitudeVariation + from the base magnitude. + + Magnitude is specified in units of pixels per second. + + The default value is zero. +*/ QSGAngledDirection::QSGAngledDirection(QObject *parent) : QSGStochasticDirection(parent) , m_angle(0) diff --git a/src/declarative/particles/qsgcumulativedirection.cpp b/src/declarative/particles/qsgcumulativedirection.cpp index fe635e574d..5ffdef6327 100644 --- a/src/declarative/particles/qsgcumulativedirection.cpp +++ b/src/declarative/particles/qsgcumulativedirection.cpp @@ -42,6 +42,15 @@ #include "qsgcumulativedirection_p.h" QT_BEGIN_NAMESPACE +/*! + \qmlclass CumulativeDirection QSGCumulativeDirection + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits StochasticDirection + \brief The CumulativeDirection element allows you to specify a direction made of other directions + + The CumulativeDirection element will act as a direction that sums the directions within it. +*/ QSGCumulativeDirection::QSGCumulativeDirection(QObject *parent):QSGStochasticDirection(parent) { } diff --git a/src/declarative/particles/qsgcustomparticle.cpp b/src/declarative/particles/qsgcustomparticle.cpp index 908169582d..f1477f6ebf 100644 --- a/src/declarative/particles/qsgcustomparticle.cpp +++ b/src/declarative/particles/qsgcustomparticle.cpp @@ -119,6 +119,15 @@ struct PlainVertices { PlainVertex v4; }; +/*! + \qmlclass CustomParticle QSGCustomParticle + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits ParticlePainter + \brief The CustomParticle element allows you to specify your own shader to paint particles. + +*/ + QSGCustomParticle::QSGCustomParticle(QSGItem* parent) : QSGParticlePainter(parent) , m_pleaseReset(true) @@ -137,7 +146,7 @@ void QSGCustomParticle::componentComplete() //Trying to keep the shader conventions the same as in qsgshadereffectitem /*! - \qmlproperty string CustomParticle::fragmentShader + \qmlproperty string QtQuick.Particles2::CustomParticle::fragmentShader This property holds the fragment shader's GLSL source code. The default shader passes the texture coordinate along to the fragment @@ -156,7 +165,7 @@ void QSGCustomParticle::setFragmentShader(const QByteArray &code) } /*! - \qmlproperty string CustomParticle::vertexShader + \qmlproperty string QtQuick.Particles2::CustomParticle::vertexShader This property holds the vertex shader's GLSL source code. The default shader expects the texture coordinate to be passed from the diff --git a/src/declarative/particles/qsgellipseextruder.cpp b/src/declarative/particles/qsgellipseextruder.cpp index e43023324e..59e8803b28 100644 --- a/src/declarative/particles/qsgellipseextruder.cpp +++ b/src/declarative/particles/qsgellipseextruder.cpp @@ -42,12 +42,29 @@ #include "qsgellipseextruder_p.h" #include <cmath> QT_BEGIN_NAMESPACE +/*! + \qmlclass EllipseShape QSGEllipseExtruder + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Shape + \brief The EllipseShape represents an ellipse to other particle system elements + + This shape can be used by Emitter subclasses and Affector subclasses to have + them act upon an ellipse shaped area. +*/ QSGEllipseExtruder::QSGEllipseExtruder(QObject *parent) : QSGParticleExtruder(parent) , m_fill(true) { } +/*! + \qmlproperty bool QtQuick.Particles2::EllipseShape::fill + If fill is true the ellipse is filled; otherwise it is just a border. + + Default is true. +*/ + QPointF QSGEllipseExtruder::extrude(const QRectF & r) { qreal theta = ((qreal)rand()/RAND_MAX) * 6.2831853071795862; diff --git a/src/declarative/particles/qsgemitter.cpp b/src/declarative/particles/qsgemitter.cpp index 67ebcd6716..f05ee6af8a 100644 --- a/src/declarative/particles/qsgemitter.cpp +++ b/src/declarative/particles/qsgemitter.cpp @@ -43,6 +43,24 @@ #include "qsgparticlesystem_p.h" QT_BEGIN_NAMESPACE +/*! + \qmlclass Emitter QSGBasicEmitter + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief The Emitter element allows you to emit logical particles. + + This element emits logical particles into the ParticleSystem, with the + given starting attributes. + + Note that logical particles are not + automatically rendered, you will need to have one or more + ParticlePainter elements visualizing them. + + Note that the given starting attributes can be modified at any point + in the particle's lifetime by any Affector element in the same + ParticleSystem. This includes attributes like lifespan. +*/ + QSGBasicEmitter::QSGBasicEmitter(QSGItem* parent) : QSGParticleEmitter(parent) , m_speed_from_movement(0) @@ -54,6 +72,52 @@ QSGBasicEmitter::QSGBasicEmitter(QSGItem* parent) // setFlag(ItemHasContents); } +/*! + \qmlproperty ParticleSystem QtQuick.Particles2::Emitter::system + + This is the Particle system that the Emitter will emit into. + This can be omitted if the Emitter is a direct child of the ParticleSystem +*/ +/*! + \qmlproperty string QtQuick.Particles2::Emitter::particle +*/ +/*! + \qmlproperty Shape QtQuick.Particles2::Emitter::shape +*/ +/*! + \qmlproperty bool QtQuick.Particles2::Emitter::emitting +*/ +/*! + \qmlproperty real QtQuick.Particles2::Emitter::emitRate +*/ +/*! + \qmlproperty int QtQuick.Particles2::Emitter::lifeSpan +*/ +/*! + \qmlproperty int QtQuick.Particles2::Emitter::lifeSpanVariation +*/ +/*! + \qmlproperty int QtQuick.Particles2::Emitter::emitCap +*/ +/*! + \qmlproperty real QtQuick.Particles2::Emitter::size +*/ +/*! + \qmlproperty real QtQuick.Particles2::Emitter::endSize +*/ +/*! + \qmlproperty real QtQuick.Particles2::Emitter::sizeVariation +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::Emitter::speed +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::Emitter::acceleration +*/ +/*! + \qmlproperty qreal QtQuick.Particles2::Emitter::speedFromMovement +*/ + void QSGBasicEmitter::setSpeedFromMovement(qreal t) { if (t == m_speed_from_movement) diff --git a/src/declarative/particles/qsgfollowemitter.cpp b/src/declarative/particles/qsgfollowemitter.cpp index 9b5b084705..ff9f83df14 100644 --- a/src/declarative/particles/qsgfollowemitter.cpp +++ b/src/declarative/particles/qsgfollowemitter.cpp @@ -44,6 +44,23 @@ #include <cmath> QT_BEGIN_NAMESPACE +/*! + \qmlclass Emitter QSGBasicEmitter + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief The Emitter element allows you to emit logical particles. + + This element emits logical particles into the ParticleSystem, with the + given starting attributes. + + Note that logical particles are not + automatically rendered, you will need to have one or more + ParticlePainter elements visualizing them. + + Note that the given starting attributes can be modified at any point + in the particle's lifetime by any Affector element in the same + ParticleSystem. This includes attributes like lifespan. +*/ QSGFollowEmitter::QSGFollowEmitter(QSGItem *parent) : QSGParticleEmitter(parent) , m_particlesPerParticlePerSecond(0) @@ -63,6 +80,65 @@ QSGFollowEmitter::QSGFollowEmitter(QSGItem *parent) : this, SLOT(recalcParticlesPerSecond())); } + +/*! + \qmlproperty ParticleSystem QtQuick.Particles2::FollowEmitter::system + + This is the Particle system that the FollowEmitter will emit into. + This can be omitted if the FollowEmitter is a direct child of the ParticleSystem +*/ +/*! + \qmlproperty string QtQuick.Particles2::FollowEmitter::particle +*/ +/*! + \qmlproperty string QtQuick.Particles2::FollowEmitter::follow +*/ +/*! + \qmlproperty Shape QtQuick.Particles2::FollowEmitter::shape +*/ +/*! + \qmlproperty Shape QtQuick.Particles2::FollowEmitter::emitShape +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::emitWidth +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::emitHeight +*/ +/*! + \qmlproperty bool QtQuick.Particles2::FollowEmitter::emitting +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::emitRatePerParticle +*/ +/*! + \qmlproperty int QtQuick.Particles2::FollowEmitter::lifeSpan +*/ +/*! + \qmlproperty int QtQuick.Particles2::FollowEmitter::lifeSpanVariation +*/ +/*! + \qmlproperty int QtQuick.Particles2::FollowEmitter::emitCap +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::size +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::endSize +*/ +/*! + \qmlproperty real QtQuick.Particles2::FollowEmitter::sizeVariation +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::FollowEmitter::speed +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::FollowEmitter::acceleration +*/ +/*! + \qmlproperty qreal QtQuick.Particles2::FollowEmitter::speedFromMovement +*/ + void QSGFollowEmitter::recalcParticlesPerSecond(){ if (!m_system) return; diff --git a/src/declarative/particles/qsgfriction.cpp b/src/declarative/particles/qsgfriction.cpp index 2bd4391503..fcd43a57d9 100644 --- a/src/declarative/particles/qsgfriction.cpp +++ b/src/declarative/particles/qsgfriction.cpp @@ -41,6 +41,19 @@ #include "qsgfriction_p.h" QT_BEGIN_NAMESPACE +/*! + \qmlclass Friction QSGFrictionAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The Friction affector slows down movement proportional to the particle's current speed. + +*/ + +/*! + \qmlproperty real QtQuick.Particles2::Friction::factor +*/ + QSGFrictionAffector::QSGFrictionAffector(QSGItem *parent) : QSGParticleAffector(parent), m_factor(0.0) { diff --git a/src/declarative/particles/qsggravity.cpp b/src/declarative/particles/qsggravity.cpp index 0959c76694..1639588917 100644 --- a/src/declarative/particles/qsggravity.cpp +++ b/src/declarative/particles/qsggravity.cpp @@ -43,6 +43,25 @@ #include <cmath> QT_BEGIN_NAMESPACE const qreal CONV = 0.017453292520444443; +/*! + \qmlclass Gravity QSGGravityAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The Gravity element allows you to set a constant accleration in an angle + + This element will set the acceleration of all affected particles to a vector of + the specified magnitude in the specified angle. +*/ + +/*! + \qmlproperty real QtQuick.Particles2::Gravity::acceleration + +*/ +/*! + \qmlproperty real QtQuick.Particles2::Gravity::angle +*/ + QSGGravityAffector::QSGGravityAffector(QSGItem *parent) : QSGParticleAffector(parent), m_acceleration(-10), m_angle(90), m_xAcc(0), m_yAcc(0) { diff --git a/src/declarative/particles/qsgimageparticle.cpp b/src/declarative/particles/qsgimageparticle.cpp index aa7382190d..8c04175010 100644 --- a/src/declarative/particles/qsgimageparticle.cpp +++ b/src/declarative/particles/qsgimageparticle.cpp @@ -278,6 +278,78 @@ QSGMaterialShader *SimpleMaterial::createShader() const { return new SimpleMaterialData; } +/*! + \qmlclass ImageParticle QSGImageParticle + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits ParticlePainter + \brief The ImageParticle element visualizes logical particles using an image + + This element renders a logical particle as an image. The image can be + - colorized + - roatated + - deformed + - a sprite-based animation +*/ +/*! + \qmlproperty url QtQuick.Particles2::ImageParticle::source +*/ +/*! + \qmlproperty url QtQuick.Particles2::ImageParticle::colorTable +*/ +/*! + \qmlproperty url QtQuick.Particles2::ImageParticle::sizeTable +*/ +/*! + \qmlproperty url QtQuick.Particles2::ImageParticle::opacityTable +*/ +/*! + \qmlproperty color QtQuick.Particles2::ImageParticle::color +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::colorVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::redVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::greenVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::blueVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::alpha +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::alphaVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::rotation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::rotationVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeed +*/ +/*! + \qmlproperty real QtQuick.Particles2::ImageParticle::rotationSpeedVariation +*/ +/*! + \qmlproperty bool QtQuick.Particles2::ImageParticle::autoRotation +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::xVector +*/ +/*! + \qmlproperty StochasticDirection QtQuick.Particles2::ImageParticle::yVector +*/ +/*! + \qmlproperty list<Sprite> QtQuick.Particles2::ImageParticle::sprites +*/ + + QSGImageParticle::QSGImageParticle(QSGItem* parent) : QSGParticlePainter(parent) , m_do_reset(false) diff --git a/src/declarative/particles/qsgitemparticle.cpp b/src/declarative/particles/qsgitemparticle.cpp index 625c98ba61..1d2d166242 100644 --- a/src/declarative/particles/qsgitemparticle.cpp +++ b/src/declarative/particles/qsgitemparticle.cpp @@ -48,6 +48,15 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass ItemParticle QSGItemParticle + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits ParticlePainter + \brief The ItemParticle element allows you to specify your own delegate to paint particles. + +*/ + QSGItemParticle::QSGItemParticle(QSGItem *parent) : QSGParticlePainter(parent), m_fade(true), m_delegate(0) { diff --git a/src/declarative/particles/qsgkill.cpp b/src/declarative/particles/qsgkill.cpp index b9373ef34c..9d4bc940bd 100644 --- a/src/declarative/particles/qsgkill.cpp +++ b/src/declarative/particles/qsgkill.cpp @@ -42,6 +42,15 @@ #include "qsgkill_p.h" #include "qsgparticleemitter_p.h" QT_BEGIN_NAMESPACE +/*! + \qmlclass Kill QSGKillAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The Kill affector allows you to expire affected particles + +*/ + QSGKillAffector::QSGKillAffector(QSGItem *parent) : QSGParticleAffector(parent) { diff --git a/src/declarative/particles/qsglineextruder.cpp b/src/declarative/particles/qsglineextruder.cpp index 5acb2b2d1a..a08d052c20 100644 --- a/src/declarative/particles/qsglineextruder.cpp +++ b/src/declarative/particles/qsglineextruder.cpp @@ -41,6 +41,25 @@ #include "qsglineextruder_p.h" #include <cmath> +/*! + \qmlclass LineShape QSGLineExtruder + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Shape + \brief The LineShape represents a line to Affectors and Emitter + +*/ + +/*! + \qmlproperty bool QtQuick.Particles2::LineShape::mirrored + + By default, the line goes from (0,0) to (width, height) of the item that + this shape is being applied to. + + If mirrored is set to true, this will be mirrored along the y axis. + The line will then go from (0,height) to (width, 0). +*/ + QSGLineExtruder::QSGLineExtruder(QObject *parent) : QSGParticleExtruder(parent), m_mirrored(false) { diff --git a/src/declarative/particles/qsgmaskextruder.cpp b/src/declarative/particles/qsgmaskextruder.cpp index 4119c95be7..e76280378b 100644 --- a/src/declarative/particles/qsgmaskextruder.cpp +++ b/src/declarative/particles/qsgmaskextruder.cpp @@ -43,6 +43,19 @@ #include <QImage> #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass MaskShape QSGMaskExtruder + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Shape + \brief The MaskShape element allows you to represent an image as a shape to affectors and emitters. + +*/ +/*! + \qmlproperty url QtQuick.Particles2::MaskShape::source +*/ + + QSGMaskExtruder::QSGMaskExtruder(QObject *parent) : QSGParticleExtruder(parent) , m_lastWidth(-1) diff --git a/src/declarative/particles/qsgmodelparticle.cpp b/src/declarative/particles/qsgmodelparticle.cpp index 60c44381c7..844b76dcb2 100644 --- a/src/declarative/particles/qsgmodelparticle.cpp +++ b/src/declarative/particles/qsgmodelparticle.cpp @@ -46,6 +46,15 @@ #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass ModelParticle QSGModelParticle + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits ParticlePainter + \brief The ModelParticle element allows you to specify a model and delegate pair to paint particles. + +*/ + QSGModelParticle::QSGModelParticle(QSGItem *parent) : QSGParticlePainter(parent), m_ownModel(false), m_comp(0), m_model(0), m_fade(true), m_modelCount(0) diff --git a/src/declarative/particles/qsgparticleaffector.cpp b/src/declarative/particles/qsgparticleaffector.cpp index 7c6eac53c8..bf268efc9d 100644 --- a/src/declarative/particles/qsgparticleaffector.cpp +++ b/src/declarative/particles/qsgparticleaffector.cpp @@ -42,6 +42,64 @@ #include "qsgparticleaffector_p.h" #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass Affector QSGParticleAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief Affector elements can alter the attributes of logical particles at any point in their lifetime. + + The base Affector does not alter any attributes, but can be used to emit a signal + when a particle meets certain conditions. + + If an affector has a defined size, then it will only affect particles within its size and position on screen. +*/ +/*! + \qmlproperty ParticleSystem QtQuick.Particles2::Affector::system + This is the system which will be affected by the element. + If the Affector is a direct child of a ParticleSystem, it will automatically be associated with it. +*/ +/*! + \qmlproperty list<string> QtQuick.Particles2::Affector::particles + Which logical particle groups will be affected. + + If empty, it will affect all particles. +*/ +/*! + \qmlproperty list<string> QtQuick.Particles2::Affector::collisionParticles + If any logical particle groups are specified here, then the affector + will only be triggered if the particle being examined intersects with + a particle of one of these groups. + + By default, no groups are specified. +*/ +/*! + \qmlproperty bool QtQuick.Particles2::Affector::active + If active is set to false, this affector will not affect any particles. + + Usually this is used to conditionally turn an affector on or off. + + Default value is true. +*/ +/*! + \qmlproperty bool QtQuick.Particles2::Affector::onceOff + If onceOff is set to true, this affector will only affect each particle + once in their lifetimes. + + Default value is false. +*/ +/*! + \qmlproperty Shape QtQuick.Particles2::Affector::shape + If a size has been defined, the shape property can be used to affect a + non-rectangular area. +*/ +/*! + \qmlproperty bool QtQuick.Particles2::Affector::signal + If this is set to true, then an affected(x,y) signal will be emitted each + time this affector affects a particle. + + Default value is false. +*/ + QSGParticleAffector::QSGParticleAffector(QSGItem *parent) : QSGItem(parent), m_needsReset(false), m_system(0), m_active(true) , m_updateIntSet(false), m_shape(new QSGParticleExtruder(this)), m_signal(false) diff --git a/src/declarative/particles/qsgparticleemitter.cpp b/src/declarative/particles/qsgparticleemitter.cpp index 9f8a5e7b42..dfd1618088 100644 --- a/src/declarative/particles/qsgparticleemitter.cpp +++ b/src/declarative/particles/qsgparticleemitter.cpp @@ -41,6 +41,7 @@ #include "qsgparticleemitter_p.h" QT_BEGIN_NAMESPACE +//Not visible from QML, so not documented. Document subclasses. QSGParticleEmitter::QSGParticleEmitter(QSGItem *parent) : QSGItem(parent) , m_particlesPerSecond(10) diff --git a/src/declarative/particles/qsgparticleemitter_p.h b/src/declarative/particles/qsgparticleemitter_p.h index 8967a5285d..9cf130d40d 100644 --- a/src/declarative/particles/qsgparticleemitter_p.h +++ b/src/declarative/particles/qsgparticleemitter_p.h @@ -60,7 +60,6 @@ QT_MODULE(Declarative) class QSGParticleEmitter : public QSGItem { Q_OBJECT - //###currently goes in emitters OR sets system. Pick one? Q_PROPERTY(QSGParticleSystem* system READ system WRITE setSystem NOTIFY systemChanged) Q_PROPERTY(QString particle READ particle WRITE setParticle NOTIFY particleChanged) Q_PROPERTY(QSGParticleExtruder* shape READ extruder WRITE setExtruder NOTIFY extruderChanged) diff --git a/src/declarative/particles/qsgparticleextruder.cpp b/src/declarative/particles/qsgparticleextruder.cpp index 965cfc5a6a..b51ab8b467 100644 --- a/src/declarative/particles/qsgparticleextruder.cpp +++ b/src/declarative/particles/qsgparticleextruder.cpp @@ -43,6 +43,15 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass Shape QSGParticleExtruder + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief The Shape element allows you to specify an area for affectors and emitter. + + The base class is just a rectangle. +*/ + QSGParticleExtruder::QSGParticleExtruder(QObject *parent) : QObject(parent), m_fill(true) { diff --git a/src/declarative/particles/qsgparticlepainter.cpp b/src/declarative/particles/qsgparticlepainter.cpp index 6c892b4983..7bcaefa66f 100644 --- a/src/declarative/particles/qsgparticlepainter.cpp +++ b/src/declarative/particles/qsgparticlepainter.cpp @@ -42,6 +42,28 @@ #include "qsgparticlepainter_p.h" #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass ParticlePainter QSGParticlePainter + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits ParticlePainter + \brief ParticlePainter elements allow you to specify how to paint particles. + + The default implementation paints nothing. See the subclasses if you want to + paint something visible. + +*/ +/*! + \qmlproperty ParticleSystem QtQuick.Particles2::ParticlePainter::system + This is the system whose particles can be painted by the element. + If the ParticlePainter is a direct child of a ParticleSystem, it will automatically be associated with it. +*/ +/*! + \qmlproperty list<string> QtQuick.Particles2::ParticlePainter::particles + Which logical particle groups will be painted. + + If empty, it will paint the default particle (""). +*/ QSGParticlePainter::QSGParticlePainter(QSGItem *parent) : QSGItem(parent), m_system(0), m_count(0), m_sentinel(new QSGParticleData(0)) diff --git a/src/declarative/particles/qsgparticlesystem.cpp b/src/declarative/particles/qsgparticlesystem.cpp index 15a0119ac5..98c685f4b2 100644 --- a/src/declarative/particles/qsgparticlesystem.cpp +++ b/src/declarative/particles/qsgparticlesystem.cpp @@ -52,6 +52,37 @@ #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass ParticleSystem QSGParticleSystem + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief The ParticleSystem brings together ParticlePainter, Emitter and Affector elements. + +*/ + +/*! + \qmlproperty bool QtQuick.Particles2::ParticleSystem::running + + If running is set to false, the particle system will not advance the simulation. +*/ +/*! + \qmlproperty int QtQuick.Particles2::ParticleSystem::startTime + + If start time is specified, then the system will simulate up to this time + before the system starts playing. This allows you to appear to start with a + fully populated particle system, instead of starting with no particles visible. +*/ +/*! + \qmlproperty list<Sprite> QtQuick.Particles2::ParticleSystem::particleStates + + You can define a sub-set of particle groups in this property in order to provide them + with stochastic state transitions. + + Each QtQuick2::Sprite in this list is interpreted as corresponding to the particle group + with ths same name. Any transitions defined in these sprites will take effect on the particle + groups as well. Additionally FollowEmitters, Affectors and ParticlePainters definined + inside one of these sprites are automatically associated with the corresponding particle group. +*/ const qreal EPSILON = 0.001; //Utility functions for when within 1ms is close enough diff --git a/src/declarative/particles/qsgpointattractor.cpp b/src/declarative/particles/qsgpointattractor.cpp index 9b4c997817..6be61aa716 100644 --- a/src/declarative/particles/qsgpointattractor.cpp +++ b/src/declarative/particles/qsgpointattractor.cpp @@ -43,6 +43,19 @@ #include <cmath> #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass PointAttractor QSGPointAttractorAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The PointAttractor allows you to attract particles towards a specific point. + + Note that the size and position of this element affects which particles it affects. + The size of the point attracted to is always 0x0, and the location of that point + is specified by the x and y properties that badly need renaming. + +*/ + QSGPointAttractorAffector::QSGPointAttractorAffector(QSGItem *parent) : QSGParticleAffector(parent), m_strength(0.0), m_x(0), m_y(0) , m_physics(Velocity), m_proportionalToDistance(Linear) diff --git a/src/declarative/particles/qsgpointdirection.cpp b/src/declarative/particles/qsgpointdirection.cpp index 5b916500d0..0448ac9a7e 100644 --- a/src/declarative/particles/qsgpointdirection.cpp +++ b/src/declarative/particles/qsgpointdirection.cpp @@ -43,6 +43,29 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass PointDirection QSGPointDirection + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits StochasticDirection + \brief The PointDirection element allows you to specify a direction that varies in x and y components + + The PointDirection element allows both the specification of a direction by x and y components, + as well as varying the parameters by x or y component. +*/ +/*! + \qmlproperty real QtQuick.Particles2::PointDirection::x +*/ +/*! + \qmlproperty real QtQuick.Particles2::PointDirection::y +*/ +/*! + \qmlproperty real QtQuick.Particles2::PointDirection::xVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::PointDirection::yVariation +*/ + QSGPointDirection::QSGPointDirection(QObject *parent) : QSGStochasticDirection(parent) , m_x(0) diff --git a/src/declarative/particles/qsgspritegoal.cpp b/src/declarative/particles/qsgspritegoal.cpp index 1c59034f23..79fcf8188c 100644 --- a/src/declarative/particles/qsgspritegoal.cpp +++ b/src/declarative/particles/qsgspritegoal.cpp @@ -47,6 +47,28 @@ QT_BEGIN_NAMESPACE +/*! + \qmlclass SpriteGoal QSGSpriteGoalAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The SpriteGoal Affector allows you to change the state of a sprite or group of a particle. + +*/ +/*! + \qmlproperty string QtQuick.Particles2::SpriteGoal::goalState +*/ +/*! + \qmlproperty bool QtQuick.Particles2::SpriteGoal::jump +*/ +/*! + \qmlproperty bool QtQuick.Particles2::SpriteGoal::systemStates +*/ + + Q_PROPERTY(QString goalState READ goalState WRITE setGoalState NOTIFY goalStateChanged) + Q_PROPERTY(bool jump READ jump WRITE setJump NOTIFY jumpChanged) + Q_PROPERTY(bool systemStates READ systemStates WRITE setSystemStates NOTIFY systemStatesChanged) + QSGSpriteGoalAffector::QSGSpriteGoalAffector(QSGItem *parent) : QSGParticleAffector(parent), m_goalIdx(-1), m_jump(false), m_systemStates(false), m_lastEngine(0), m_notUsingEngine(false) { diff --git a/src/declarative/particles/qsgstochasticdirection.cpp b/src/declarative/particles/qsgstochasticdirection.cpp index 38def96b21..f44b941578 100644 --- a/src/declarative/particles/qsgstochasticdirection.cpp +++ b/src/declarative/particles/qsgstochasticdirection.cpp @@ -42,6 +42,14 @@ #include "qsgstochasticdirection_p.h" QT_BEGIN_NAMESPACE +/*! + \qmlclass StochasticDirection QSGStochasticDirection + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \brief The StochasticDirection elements allow you to specify a vector space. + +*/ + QSGStochasticDirection::QSGStochasticDirection(QObject *parent) : QObject(parent) diff --git a/src/declarative/particles/qsgtargeteddirection.cpp b/src/declarative/particles/qsgtargeteddirection.cpp index 0f6c0df22f..3e5d3e1628 100644 --- a/src/declarative/particles/qsgtargeteddirection.cpp +++ b/src/declarative/particles/qsgtargeteddirection.cpp @@ -45,6 +45,44 @@ #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass TargetedDirection QSGTargetedDirection + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits StochasticDirection + \brief The TargetedDirection element allows you to specify a direction towards the target point + +*/ +/*! + \qmlproperty real QtQuick.Particles2::TargetedDirection::targetX +*/ +/*! + \qmlproperty real QtQuick.Particles2::TargetedDirection::targetY +*/ +/*! + \qmlproperty Item QtQuick.Particles2::TargetedDirection::targetItem + If specified, this will take precedence over targetX and targetY. + The targeted point will be the center of the specified Item +*/ +/*! + \qmlproperty real QtQuick.Particles2::TargetedDirection::targetVariation +*/ +/*! + \qmlproperty real QtQuick.Particles2::TargetedDirection::magnitude +*/ +/*! + \qmlproperty real QtQuick.Particles2::TargetedDirection::magnitudeVariation +*/ +/*! + \qmlproperty bool QtQuick.Particles2::TargetedDirection::proportionalMagnitude + + If true, then the value of magnitude and magnitudeVariation shall be interpreted as multiples + of the distance between the source point and the target point, per second. + + If false(default), then the value of magnitude and magnitudeVariation shall be interpreted as + pixels per second. +*/ + QSGTargetedDirection::QSGTargetedDirection(QObject *parent) : QSGStochasticDirection(parent) , m_targetX(0) diff --git a/src/declarative/particles/qsgtargeteddirection_p.h b/src/declarative/particles/qsgtargeteddirection_p.h index 3a7e0d0af0..6fdd3f937d 100644 --- a/src/declarative/particles/qsgtargeteddirection_p.h +++ b/src/declarative/particles/qsgtargeteddirection_p.h @@ -59,6 +59,7 @@ class QSGTargetedDirection : public QSGStochasticDirection Q_PROPERTY(qreal targetVariation READ targetVariation WRITE setTargetVariation NOTIFY targetVariationChanged) + //TODO: An enum would be better Q_PROPERTY(bool proportionalMagnitude READ proportionalMagnitude WRITE setProportionalMagnitude NOTIFY proprotionalMagnitudeChanged) Q_PROPERTY(qreal magnitude READ magnitude WRITE setMagnitude NOTIFY magnitudeChanged) Q_PROPERTY(qreal magnitudeVariation READ magnitudeVariation WRITE setMagnitudeVariation NOTIFY magnitudeVariationChanged) diff --git a/src/declarative/particles/qsgturbulence.cpp b/src/declarative/particles/qsgturbulence.cpp index 929c6527a0..c846f151b4 100644 --- a/src/declarative/particles/qsgturbulence.cpp +++ b/src/declarative/particles/qsgturbulence.cpp @@ -46,6 +46,27 @@ #include <QDebug> QT_BEGIN_NAMESPACE +/*! + \qmlclass Turbulence QSGTurbulenceAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The TurbulenceAffector is a bit of a hack and probably shouldn't be used yet. + +*/ +/*! + \qmlproperty int QtQuick.Particles2::Turbulence::strength + Maximum magnitude of a point in the vector field. +*/ +/*! + \qmlproperty int QtQuick.Particles2::Turbulence::frequency + Times per second vector field is perturbed. +*/ +/*! + \qmlproperty int QtQuick.Particles2::Turbulence::gridSize + Square root of the number of points in the vector field simulcrum. +*/ + QSGTurbulenceAffector::QSGTurbulenceAffector(QSGItem *parent) : QSGParticleAffector(parent), m_strength(10), m_lastT(0), m_frequency(64), m_gridSize(10), m_field(0), m_inited(false) diff --git a/src/declarative/particles/qsgwander.cpp b/src/declarative/particles/qsgwander.cpp index 70e43a8923..849f2880a6 100644 --- a/src/declarative/particles/qsgwander.cpp +++ b/src/declarative/particles/qsgwander.cpp @@ -42,6 +42,14 @@ #include "qsgwander_p.h" #include "qsgparticlesystem_p.h"//for ParticlesVertices QT_BEGIN_NAMESPACE +/*! + \qmlclass Wander QSGWanderAffector + \inqmlmodule QtQuick.Particles 2 + \since QtQuick.Particles 2.0 + \inherits Affector + \brief The Wander affector allows particles to randomly vary their trajectory. + +*/ QSGWanderAffector::QSGWanderAffector(QSGItem *parent) : QSGParticleAffector(parent), m_xVariance(0), m_yVariance(0), m_pace(0) |