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