Document recursion limitations of the graphical effects.
[qt:qtgraphicaleffects.git] / src / effects / MaskedBlur.qml
1 /****************************************************************************
2 **
3 ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the Qt Graphical Effects module.
7 **
8 ** $QT_BEGIN_LICENSE:BSD$
9 ** You may use this file under the terms of the BSD license as follows:
10 **
11 ** "Redistribution and use in source and binary forms, with or without
12 ** modification, are permitted provided that the following conditions are
13 ** met:
14 **   * Redistributions of source code must retain the above copyright
15 **     notice, this list of conditions and the following disclaimer.
16 **   * Redistributions in binary form must reproduce the above copyright
17 **     notice, this list of conditions and the following disclaimer in
18 **     the documentation and/or other materials provided with the
19 **     distribution.
20 **   * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names
21 **     of its contributors may be used to endorse or promote products derived
22 **     from this software without specific prior written permission.
23 **
24 **
25 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27 ** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28 ** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29 ** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
30 ** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
31 ** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 ** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 ** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 ** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
35 ** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
36 **
37 ** $QT_END_LICENSE$
38 **
39 ****************************************************************************/
40
41 import QtQuick 2.0
42 import "private"
43
44 /*!
45     \qmltype MaskedBlur
46     \inqmlmodule QtGraphicalEffects 1.0
47     \since QtGraphicalEffects 1.0
48     \inherits QtQuick2::Item
49     \ingroup qtgraphicaleffects-blur
50     \brief Applies a blur effect with a varying intesity.
51
52     MaskedBlur effect softens the image by blurring it. The intensity of the
53     blur can be controlled for each pixel using maskSource so that some parts of
54     the source are blurred more than others. By default the effect produces a
55     high quality result, thus the rendering speed may not be the highest
56     possible. The rendering speed is reduced especially if the
57     \l{MaskedBlur::samples}{samples} is large. For use cases that require faster
58     rendering speed and the highest possible visual quality is not necessary,
59     property \l{MaskedBlur::fast}{fast} can be set to true.
60
61     \table
62     \header
63         \li Source
64         \li MaskSource
65         \li Effect applied
66     \row
67         \li \image Original_bug.png
68         \li \image MaskedBlur_mask.png
69         \li \image MaskedBlur_bug.png
70     \endtable
71
72     \section1 Example
73
74     The following example shows how to apply the effect.
75     \snippet MaskedBlur-example.qml example
76
77 */
78 Item {
79     id: rootItem
80
81     /*!
82         This property defines the source item that is going to be blurred.
83
84         \note It is not supported to let the effect include itself, for
85         instance by setting source to the effect's parent.
86     */
87     property variant source
88
89     /*!
90         This property defines the item that is controlling the final intensity
91         of the blur. The pixel alpha channel value from maskSource defines the
92         actual blur radius that is going to be used for blurring the
93         corresponding source pixel.
94
95         Opaque maskSource pixels produce blur with specified
96         \l{MaskedBlur::radius}{radius}, while transparent pixels suppress the
97         blur completely. Semitransparent maskSource pixels produce blur with a
98         radius that is interpolated according to the pixel transparency level.
99     */
100     property variant maskSource
101
102     /*!
103         This property defines the distance of the neighboring pixels which
104         affect the blurring of an individual pixel. A larger radius increases
105         the blur effect.
106
107         Depending on the radius value, value of the
108         \l{MaskedBlur::samples}{samples} should be set to sufficiently large to
109         ensure the visual quality.
110
111         The value ranges from 0.0 (no blur) to inf. By default, the property is
112         set to \c 0.0 (no blur).
113
114         \table
115         \header
116         \li Output examples with different radius values
117         \li
118         \li
119         \row
120             \li \image MaskedBlur_radius1.png
121             \li \image MaskedBlur_radius2.png
122             \li \image MaskedBlur_radius3.png
123         \row
124             \li \b { radius: 0 }
125             \li \b { radius: 8 }
126             \li \b { radius: 16 }
127         \row
128             \li \l samples: 24
129             \li \l samples: 24
130             \li \l samples: 24
131         \row
132             \li \l transparentBorder: false
133             \li \l transparentBorder: false
134             \li \l transparentBorder: false
135         \row
136             \li \l fast: false
137             \li \l fast: false
138             \li \l fast: false
139         \endtable
140
141     */
142     property real radius: 0.0
143
144     /*!
145         This property defines how many samples are taken per pixel when blur
146         calculation is done. Larger value produces better quality, but is slower
147         to render.
148
149         Ideally, this value should be twice as large as the highest required
150         radius value, for example, if the radius is animated between 0.0 and
151         4.0, samples should be set to 8.
152
153         The value ranges from 0 to 32. By default, the property is set to \c 0.
154
155         This property is not intended to be animated. Changing this property may
156         cause the underlying OpenGL shaders to be recompiled.
157
158         When \l{MaskedBlur::fast}{fast} property is set to true, this property
159         has no effect.
160     */
161     property int samples: 0
162
163     /*!
164         This property allows the effect output pixels to be cached in order to
165         improve the rendering performance. Every time the source or effect
166         properties are changed, the pixels in the cache must be updated. Memory
167         consumption is increased, because an extra buffer of memory is required
168         for storing the effect output.
169
170         It is recommended to disable the cache when the source or the effect
171         properties are animated.
172
173         By default, the property is set to \c false.
174
175     */
176     property bool cached: false
177
178     /*!
179         This property selects the blurring algorithm that is used to produce the
180         blur. Setting this to true enables fast algorithm, setting value to
181         false produces higher quality result.
182
183         By default, the property is set to \c false.
184
185         \table
186         \header
187         \li Output examples with different fast values
188         \li
189         \li
190         \row
191             \li \image MaskedBlur_fast1.png
192             \li \image MaskedBlur_fast2.png
193         \row
194             \li \b { fast: false }
195             \li \b { fast: true }
196         \row
197             \li \l radius: 16
198             \li \l radius: 16
199         \row
200             \li \l samples: 24
201             \li \l samples: 24
202         \row
203             \li \l transparentBorder: false
204             \li \l transparentBorder: false
205         \endtable
206
207     */
208     property bool fast: false
209
210     /*!
211         This property defines the blur behavior near the edges of the item,
212         where the pixel blurring is affected by the pixels outside the source
213         edges.
214
215         If the property is set to \c true, the pixels outside the source are
216         interpreted to be transparent, which is similar to OpenGL
217         clamp-to-border extension. The blur is expanded slightly outside the
218         effect item area.
219
220         If the property is set to \c false, the pixels outside the source are
221         interpreted to contain the same color as the pixels at the edge of the
222         item, which is similar to OpenGL clamp-to-edge behavior. The blur does
223         not expand outside the effect item area.
224
225         By default, the property is set to \c false.
226
227         \table
228         \header
229         \li Output examples with different transparentBorder values
230         \li
231         \li
232         \row
233             \li \image MaskedBlur_transparentBorder1.png
234             \li \image MaskedBlur_transparentBorder2.png
235         \row
236             \li \b { transparentBorder: false }
237             \li \b { transparentBorder: true }
238         \row
239             \li \l radius: 64
240             \li \l radius: 64
241         \row
242             \li \l samples: 24
243             \li \l samples: 24
244         \row
245             \li \l fast: true
246             \li \l fast: true
247         \endtable
248
249     */
250     property bool transparentBorder: false
251
252     Loader {
253         id: loaderItem
254         anchors.fill: parent
255         sourceComponent: rootItem.fast ? fastBlur : gaussianBlur
256     }
257
258     Component {
259         id: gaussianBlur
260         GaussianMaskedBlur {
261             anchors.fill: parent
262             source: rootItem.source
263             maskSource: rootItem.maskSource
264             radius: rootItem.radius
265             maximumRadius: rootItem.samples * 0.5
266             transparentBorder: rootItem.transparentBorder
267             cached: rootItem.cached
268         }
269     }
270
271     Component {
272         id: fastBlur
273         FastMaskedBlur {
274             anchors.fill: parent
275             source:rootItem. source
276             maskSource: rootItem.maskSource
277             blur: Math.pow(rootItem.radius / 64.0, 0.4)
278             transparentBorder: rootItem.transparentBorder
279             cached: rootItem.cached
280         }
281     }
282 }