Document recursion limitations of the graphical effects.
[qt:qtgraphicaleffects.git] / src / effects / InnerShadow.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 InnerShadow
46     \inqmlmodule QtGraphicalEffects 1.0
47     \since QtGraphicalEffects 1.0
48     \inherits QtQuick2::Item
49     \ingroup qtgraphicaleffects-drop-shadow
50     \brief Generates a colorized and blurred shadow inside the
51     source.
52
53     By default the effect produces a high quality shadow image, thus the
54     rendering speed of the shadow might not be the highest possible. The
55     rendering speed is reduced especially if the shadow edges are heavily
56     softened. For use cases that require faster rendering speed and for which
57     the highest possible visual quality is not necessary, property
58     \l{InnerShadow::fast}{fast} can be set to true.
59
60     \table
61     \header
62         \li Source
63         \li Effect applied
64     \row
65         \li \image Original_butterfly.png
66         \li \image InnerShadow_butterfly.png
67     \endtable
68
69     \section1 Example
70
71     The following example shows how to apply the effect.
72     \snippet InnerShadow-example.qml example
73
74 */
75 Item {
76     id: rootItem
77
78     /*!
79         This property defines the source item that is going to be used as the
80         source for the generated shadow.
81
82         \note It is not supported to let the effect include itself, for
83         instance by setting source to the effect's parent.
84     */
85     property variant source
86
87     /*!
88         Radius defines the softness of the shadow. A larger radius causes the
89         edges of the shadow to appear more blurry.
90
91         Depending on the radius value, value of the
92         \l{InnerShadow::samples}{samples} should be set to sufficiently large to
93         ensure the visual quality.
94
95         The value ranges from 0.0 (no blur) to inf. By default, the property is
96         set to \c 0.0 (no blur).
97
98         \table
99         \header
100         \li Output examples with different radius values
101         \li
102         \li
103         \row
104             \li \image InnerShadow_radius1.png
105             \li \image InnerShadow_radius2.png
106             \li \image InnerShadow_radius3.png
107         \row
108             \li \b { radius: 0 }
109             \li \b { radius: 6 }
110             \li \b { radius: 12 }
111         \row
112             \li \l samples: 24
113             \li \l samples: 24
114             \li \l samples: 24
115         \row
116             \li \l color: #000000
117             \li \l color: #000000
118             \li \l color: #000000
119         \row
120             \li \l horizontalOffset: 0
121             \li \l horizontalOffset: 0
122             \li \l horizontalOffset: 0
123         \row
124             \li \l verticalOffset: 0
125             \li \l verticalOffset: 0
126             \li \l verticalOffset: 0
127         \row
128             \li \l spread: 0
129             \li \l spread: 0
130             \li \l spread: 0
131         \endtable
132
133     */
134     property real radius: 0.0
135
136     /*!
137         This property defines how many samples are taken per pixel when edge
138         softening blur calculation is done. Larger value produces better
139         quality, but is slower to render.
140
141         Ideally, this value should be twice as large as the highest required
142         radius value, for example, if the radius is animated between 0.0 and
143         4.0, samples should be set to 8.
144
145         The value ranges from 0 to 32. By default, the property is set to \c 0.
146
147         This property is not intended to be animated. Changing this property may
148         cause the underlying OpenGL shaders to be recompiled.
149
150         When \l{InnerShadow::fast}{fast} property is set to true, this property
151         has no effect.
152
153     */
154     property int samples: 0
155
156     /*!
157         This property defines how large part of the shadow color is strenghtened
158         near the source edges.
159
160         The value ranges from 0.0 to 1.0. By default, the property is set to \c
161         0.5.
162
163         \table
164         \header
165         \li Output examples with different spread values
166         \li
167         \li
168         \row
169             \li \image InnerShadow_spread1.png
170             \li \image InnerShadow_spread2.png
171             \li \image InnerShadow_spread3.png
172         \row
173             \li \b { spread: 0.0 }
174             \li \b { spread: 0.3 }
175             \li \b { spread: 0.5 }
176         \row
177             \li \l radius: 16
178             \li \l radius: 16
179             \li \l radius: 16
180         \row
181             \li \l samples: 24
182             \li \l samples: 24
183             \li \l samples: 24
184         \row
185             \li \l color: #000000
186             \li \l color: #000000
187             \li \l color: #000000
188         \row
189             \li \l horizontalOffset: 0
190             \li \l horizontalOffset: 0
191             \li \l horizontalOffset: 0
192         \row
193             \li \l verticalOffset: 0
194             \li \l verticalOffset: 0
195             \li \l verticalOffset: 0
196         \endtable
197
198     */
199     property real spread: 0.0
200
201     /*!
202         This property defines the RGBA color value which is used for the shadow.
203
204         By default, the property is set to \c "black".
205
206         \table
207         \header
208         \li Output examples with different color values
209         \li
210         \li
211         \row
212             \li \image InnerShadow_color1.png
213             \li \image InnerShadow_color2.png
214             \li \image InnerShadow_color3.png
215         \row
216             \li \b { color: #000000 }
217             \li \b { color: #ffffff }
218             \li \b { color: #ff0000 }
219         \row
220             \li \l radius: 16
221             \li \l radius: 16
222             \li \l radius: 16
223         \row
224             \li \l samples: 24
225             \li \l samples: 24
226             \li \l samples: 24
227         \row
228             \li \l horizontalOffset: 0
229             \li \l horizontalOffset: 0
230             \li \l horizontalOffset: 0
231         \row
232             \li \l verticalOffset: 0
233             \li \l verticalOffset: 0
234             \li \l verticalOffset: 0
235         \row
236             \li \l spread: 0.2
237             \li \l spread: 0.2
238             \li \l spread: 0.2
239         \endtable
240     */
241     property color color: "black"
242
243     /*!
244         \qmlproperty real QtGraphicalEffects1::InnerShadow::horizontalOffset
245         \qmlproperty real QtGraphicalEffects1::InnerShadow::verticalOffset
246
247         HorizontalOffset and verticalOffset properties define the offset for the
248         rendered shadow compared to the InnerShadow item position. Often, the
249         InnerShadow item is anchored so that it fills the source element. In
250         this case, if the HorizontalOffset and verticalOffset properties are set
251         to 0, the shadow is rendered fully inside the source item. By changing
252         the offset properties, the shadow can be positioned relatively to the
253         source item.
254
255         The values range from -inf to inf. By default, the properties are set to
256         \c 0.
257
258         \table
259         \header
260         \li Output examples with different horizontalOffset values
261         \li
262         \li
263         \row
264             \li \image InnerShadow_horizontalOffset1.png
265             \li \image InnerShadow_horizontalOffset2.png
266             \li \image InnerShadow_horizontalOffset3.png
267         \row
268             \li \b { horizontalOffset: -20 }
269             \li \b { horizontalOffset: 0 }
270             \li \b { horizontalOffset: 20 }
271         \row
272             \li \l radius: 16
273             \li \l radius: 16
274             \li \l radius: 16
275         \row
276             \li \l samples: 24
277             \li \l samples: 24
278             \li \l samples: 24
279         \row
280             \li \l color: #000000
281             \li \l color: #000000
282             \li \l color: #000000
283         \row
284             \li \l verticalOffset: 0
285             \li \l verticalOffset: 0
286             \li \l verticalOffset: 0
287         \row
288             \li \l spread: 0
289             \li \l spread: 0
290             \li \l spread: 0
291         \endtable
292
293     */
294     property real horizontalOffset: 0
295     property real verticalOffset: 0
296
297     /*!
298         This property selects the blurring algorithm that is used to produce the
299         softness for the effect. Setting this to true enables fast algorithm,
300         setting value to false produces higher quality result.
301
302         By default, the property is set to \c false.
303
304         \table
305         \header
306         \li Output examples with different fast values
307         \li
308         \li
309         \row
310             \li \image InnerShadow_fast1.png
311             \li \image InnerShadow_fast2.png
312         \row
313             \li \b { fast: false }
314             \li \b { fast: true }
315         \row
316             \li \l radius: 16
317             \li \l radius: 16
318         \row
319             \li \l samples: 24
320             \li \l samples: 24
321         \row
322             \li \l color: #000000
323             \li \l color: #000000
324         \row
325             \li \l horizontalOffset: 0
326             \li \l horizontalOffset: 0
327         \row
328             \li \l verticalOffset: 0
329             \li \l verticalOffset: 0
330         \row
331             \li \l spread: 0.2
332             \li \l spread: 0.2
333         \endtable
334     */
335     property bool fast: false
336
337     /*!
338         This property allows the effect output pixels to be cached in order to
339         improve the rendering performance. Every time the source or effect
340         properties are changed, the pixels in the cache must be updated. Memory
341         consumption is increased, because an extra buffer of memory is required
342         for storing the effect output.
343
344         It is recommended to disable the cache when the source or the effect
345         properties are animated.
346
347         By default, the property is set to \c false.
348
349     */
350     property bool cached: false
351
352     Loader {
353         anchors.fill: parent
354         sourceComponent: rootItem.fast ? innerShadow : gaussianInnerShadow
355     }
356
357     Component {
358         id: gaussianInnerShadow
359         GaussianInnerShadow {
360             anchors.fill: parent
361             source: rootItem.source
362             radius: rootItem.radius
363             maximumRadius: rootItem.samples * 0.5
364             color: rootItem.color
365             cached: rootItem.cached
366             spread: rootItem.spread
367             horizontalOffset: rootItem.horizontalOffset
368             verticalOffset: rootItem.verticalOffset
369         }
370     }
371
372     Component {
373         id: innerShadow
374         FastInnerShadow {
375             anchors.fill: parent
376             source: rootItem.source
377             blur: Math.pow(rootItem.radius / 64.0, 0.4)
378             color: rootItem.color
379             cached: rootItem.cached
380             spread: rootItem.spread
381             horizontalOffset: rootItem.horizontalOffset
382             verticalOffset: rootItem.verticalOffset
383         }
384     }
385 }