1/**************************************************************************** 2** 3** Copyright (C) 2021 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the Qt Design Studio documentation. 7** 8** Commercial License Usage 9** Licensees holding valid commercial Qt licenses may use this file in 10** accordance with the commercial license agreement provided with the 11** Software or, alternatively, in accordance with the terms contained in 12** a written agreement between you and The Qt Company. For licensing terms 13** and conditions see https://www.qt.io/terms-conditions. For further 14** information use the contact form at https://www.qt.io/contact-us. 15** 16** GNU Free Documentation License Usage 17** Alternatively, this file may be used under the terms of the GNU Free 18** Documentation License version 1.3 as published by the Free Software 19** Foundation and appearing in the file included in the packaging of 20** this file. Please review the following information to ensure 21** the GNU Free Documentation License version 1.3 requirements 22** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 23** 24****************************************************************************/ 25 26/*! 27 \page quick-2d-effects.html 28 \previouspage quick-data-models.html 29 \nextpage quick-logic-helpers.html 30 31 \title 2D Effects 32 33 \QDS provides a set of effects that you can apply to components by 34 dragging-and-dropping them from \l Library > \uicontrol Components 35 > \uicontrol {Qt Quick Studio Effects} to the component in \l Navigator. 36 37 \image studio-2d-effects.png "Effects tab in Library" 38 39 \note The availability of effects depends on whether you selected 40 \uicontrol {Qt 5} or \uicontrol {Qt 6} when \l{Creating Projects} 41 {creating your project}. 42 43 Effects have one or more source properties for specifying the visual input 44 for which the effect is applied to a component. The altered visual output is 45 then presented in the effect component itself. The source can be another, 46 often hidden, component in the scene. More complex effects can have multiple 47 sources. The source component can be any component, even video or another 48 effect. Pipelining multiple effects together is a simple way to create 49 even more impressive output. 50 51 Each effect has a set of properties that can be used to configure the effect 52 output. They can be animated just like any other properties. The 53 component documentation contains property descriptions and basic usage 54 examples. 55 56 In addition to the effects described in this topic, you can set linear, 57 radial, and conical gradients. For more information, see 58 \l{Picking Gradients}. 59 60 \section1 Caching and Borders 61 62 Specify common properties for 2D effects in the \uicontrol Caching or 63 \uicontrol {Caching and Border} section. 64 65 \image studio-2d-effects-caching-and-border.png "Studio Effects Caching and Border properties" 66 67 The \uicontrol Cached property allows the effect output pixels to be cached 68 in order to improve the rendering performance. Every time the source or 69 effect properties are changed, the pixels in the cache must be updated. 70 Memory consumption is increased, because an extra buffer of memory is 71 required for storing the effect output. We recommend that you disable the 72 cache when the source or the effect properties are animated. 73 74 The \uicontrol {Transparent border} property determines the blur behavior 75 near the edges of the component, where the pixel blurring is affected by 76 the pixels outside the source edges. 77 78 If the property is set to \c true, the pixels outside the source are 79 interpreted as being transparent, which is similar to OpenGL clamp-to-border 80 extension. The blur is expanded slightly outside the effect component area. 81 82 If the property is set to \c false, the pixels outside the source are 83 interpreted as containing the same color as the pixels at the edge of 84 the component, which is similar to OpenGL clamp-to-edge behavior. The blur 85 does not expand outside the effect component area. 86 87 \section1 Summary of 2D Effects 88 89 The following table summarizes the available effects and contains links to 90 the developer documentation of the inherited component. The Qt 6 column 91 indicates which effects are available for Qt 6 projects. 92 93 \note The effects are available when running with OpenGL. 94 95 \table 96 \header 97 \li Icon 98 \li Effect 99 \li Qt 6 100 \li Description 101 \row 102 \li \inlineimage icons/blend-mode-16px.png 103 \li \l [QML] {Blend} 104 \li 105 \li Merges two source components by using a blend mode. 106 107 The default \uicontrol Mode is \c subtract, where the pixel value 108 from the component specified in the \uicontrol {Foreground source} 109 field, which is going to be blended over the source component, 110 is subtracted from the source and written over it. 111 112 For a list of possible \uicontrol Mode values and examples of their 113 use, see \l{Blend::mode}{Blend.mode}. 114 \row 115 \li \inlineimage icons/brightness-contrast-16px.png 116 \li \l {BrightnessContrast}{Brightness Contrast} 117 \li \inlineimage ok.png 118 \li Adjusts \uicontrol Brightness and \uicontrol Contrast. 119 \row 120 \li \inlineimage icons/colourize-16px.png 121 \li \l {ColorOverlay}{Color Overlay} 122 \li \inlineimage ok.png 123 \li Alters the colors of the source component by applying an 124 \uicontrol {Overlay color}. You can use the color picker 125 to \l{Picking Colors}{select the color}. 126 \row 127 \li \inlineimage icons/colourize-16px.png 128 \li \l Colorize 129 \li \inlineimage ok.png 130 \li Sets the color in the HSL color space by specifying \uicontrol Hue, 131 \uicontrol Lightness, and \uicontrol Saturation values. 132 \row 133 \li \inlineimage icons/desaturation-16px.png 134 \li \l {Desaturate}{Desaturation} 135 \li \inlineimage ok.png 136 \li Reduces the saturation of the colors by the value set in the 137 \uicontrol Desaturation field. The value ranges from \c 0.0 138 (no change) to \c 1.0 (desaturated). Desaturated pixel values are 139 calculated as averages of the original RGB component values 140 of the source component. 141 \row 142 \li \inlineimage icons/directional-blur-16px.png 143 \li \l {DirectionalBlur}{Directional Blur} 144 \li \inlineimage ok.png 145 \li Applies a blur effect to the specified direction. The value of the 146 \uicontrol Angle field defines the direction of the blur. This 147 effect makes the source component appear to be moving in the direction of 148 the blur. Blur is applied to both sides of each pixel, and therefore 149 setting the direction to \c 0 and \c 180 provides the same result. 150 151 The value of the \uicontrol Length field specifies the perceived 152 amount of movement for each pixel. The movement is divided evenly 153 to both sides of each pixel. 154 155 The quality of the blur depends on the value of the 156 \uicontrol Samples field. If the \uicontrol Length value is large, 157 more samples are needed to preserve high visual quality. 158 \row 159 \li \inlineimage icons/displace-16px.png 160 \li \l Displace 161 \li \inlineimage ok.png 162 \li Moves the pixels of the source component according to the displacement 163 map specified in the \uicontrol {Displacement source} field. 164 165 The value of the \uicontrol Displacement field specifies the 166 scale for the displacement. The larger the scale, the larger the 167 displacement of the pixels. The value set to \c 0.0 causes no 168 displacement. The value of \c -1.0 sets the inverted maximum shift 169 according to the displacement source value, while \c 1.0 sets the 170 maximum shift. 171 \row 172 \li \inlineimage icons/drop-shadow-16px.png 173 \li \l {DropShadow}{Drop Shadow} 174 \li \inlineimage ok.png 175 \li Generates a soft shadow behind the source component using a 176 gaussian blur. This effect blurs the alpha channel of the input and 177 colorizes the result, which it then places behind the source component 178 to create a soft shadow. You can set the shadow's color in the 179 \uicontrol {Drop shadow color} field and change its location in the 180 horizontal (\uicontrol H) and vertical (\uicontrol V) 181 \uicontrol Offset fields. 182 183 The value of the \uicontrol Radius field specifies the softness of 184 the shadow. A larger radius causes the edges of the shadow to appear 185 more blurry. The ideal blur is achieved by setting the value of the 186 \uicontrol Samples field to twice as large as the highest required 187 radius value plus one (\c {samples = 1 + radius * 2}). 188 189 The soft shadow is created by blurring the image live using a 190 gaussian blur, which is a costly operation. Fullscreen gaussian 191 blur with even a moderate number of samples will only run at 60 192 FPS on high-end graphics hardware. 193 \row 194 \li \inlineimage icons/fast-blur-16px.png 195 \li \l {FastBlur}{Fast Blur} 196 \li \inlineimage ok.png 197 \li Applies a fast blur effect to one or more source components. 198 \uicontrol {Fast Blur} offers lower blur quality than 199 \uicontrol {Gaussian Blur}, but it is faster to render. 200 This effect softens the source content by blurring it with 201 an algorithm that uses source content downscaling and 202 bilinear filtering. Use this effect if the source content 203 is rapidly changing and the highest possible blur quality 204 is not needed. 205 206 The value of the \uicontrol Radius field specifies the distance of 207 the neighboring pixels that affect the blurring of an individual 208 pixel. A larger radius increases the blur effect. The fast blur 209 algorithm may internally reduce the accuracy of the radius in order 210 to provide good rendering performance. 211 \row 212 \li \inlineimage icons/gamma-adjust-16px.png 213 \li \l [QML] {GammaAdjust}{Gamma Adjust} 214 \li \inlineimage ok.png 215 \li Alters the luminance of the source component. This effect is applied 216 to each pixel according to the curve that is pre-defined as a 217 power-law expression, where the value of the \uicontrol Gamma 218 field is used as the reciprocal scaling exponent. 219 \row 220 \li \inlineimage icons/gaussian-blur-16px.png 221 \li \l [QML] {GaussianBlur}{Gaussian Blur} 222 \li 223 \li Applies a gaussian blur effect to one or more source components. 224 The effect softens the image by blurring it with an algorithm that 225 uses the gaussian function to calculate the effect. The effect 226 produces higher quality than \uicontrol {Fast Blur}, but is slower 227 to render. Performing blur live is a costly operation. Fullscreen 228 gaussian blur with even a moderate number of \uicontrol Samples 229 will only run at 60 FPS on high-end graphics hardware. 230 231 The value of the \uicontrol Radius field specifies the distance of 232 the neighboring pixels that affect the blurring of an individual 233 pixel. The value of the \uicontrol Distance field is a parameter to 234 the gaussian function that is used when calculating neighboring 235 pixel weights for the blurring. A larger deviation causes an image 236 to appear more blurry, but it also reduces the quality of the blur. 237 A very large deviation value causes the effect to look a bit similar 238 to what, for exmple, a box blur algorithm produces. A too small 239 deviation value makes the effect insignificant for the pixels near 240 the radius. 241 \row 242 \li \inlineimage icons/glow-16px.png 243 \li \l [QML] {Glow} 244 \li \inlineimage ok.png 245 \li Generates a halo-like glow around the source component. This effect 246 blurs the alpha channel of the source and colorizes it with 247 \uicontrol {Glow color}. It then places the alpha channel behind the 248 source, resulting in a halo or glow around the component. The quality 249 of the blurred edge can be controlled by using the values of the 250 \uicontrol Samples and \uicontrol Radius and the strength of the 251 glow can be changed using the value of the \uicontrol Spread field. 252 \row 253 \li \inlineimage icons/hue-saturation-16px.png 254 \li \l {HueSaturation}{Hue Saturation} 255 \li \inlineimage ok.png 256 \li Alters the source component colors in the HSL color space. 257 This effect is similar to the \uicontrol Colorize effect, but 258 the \uicontrol Hue and \uicontrol Saturation values are handled 259 differently. This effect always shifts these values, as well as 260 the \uicontrol Lightness value from the original, instead of 261 setting them. 262 \row 263 \li \inlineimage icons/inner-shadow-16px.png 264 \li \l {InnerShadow}{Inner Shadow} 265 \li 266 \li Generates a colorized and blurred shadow inside the source using 267 the color that you specify in the \uicontrol {Inner shadow color} 268 field. 269 270 The quality of the shadow can be controlled by the values of the 271 \uicontrol Samples and \uicontrol Radius fields. Ideally, the 272 sample value should be twice as large as the highest required 273 radius value. For example, if the radius is animated between 274 \c 0.0 and \c 4.0, samples should be set to \c 8. 275 276 The value of the \uicontrol Spread field specifies how large a part 277 of the shadow color is strengthened near the source edges. 278 The effect produces a high quality shadow image, and therefore the 279 rendering speed of the shadow might not be the highest possible. 280 The rendering speed is reduced especially if the shadow edges are 281 heavily softened. For use cases that require faster rendering speed 282 at the cost of high visual quality, select the \uicontrol Fast 283 check box. 284 \row 285 \li \inlineimage icons/levels-16px.png 286 \li \l {LevelAdjust}{Level Adjust} 287 \li \inlineimage ok.png 288 \li Adjusts color levels in the RGBA color space. This effect adjusts 289 the source component colors separately for each color channel. Source 290 component contrast can be adjusted and color balance altered. 291 292 The value of the \uicontrol Gamma field specifies the change factor 293 for how the value of each pixel color channel is altered according 294 to the equation. Setting the gamma values under 295 \c QtVector3d(1.0, 1.0, 1.0) makes the image darker, whereas the 296 values above \c QtVector3d(1.0, 1.0, 1.0) lighten it. The value 297 ranges from \c QtVector3d(0.0, 0.0, 0.0) (darkest) to \c inf 298 (lightest). 299 300 You can specify the maximum and minimum \uicontrol Input and 301 \uicontrol Output levels for each color channel. \uicontrol Maximum 302 input sets the white-point, which means that all pixels with a 303 higher value are rendered as white (per color channel). Decreasing 304 this value lightens the light areas. To darken the light areas and 305 to increase the contrast, decrease the value of the 306 \uicontrol Maximum output field. 307 308 The value of the \uicontrol Minimum input field sets the minimum 309 input level for each color channel. It sets the black-point, which 310 means that all pixels with a lower value are rendered as black 311 (per color channel). Increasing this value darkens the dark areas. 312 To lighten the dark areas and to reduce the contrast, increase the 313 value of the \uicontrol Minimum output field. 314 \row 315 \li \inlineimage icons/mask-blur-16px.png 316 \li \l {MaskedBlur}{Masked Blur} 317 \li 318 \li Softens the image by blurring it. The intensity of the blur can be 319 controlled for each pixel by specifying a \uicontrol {Mask source}, 320 so that some parts of the source are blurred more than others. 321 322 The value of the \uicontrol Radius field specifies the distance of 323 the neighboring pixels that affect the blurring of an individual 324 pixel. 325 326 The value of the \uicontrol Samples field specifies, how many 327 samples are taken per pixel when blur calculation is done. Larger 328 samples produce better quality, but are slower to render. 329 \row 330 \li \inlineimage icons/opacity-mask-16px.png 331 \li \l {OpacityMask}{Opacity Mask} 332 \li \inlineimage ok.png 333 \li Masks the source component with another component specified in the 334 \uicontrol {Mask source} field. The mask component gets rendered into an 335 intermediate pixel buffer and the alpha values from the result are 336 used to determine the visibility of the source component's pixels in the 337 display. 338 339 Select the \uicontrol Invert check box to specify that the 340 resulting opacity is the source alpha multiplied with the 341 inverse of the mask alpha: \c {As * (1 - Am)}. When this property 342 is \c false, the resulting opacity is the source alpha multiplied 343 with the mask alpha: \c {As * Am}. 344 \row 345 \li \inlineimage icons/radial-blur-16px.png 346 \li \l {RadialBlur}{Radial Blur} 347 \li 348 \li Applies a directional blur effect in a circular direction around the 349 component's center point. This effect makes the source component appear 350 to be rotating into the direction of the blur. Other available 351 motionblur effects are \uicontrol {Zoom Blur} and 352 \uicontrol {Directional Blur}. 353 354 The value of the \uicontrol Angle field specifies both the direction 355 of the blur and the level of blurring. The larger the angle, the 356 more blurred the result. The quality of the blur depends on the 357 value or the \uicontrol Samples field. If the angle is large, more 358 samples are needed to preserve high visual quality. 359 \row 360 \li \inlineimage icons/recursive-blur-16px.png 361 \li \l {RecursiveBlur}{Recursive Blur} 362 \li 363 \li Blurs repeatedly, providing a strong blur effect. This effect 364 softens the image by blurring it with an algorithm that uses a 365 recursive feedback loop to blur the source as many times as 366 set in the \uicontrol Loops field. 367 368 The value of the \uicontrol Radius field specifies the distance of 369 the neighboring pixels that affect the blurring of an individual 370 pixel. 371 372 The effect may produce more blurred results than 373 \uicontrol {Fast Blur} or \uicontrol {Gaussian Blur}, 374 but the result is produced asynchronously and takes more time. 375 \row 376 \li \inlineimage icons/threshold-16px.png 377 \li \l {ThresholdMask}{Threshold Mask} 378 \li \inlineimage ok.png 379 \li Masks the source component with another component specified by 380 \uicontrol {Mask source}. The value of the \uicontrol Spread 381 field determines the smoothness of the mask edges near the 382 \uicontrol Threshold alpha value. Setting spread to \c 0.0 uses 383 the mask with the specified threshold. Setting higher spread values 384 softens the transition from the transparent mask pixels towards 385 opaque mask pixels by adding interpolated values between them. 386 \row 387 \li \inlineimage icons/zoom-blur-16px.png 388 \li \l {ZoomBlur}{Zoom Blur} 389 \li 390 \li Applies a directional blur effect towards source component's 391 center point. This effect makes the source component appear to be 392 moving towards the center point in Z-direction or the camera 393 appear to be zooming rapidly. 394 395 The value of the \uicontrol Length field specifies the maximum 396 perceived amount of movement for each pixel. The amount is smaller 397 near the center specified by the horizontal (\uicontrol H) and 398 vertical (\uicontrol V) \uicontrol Offset fields and reaches the 399 specified value at the edges. 400 401 The quality of the blur depends on the value of the 402 \uicontrol Samples field. If the length value is large, 403 more samples are needed to preserve high visual quality. 404 405 Other available motion blur effects are 406 \uicontrol {Directional Blur} and \uicontrol {Radial Blur}. 407 \endtable 408*/ 409
