diff options
Diffstat (limited to 'src/quick/doc/src/concepts/effects')
| -rw-r--r-- | src/quick/doc/src/concepts/effects/particles.qdoc | 155 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/effects/shaders.qdoc | 53 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/effects/sprites.qdoc | 181 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/effects/topic.qdoc | 88 | ||||
| -rw-r--r-- | src/quick/doc/src/concepts/effects/transformations.qdoc | 36 |
5 files changed, 513 insertions, 0 deletions
diff --git a/src/quick/doc/src/concepts/effects/particles.qdoc b/src/quick/doc/src/concepts/effects/particles.qdoc new file mode 100644 index 0000000000..2809ce4f85 --- /dev/null +++ b/src/quick/doc/src/concepts/effects/particles.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** 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.0 + \title QML Module QtQuick.Particles 2.0 + + \brief Contains types for particle effects + + This QML module contains a particle system for Qt Quick. To use these types, import the module with the following line: + \code + import QtQuick.Particles 2.0 + \endcode + + For a simple overview of how the system can be used, see \l{Using the Qt Quick Particle System}. + + For details on the performance characteristics see \l{qtquick-particles-performance.html}{Qt Quick Particle System Performance}. + +*/ + +/*! + \page qtquick-effects-particles.html + \inqmlmodule QtQuick.Particles 2.0 + \title Using the Qt Quick Particle System + + Documentation for all Particle System elements can be found on the \l{QML Module QtQuick.Particles 2}{QtQuick.Particles} module page. + + Note that to use elements from the particles module, you will need to import the types with the following line: + \code + import QtQuick.Particles 2.0 + \endcode + + \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 qtquick-particles-performance.html + \inqmlmodule QtQuick 2.0 + \title 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. +*/ diff --git a/src/quick/doc/src/concepts/effects/shaders.qdoc b/src/quick/doc/src/concepts/effects/shaders.qdoc new file mode 100644 index 0000000000..c778cec789 --- /dev/null +++ b/src/quick/doc/src/concepts/effects/shaders.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qtquick-shaders +\page qtquick-effects-shaders.html +\title Qt Quick Shader Effects +\brief For applying OpenGL vertex and fragment shaders to rectangles + +\section1 Related Types +\generatelist{related} + +\section1 Shaders +Describe Shaders and where it could be used in UIs or applications +Mention OpenGL shader language (GLSL) + +\section1 ShaderEffect Element +Introduce the \l{QtQuick2::ShaderEffect} Element. +Say what is possible and how to load shaders + +\section1 Shader Overview +Go over shaders in more detail and what shaders actually do. + +\section2 Vertex Shader +Go over vertex shaders + +\section2 Fragment Shader +Go over fragment shaders +*/ diff --git a/src/quick/doc/src/concepts/effects/sprites.qdoc b/src/quick/doc/src/concepts/effects/sprites.qdoc new file mode 100644 index 0000000000..e4bd2e0c31 --- /dev/null +++ b/src/quick/doc/src/concepts/effects/sprites.qdoc @@ -0,0 +1,181 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qtquick-images-sprites +\ingroup qml-features +\page qtquick-effects-sprites.html +\title Sprite Animations +\brief Sprite-based animations with flexible transitioning + +\section1 Related Types + +\generatelist{related} + +\section1 Sprite Engine + +The QtQuick sprite engine is a stochastic state machine combined with the ability +to chop up images containing multiple frames of an animation. + +\section2 State Machine + +A primary function of the sprite engine is its internal state machine. This is not the same as +the states and transitions in Qt Quick, and is more like a conventional state machine. Sprites +can have weighted transitions to other sprites, or back to themselves. When a sprite animation +finishes, the sprite engine will choose the next sprite randomly, based on the weighted transitions +available for the sprite that just finished. + +You can affect the currently playing sprite in two ways. You can arbitrarily force it to immediately +start playing any sprite, or you can tell it to gradually transition to a given sprite. If you +instruct it to gradually transition, then it will reach the target sprite by going through valid +state transitions using the fewest number of intervening sprites (but ignoring relative weightings). +This allows you to easily insert a transitional animation between two different sprites. + +\image spriteenginegraph.png + +As an example, consider the above diagram which illustrates the sprites for a hypothetical 2D +platform game character. The character starts by displaying the standing state. From this state, +barring external input, he will transition to either the waiting animation, the walking animation, +or play the standing animation again. Because the weights for those transitions are one, zero and three +respectively, he has a one in four chance of playing the waiting animation when the standing animation +finishes, and a three in four chance of playing the standing animation again. This allows for a character +who has a slightly animated and variable behavior while waiting. + +Because there is a zero weight transition to the walking animation, the standing animation will not normally +transition there. But if you set the goal animation to be the walking animation, it would play the walking +animation when it finished the standing animation. If it was previously in the waiting animation, it would +finish playing that, then play the standing animation, then play the walking animation. It would then continue to +play the walking animation until the goal animation is unset, at which point it would switch to the standing +animation after finishing the walking animation. + +If you set the goal state then to the jumping animation, it would finish the walking animation before +playing the jumping animation. Because the jumping animation does not transition to other states, it will still +keep playing the jumping animation until the state is forced to change. In this example, you could set it back to +walking and change to goal animation to walking or to nothing (which would lead it to play the standing animation +after the walking animation). Note that by forcibly setting the animation, you can start playing the animation +immediately. + +\section2 Input Format + +The file formats accepted by the sprite engine is the same as the file formats accepted by other QML elements, +such as \l Image. In order to animate the image however, the sprite engine requires the image file to contain +all of the frames of the animation. They should be arranged in a contiguous line, which may wrap from the right +edge of the file to a lower row starting from the left edge of the file (and which is placed directly below the +previous row). + +\image spritecutting.png + +As an example, take the above image. For now just consider the black numbers, and assume the squares are 40x40 pixels. +Normally, the image is read from the top-left corner. If you specified the frame size as 40x40 pixels, and a frame count +of 8, then it would read in the frames as they are numbered. The frame in the top left would be the first frame, the frame +in the top right would be the fifth frame, and then it would wrap to the next row (at pixel location 0,40 in the file) to read +the sixth frame. It would stop reading after the frame marked 8, and if there was any image data in the square below frame four +then it would not be included in the animation. + +It is possible to load animations from an arbitrary offset, but they will still follow the same pattern. +Consider now the red numbers. If we specify that the animation begins at pixel location 120,0, with a +frame count of 5 and the same frame size as before, then it will load the frames as they are numbered in red. +The first 120x40 of the image will not be used, as it starts reading 40x40 blocks from the location of 120,0. +When it reaches the end of the file at 160,0, it then starts to read the next row from 0,40. + +The blue numbers show the frame numbers if you tried to load two frames of that size, starting from 40,40. Note +that it is possible to load multiple sprites out of the one image file. The red, blue and black numbers can all +be loaded as separate animations to the same sprite engine. The following code loads the animations as per the image. +It also specifies that animations are to played at 20 frames per second. + +\code +Sprite { + name: "black" + source: "image.png" + frameCount: 8 + frameWidth: 40 + frameHeight: 40 + frameRate: 20 +} +Sprite { + name: "red" + source: "image.png" + frameX: 120 + frameCount: 5 + frameWidth: 40 + frameHeight: 40 + frameRate: 20 +} +Sprite { + name: "blue" + source: "image.png" + frameX: 40 + frameX: 40 + frameCount: 2 + frameWidth: 40 + frameHeight: 40 + frameRate: 20 +} +\endcode + +Frames within one animation must be the same size, however multiple animations within the same file +do not. Sprites without a frameCount specified assume that they take the entire file, and you must specify +the frame size. Sprites without a frame size assume that they are square and take the entire file without wrapping, +and you must specify a frame count. + +The sprite engine internally copies and cuts up images to fit in an easier to read internal format, which leads +to some graphics memory limitations. Because it requires all the sprites for a single engine to be in the same +texture, attempting to load many different animations can run into texture memory limits on embedded devices. In +these situations, a warning will be output to the console containing the maximum texture size. + +There are several software tools to help turn images into sprite sheets, here are some examples: +Photoshop plugin: +http://www.personal.psu.edu/zez1/blogs/my_blog/2011/05/scripts-4-photoshop-file-sequence-to-layers-to-sprite-sheet.html +Gimp plugin: +http://registry.gimp.org/node/20943 +Cmd-line tool: +http://www.imagemagick.org/script/montage.php + + +\section2 QML Types Using the Sprite Engine + +Sprites for the sprite engine can be defined using the \l Sprite element. This element includes the input parameters +as well as the length of the animation and weighted transitions to other animations. It is purely a data class, and +does not render anything. + +\l SpriteSequence is an element which uses a sprite engine to draw the sprites defined in it. It is a single and +self-contained sprite engine, and does not interact with other sprite engines. \l Sprite elements can be shared between +sprite engine using elements, but this is not done automatically. So if you have defined a sprite in one \l SpriteSequence +you will need to redefine it (or reference the same \l Sprite element) in the sprites property of another \l SpriteSequence +in order to transition to that animation. + +Additionally, \l ImageParticle can use \l Sprite elements to define sprites for each particle. This is again a single +sprite engine per element. This works similarly to SpriteSequence, but it also has the parametrized variability provided +by the \l ImageParticle element. + +\section1 AnimatedSprite + +For use-cases which do not need to transition between animations, consider the \l AnimatedSprite element. +This element displays sprite animations with the same input format, but only one at a time. It also provides more fine-grained +manual control, as there is no sprite engine managing the timing and transitions behind the scenes. + +*/ diff --git a/src/quick/doc/src/concepts/effects/topic.qdoc b/src/quick/doc/src/concepts/effects/topic.qdoc new file mode 100644 index 0000000000..aa6b998c49 --- /dev/null +++ b/src/quick/doc/src/concepts/effects/topic.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + + +/*! +\page qtquick-effects-topic.html +\title Important Concepts In Qt Quick - Graphical Effects +\brief Overview of graphical effects concepts + +\section1 Graphical Effects and Particles + +Visually appealing user-interfaces are more engaging than lacklustre ones. +That said, the designer must bear in mind that visual effects simply provide +a useful way to subtlely communicate to the user (for example, which visual +item is active, or how focus is being transferred). Over-use of visual +effects can actually detract from the user-experience. + +\section1 Visual Transformation + +Visual objects can be transformed. For example, they can be scaled or rotated. +These sort of transformations can provide hints about focus or selection, and +can provide intuitive hints about what events are occurring in an application. + +For information about visual transformations to visual objects, see the +page titled \l{qtquick-effects-transformations.html} +{Qt Quick Transformation Types}. + +\section1 Shader Effects + +Shader effects allow the full, raw power of a graphics processing unit to be +utilized directly via vertex and pixel shaders. Using too many shader effects +can result in increased power usage and sometimes slow performance, but if +used sparingly and carefully, a shader can allow complex and visually appealing +effects to be applied to a visual object (for example, ripples in water). + +For information about shader programs and shader effects, see the page +titled \l{qtquick-effects-shaders.html} +{Qt Quick Shader Effects}. + +\section1 Particles + +A particle system allows explosions, fireworks, smoke, fog and wind effects to +be simulated and displayed to the user. Qt Quick provides a particle system +which allows these sort of complex, 2D simulations to be performed, including +support for environmental effects like gravity and turbulence. +Particles are most commonly used to add subtle and visually appealing effects +to currently selected items in lists or in activity notifiers, and in games. + +For information about particles, see the documentation about the +\l{qtquick-effects-particles.html}{Qt Quick Particle System}. + +\section1 Sprites + +A sprite is an animated image made up of frames. Sprites are commonly found +in games. Qt Quick provides a visual type to display sprites, as well as a +complex, stochastic, frame-transition controller for more complex applications +which use sprites extensively (such as games). + +For information about sprite animations, see the page titled +\l{qtquick-effects-sprites.html}{Sprite Animations}. + + +*/ + diff --git a/src/quick/doc/src/concepts/effects/transformations.qdoc b/src/quick/doc/src/concepts/effects/transformations.qdoc new file mode 100644 index 0000000000..d286a29797 --- /dev/null +++ b/src/quick/doc/src/concepts/effects/transformations.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\group qtquick-transformations +\page qtquick-effects-transformations.html +\title Qt Quick Transformation Types +\brief Types for applying transformations to visual types + +\section1 Related Types +\generatelist{related} +*/ |