src/quick/doc/src/concepts/effects/sprites.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \group qtquick-images-sprites
  30 \ingroup qml-features
  31 \page qtquick-effects-sprites.html
  32 \title Sprite Animations
  33 \brief Sprite-based animations with flexible transitioning
  34
  35 \section1 Related Types
  36
  37 \generatelist{related}
  38
  39 \section1 Sprite Engine
  40
  41 The QtQuick sprite engine is a stochastic state machine combined with the ability
  42 to chop up images containing multiple frames of an animation.
  43
  44 \section2 State Machine
  45
  46 A primary function of the sprite engine is its internal state machine. This is not the same as
  47 the states and transitions in Qt Quick, and is more like a conventional state machine. Sprites
  48 can have weighted transitions to other sprites, or back to themselves. When a sprite animation
  49 finishes, the sprite engine will choose the next sprite randomly, based on the weighted transitions
  50 available for the sprite that just finished.
  51
  52 You can affect the currently playing sprite in two ways. You can arbitrarily force it to immediately
  53 start playing any sprite, or you can tell it to gradually transition to a given sprite. If you
  54 instruct it to gradually transition, then it will reach the target sprite by going through valid
  55 state transitions using the fewest number of intervening sprites (but ignoring relative weightings).
  56 This allows you to easily insert a transitional animation between two different sprites.
  57
  58 \image spriteenginegraph.png
  59
  60 As an example, consider the above diagram which illustrates the sprites for a hypothetical 2D
  61 platform game character. The character starts by displaying the standing state. From this state,
  62 barring external input, he will transition to either the waiting animation, the walking animation,
  63 or play the standing animation again. Because the weights for those transitions are one, zero and three
  64 respectively, he has a one in four chance of playing the waiting animation when the standing animation
  65 finishes, and a three in four chance of playing the standing animation again. This allows for a character
  66 who has a slightly animated and variable behavior while waiting.
  67
  68 Because there is a zero weight transition to the walking animation, the standing animation will not normally
  69 transition there. But if you set the goal animation to be the walking animation, it would play the walking
  70 animation when it finished the standing animation. If it was previously in the waiting animation, it would
  71 finish playing that, then play the standing animation, then play the walking animation. It would then continue to
  72 play the walking animation until the goal animation is unset, at which point it would switch to the standing
  73 animation after finishing the walking animation.
  74
  75 If you set the goal state then to the jumping animation, it would finish the walking animation before
  76 playing the jumping animation. Because the jumping animation does not transition to other states, it will still
  77 keep playing the jumping animation until the state is forced to change. In this example, you could set it back to
  78 walking and change to goal animation to walking or to nothing (which would lead it to play the standing animation
  79 after the walking animation). Note that by forcibly setting the animation, you can start playing the animation
  80 immediately.
  81
  82 \section2 Input Format
  83
  84 The file formats accepted by the sprite engine is the same as the file formats accepted by other QML elements,
  85 such as \l Image. In order to animate the image however, the sprite engine requires the image file to contain
  86 all of the frames of the animation. They should be arranged in a contiguous line, which may wrap from the right
  87 edge of the file to a lower row starting from the left edge of the file (and which is placed directly below the
  88 previous row).
  89
  90 \image spritecutting.png
  91
  92 As an example, take the above image. For now just consider the black numbers, and assume the squares are 40x40 pixels.
  93 Normally, the image is read from the top-left corner. If you specified the frame size as 40x40 pixels, and a frame count
  94 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
  95 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
  96 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
  97 then it would not be included in the animation.
  98
  99 It is possible to load animations from an arbitrary offset, but they will still follow the same pattern.
 100 Consider now the red numbers. If we specify that the animation begins at pixel location 120,0, with a
 101 frame count of 5 and the same frame size as before, then it will load the frames as they are numbered in red.
 102 The first 120x40 of the image will not be used, as it starts reading 40x40 blocks from the location of 120,0.
 103 When it reaches the end of the file at 160,0, it then starts to read the next row from 0,40.
 104
 105 The blue numbers show the frame numbers if you tried to load two frames of that size, starting from 40,40. Note
 106 that it is possible to load multiple sprites out of the one image file. The red, blue and black numbers can all
 107 be loaded as separate animations to the same sprite engine. The following code loads the animations as per the image.
 108 It also specifies that animations are to played at 20 frames per second.
 109
 110 \code
 111 Sprite {
 112     name: "black"
 113     source: "image.png"
 114     frameCount: 8
 115     frameWidth: 40
 116     frameHeight: 40
 117     frameRate: 20
 118 }
 119 Sprite {
 120     name: "red"
 121     source: "image.png"
 122     frameX: 120
 123     frameCount: 5
 124     frameWidth: 40
 125     frameHeight: 40
 126     frameRate: 20
 127 }
 128 Sprite {
 129     name: "blue"
 130     source: "image.png"
 131     frameX: 40
 132     frameX: 40
 133     frameCount: 2
 134     frameWidth: 40
 135     frameHeight: 40
 136     frameRate: 20
 137 }
 138 \endcode
 139
 140 Frames within one animation must be the same size, however multiple animations within the same file
 141 do not. Sprites without a frameCount specified assume that they take the entire file, and you must specify
 142 the frame size. Sprites without a frame size assume that they are square and take the entire file without wrapping,
 143 and you must specify a frame count.
 144
 145 The sprite engine internally copies and cuts up images to fit in an easier to read internal format, which leads
 146 to some graphics memory limitations. Because it requires all the sprites for a single engine to be in the same
 147 texture, attempting to load many different animations can run into texture memory limits on embedded devices. In
 148 these situations, a warning will be output to the console containing the maximum texture size.
 149
 150 There are several software tools to help turn images into sprite sheets, here are some examples:
 151 Photoshop plugin:
 152 http://www.personal.psu.edu/zez1/blogs/my_blog/2011/05/scripts-4-photoshop-file-sequence-to-layers-to-sprite-sheet.html
 153 Gimp plugin:
 154 http://registry.gimp.org/node/20943
 155 Cmd-line tool:
 156 http://www.imagemagick.org/script/montage.php
 157
 158
 159 \section2 QML Types Using the Sprite Engine
 160
 161 Sprites for the sprite engine can be defined using the \l Sprite element. This element includes the input parameters
 162 as well as the length of the animation and weighted transitions to other animations. It is purely a data class, and
 163 does not render anything.
 164
 165 \l SpriteSequence is an element which uses a sprite engine to draw the sprites defined in it. It is a single and
 166 self-contained sprite engine, and does not interact with other sprite engines. \l Sprite elements can be shared between
 167 sprite engine using elements, but this is not done automatically. So if you have defined a sprite in one \l SpriteSequence
 168 you will need to redefine it (or reference the same \l Sprite element) in the sprites property of another \l SpriteSequence
 169 in order to transition to that animation.
 170
 171 Additionally, \l ImageParticle can use \l Sprite elements to define sprites for each particle. This is again a single
 172 sprite engine per element. This works similarly to SpriteSequence, but it also has the parametrized variability provided
 173 by the \l ImageParticle element.
 174
 175 \section1 AnimatedSprite
 176
 177 For use-cases which do not need to transition between animations, consider the \l AnimatedSprite element.
 178 This element displays sprite animations with the same input format, but only one at a time. It also provides more fine-grained
 179 manual control, as there is no sprite engine managing the timing and transitions behind the scenes.
 180
 181 */