1/****************************************************************************
2**
3** Copyright (C) 2017 The Qt Company Ltd.
4** Copyright (C) 2017 Jolla Ltd, author: <gunnar.sletta@jollamobile.com>
5** Contact: https://www.qt.io/licensing/
6**
7** This file is part of the Qt Graphical Effects module.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial License Usage
11** Licensees holding valid commercial Qt licenses may use this file in
12** accordance with the commercial license agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and The Qt Company. For licensing terms
15** and conditions see https://www.qt.io/terms-conditions. For further
16** information use the contact form at https://www.qt.io/contact-us.
17**
18** GNU Lesser General Public License Usage
19** Alternatively, this file may be used under the terms of the GNU Lesser
20** General Public License version 3 as published by the Free Software
21** Foundation and appearing in the file LICENSE.LGPL3 included in the
22** packaging of this file. Please review the following information to
23** ensure the GNU Lesser General Public License version 3 requirements
24** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
25**
26** GNU General Public License Usage
27** Alternatively, this file may be used under the terms of the GNU
28** General Public License version 2.0 or (at your option) the GNU General
29** Public license version 3 or any later version approved by the KDE Free
30** Qt Foundation. The licenses are as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
32** included in the packaging of this file. Please review the following
33** information to ensure the GNU General Public License requirements will
34** be met: https://www.gnu.org/licenses/gpl-2.0.html and
35** https://www.gnu.org/licenses/gpl-3.0.html.
36**
37** $QT_END_LICENSE$
38**
39****************************************************************************/
40
41import QtQuick 2.12
42import QtGraphicalEffects.private 1.12
43
44/*!
45    \qmltype DropShadow
46    \inqmlmodule QtGraphicalEffects
47    \since QtGraphicalEffects 1.0
48    \inherits QtQuick2::Item
49    \ingroup qtgraphicaleffects-drop-shadow
50
51    \brief Generates a soft shadow behind the source item.
52
53    The DropShadow effect blurs the alpha channel of the input, colorizes the
54    result and places it behind the source object to create a soft shadow. The
55    shadow's color can be changed using the \l {DropShadow::color}{color}
56    property. The location of the shadow can be changed with the \l
57    horizontalOffset and \l verticalOffset properties.
58
59    \table
60    \header
61        \li Source
62        \li Effect applied
63    \row
64        \li \image Original_butterfly.png
65        \li \image DropShadow_butterfly.png
66    \endtable
67
68    The soft shadow is created by blurring the image live using a gaussian
69    blur. Performing blur live is a costly operation. Fullscreen gaussian blur
70    with even a moderate number of samples will only run at 60 fps on highend
71    graphics hardware.
72
73    When the source is static, the \l cached property can be set to allocate
74    another buffer to avoid performing the blur every time it is drawn.
75
76    \note This effect is available when running with OpenGL.
77
78    \section1 Example
79
80    The following example shows how to apply the effect.
81    \snippet DropShadow-example.qml example
82
83*/
84Item {
85    id: root
86
87    DropShadowBase {
88        id: dbs
89        anchors.fill: parent
90    }
91
92    /*!
93        This property defines the source item that is going to be used as the
94        source for the generated shadow.
95
96        \note It is not supported to let the effect include itself, for
97        instance by setting source to the effect's parent.
98    */
99    property alias source: dbs.source
100
101    /*!
102        \qmlproperty int DropShadow::radius
103
104        Radius defines the softness of the shadow. A larger radius causes the
105        edges of the shadow to appear more blurry.
106
107        The ideal blur is achieved by selecting \c samples and \c radius such
108        that \c {samples = 1 + radius * 2}, such as:
109
110        \table
111        \header \li Radius             \li Samples
112        \row    \li 0 \e{(no blur)}    \li 1
113        \row    \li 1                  \li 3
114        \row    \li 2                  \li 5
115        \row    \li 3                  \li 7
116        \endtable
117
118        By default, the property is set to \c {floor(samples/2)}.
119
120        \table
121        \header
122        \li Output examples with different radius values
123        \li
124        \li
125        \row
126            \li \image DropShadow_radius1.png
127            \li \image DropShadow_radius2.png
128            \li \image DropShadow_radius3.png
129        \row
130            \li \b { radius: 0 }
131            \li \b { radius: 6 }
132            \li \b { radius: 12 }
133        \row
134            \li \l samples: 25
135            \li \l samples: 25
136            \li \l samples: 25
137        \row
138            \li \l color: #000000
139            \li \l color: #000000
140            \li \l color: #000000
141        \row
142            \li \l horizontalOffset: 0
143            \li \l horizontalOffset: 0
144            \li \l horizontalOffset: 0
145        \row
146            \li \l verticalOffset: 20
147            \li \l verticalOffset: 20
148            \li \l verticalOffset: 20
149        \row
150            \li \l spread: 0
151            \li \l spread: 0
152            \li \l spread: 0
153        \endtable
154    */
155    property alias radius: dbs.radius;
156
157    /*!
158        This property defines how many samples are taken per pixel when edge
159        softening blur calculation is done. Larger value produces better
160        quality, but is slower to render.
161
162        Ideally, this value should be twice as large as the highest required
163        radius value plus one, such as:
164
165        \table
166        \header \li Radius             \li Samples
167        \row    \li 0 \e{(no blur)}    \li 1
168        \row    \li 1                  \li 3
169        \row    \li 2                  \li 5
170        \row    \li 3                  \li 7
171        \endtable
172
173        By default, the property is set to \c 9.
174
175        This property is not intended to be animated. Changing this property will
176        cause the underlying OpenGL shaders to be recompiled.
177    */
178    property alias samples: dbs.samples
179
180    /*!
181        This property defines the RGBA color value which is used for the shadow.
182
183        By default, the property is set to \c "black".
184
185        \table
186        \header
187        \li Output examples with different color values
188        \li
189        \li
190        \row
191            \li \image DropShadow_color1.png
192            \li \image DropShadow_color2.png
193            \li \image DropShadow_color3.png
194        \row
195            \li \b { color: #000000 }
196            \li \b { color: #0000ff }
197            \li \b { color: #aa000000 }
198        \row
199            \li \l radius: 8
200            \li \l radius: 8
201            \li \l radius: 8
202        \row
203            \li \l samples: 17
204            \li \l samples: 17
205            \li \l samples: 17
206        \row
207            \li \l horizontalOffset: 0
208            \li \l horizontalOffset: 0
209            \li \l horizontalOffset: 0
210        \row
211            \li \l verticalOffset: 20
212            \li \l verticalOffset: 20
213            \li \l verticalOffset: 20
214        \row
215            \li \l spread: 0
216            \li \l spread: 0
217            \li \l spread: 0
218        \endtable
219    */
220    property alias color: dbs.color
221
222    /*!
223        \qmlproperty real QtGraphicalEffects::DropShadow::horizontalOffset
224        \qmlproperty real QtGraphicalEffects::DropShadow::verticalOffset
225
226        HorizontalOffset and verticalOffset properties define the offset for the
227        rendered shadow compared to the DropShadow item position. Often, the
228        DropShadow item is anchored so that it fills the source element. In this
229        case, if the HorizontalOffset and verticalOffset properties are set to
230        0, the shadow is rendered exactly under the source item. By changing the
231        offset properties, the shadow can be positioned relatively to the source
232        item.
233
234        The values range from -inf to inf. By default, the properties are set to
235        \c 0.
236
237        \table
238        \header
239        \li Output examples with different horizontalOffset values
240        \li
241        \li
242        \row
243            \li \image DropShadow_horizontalOffset1.png
244            \li \image DropShadow_horizontalOffset2.png
245            \li \image DropShadow_horizontalOffset3.png
246        \row
247            \li \b { horizontalOffset: -20 }
248            \li \b { horizontalOffset: 0 }
249            \li \b { horizontalOffset: 20 }
250        \row
251            \li \l radius: 4
252            \li \l radius: 4
253            \li \l radius: 4
254        \row
255            \li \l samples: 9
256            \li \l samples: 9
257            \li \l samples: 9
258        \row
259            \li \l color: #000000
260            \li \l color: #000000
261            \li \l color: #000000
262        \row
263            \li \l verticalOffset: 0
264            \li \l verticalOffset: 0
265            \li \l verticalOffset: 0
266        \row
267            \li \l spread: 0
268            \li \l spread: 0
269            \li \l spread: 0
270        \endtable
271    */
272    property alias horizontalOffset: dbs.horizontalOffset
273    property alias verticalOffset: dbs.verticalOffset
274
275    /*!
276        This property defines how large part of the shadow color is strengthened
277        near the source edges.
278
279        The value ranges from 0.0 to 1.0. By default, the property is set to \c
280        0.0.
281
282        \table
283        \header
284        \li Output examples with different spread values
285        \li
286        \li
287        \row
288            \li \image DropShadow_spread1.png
289            \li \image DropShadow_spread2.png
290            \li \image DropShadow_spread3.png
291        \row
292            \li \b { spread: 0.0 }
293            \li \b { spread: 0.5 }
294            \li \b { spread: 1.0 }
295        \row
296            \li \l radius: 8
297            \li \l radius: 8
298            \li \l radius: 8
299        \row
300            \li \l samples: 17
301            \li \l samples: 17
302            \li \l samples: 17
303        \row
304            \li \l color: #000000
305            \li \l color: #000000
306            \li \l color: #000000
307        \row
308            \li \l horizontalOffset: 0
309            \li \l horizontalOffset: 0
310            \li \l horizontalOffset: 0
311        \row
312            \li \l verticalOffset: 20
313            \li \l verticalOffset: 20
314            \li \l verticalOffset: 20
315        \endtable
316    */
317    property alias spread: dbs.spread
318
319    /*!
320        \internal
321
322        Starting Qt 5.6, this property has no effect. It is left here
323        for source compatibility only.
324
325        ### Qt 6: remove
326    */
327    property bool fast: false
328
329    /*!
330        This property allows the effect output pixels to be cached in order to
331        improve the rendering performance. Every time the source or effect
332        properties are changed, the pixels in the cache must be updated. Memory
333        consumption is increased, because an extra buffer of memory is required
334        for storing the effect output.
335
336        It is recommended to disable the cache when the source or the effect
337        properties are animated.
338
339        By default, the property is set to \c false.
340    */
341    property alias cached: dbs.cached
342
343    /*!
344        This property determines whether or not the effect has a transparent
345        border.
346
347        When set to \c true, the exterior of the item is padded with a 1 pixel
348        wide transparent edge, making sampling outside the source texture use
349        transparency instead of the edge pixels. Without this property, an
350        image which has opaque edges will not get a blurred shadow.
351
352        In the image below, the Rectangle on the left has transparent borders
353        and has blurred edges, whereas the Rectangle on the right does not:
354
355        By default, this property is set to \c true.
356
357        \snippet DropShadow-transparentBorder-example.qml example
358
359        \image DropShadow-transparentBorder.png
360    */
361    property alias transparentBorder: dbs.transparentBorder
362}
363