1/**************************************************************************** 2** 3** Copyright (C) 2017 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the Qt Graphical Effects module. 7** 8** $QT_BEGIN_LICENSE:LGPL$ 9** Commercial License Usage 10** Licensees holding valid commercial Qt licenses may use this file in 11** accordance with the commercial license agreement provided with the 12** Software or, alternatively, in accordance with the terms contained in 13** a written agreement between you and The Qt Company. For licensing terms 14** and conditions see https://www.qt.io/terms-conditions. For further 15** information use the contact form at https://www.qt.io/contact-us. 16** 17** GNU Lesser General Public License Usage 18** Alternatively, this file may be used under the terms of the GNU Lesser 19** General Public License version 3 as published by the Free Software 20** Foundation and appearing in the file LICENSE.LGPL3 included in the 21** packaging of this file. Please review the following information to 22** ensure the GNU Lesser General Public License version 3 requirements 23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. 24** 25** GNU General Public License Usage 26** Alternatively, this file may be used under the terms of the GNU 27** General Public License version 2.0 or (at your option) the GNU General 28** Public license version 3 or any later version approved by the KDE Free 29** Qt Foundation. The licenses are as published by the Free Software 30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 31** included in the packaging of this file. Please review the following 32** information to ensure the GNU General Public License requirements will 33** be met: https://www.gnu.org/licenses/gpl-2.0.html and 34** https://www.gnu.org/licenses/gpl-3.0.html. 35** 36** $QT_END_LICENSE$ 37** 38****************************************************************************/ 39 40import QtQuick 2.12 41import QtGraphicalEffects.private 1.12 42 43/*! 44 \qmltype ThresholdMask 45 \inqmlmodule QtGraphicalEffects 46 \since QtGraphicalEffects 1.0 47 \inherits QtQuick2::Item 48 \ingroup qtgraphicaleffects-mask 49 \brief Masks the source item with another item and applies a threshold 50 value. 51 52 The masking behavior can be controlled with the \l threshold value for the 53 mask pixels. 54 55 \table 56 \header 57 \li Source 58 \li MaskSource 59 \li Effect applied 60 \row 61 \li \image Original_bug.png 62 \li \image ThresholdMask_mask.png 63 \li \image ThresholdMask_bug.png 64 \endtable 65 66 \note This effect is available when running with OpenGL. 67 68 \section1 Example 69 70 The following example shows how to apply the effect. 71 \snippet ThresholdMask-example.qml example 72*/ 73Item { 74 id: rootItem 75 76 /*! 77 This property defines the source item that is going to be masked. 78 79 \note It is not supported to let the effect include itself, for 80 instance by setting source to the effect's parent. 81 */ 82 property variant source 83 84 /*! 85 This property defines the item that is going to be used as the mask. 86 Mask item gets rendered into an intermediate pixel buffer and the alpha 87 values from the result are used to determine the source item's pixels 88 visibility in the display. 89 90 \table 91 \header 92 \li Original 93 \li Mask 94 \li Effect applied 95 \row 96 \li \image Original_bug.png 97 \li \image ThresholdMask_mask.png 98 \li \image ThresholdMask_bug.png 99 \endtable 100 101 \note It is not supported to let the effect include itself, for 102 instance by setting maskSource to the effect's parent. 103 */ 104 property variant maskSource 105 106 /*! 107 This property defines a threshold value for the mask pixels. The mask 108 pixels that have an alpha value below this property are used to 109 completely mask away the corresponding pixels from the source item. The 110 mask pixels that have a higher alpha value are used to alphablend the 111 source item to the display. 112 113 The value ranges from 0.0 (alpha value 0) to 1.0 (alpha value 255). By 114 default, the property is set to \c 0.0. 115 116 \table 117 \header 118 \li Output examples with different threshold values 119 \li 120 \li 121 \row 122 \li \image ThresholdMask_threshold1.png 123 \li \image ThresholdMask_threshold2.png 124 \li \image ThresholdMask_threshold3.png 125 \row 126 \li \b { threshold: 0.0 } 127 \li \b { threshold: 0.5 } 128 \li \b { threshold: 0.7 } 129 \row 130 \li \l spread: 0.2 131 \li \l spread: 0.2 132 \li \l spread: 0.2 133 \endtable 134 */ 135 property real threshold: 0.0 136 137 /*! 138 This property defines the smoothness of the mask edges near the 139 \l{ThresholdMask::threshold}{threshold} alpha value. Setting spread to 140 0.0 uses mask normally with the specified threshold. Setting higher 141 spread values softens the transition from the transparent mask pixels 142 towards opaque mask pixels by adding interpolated values between them. 143 144 The value ranges from 0.0 (sharp mask edge) to 1.0 (smooth mask edge). 145 By default, the property is set to \c 0.0. 146 147 \table 148 \header 149 \li Output examples with different spread values 150 \li 151 \li 152 \row 153 \li \image ThresholdMask_spread1.png 154 \li \image ThresholdMask_spread2.png 155 \li \image ThresholdMask_spread3.png 156 \row 157 \li \b { spread: 0.0 } 158 \li \b { spread: 0.2 } 159 \li \b { spread: 0.8 } 160 \row 161 \li \l threshold: 0.4 162 \li \l threshold: 0.4 163 \li \l threshold: 0.4 164 \endtable 165 166 */ 167 property real spread: 0.0 168 169 /*! 170 This property allows the effect output pixels to be cached in order to 171 improve the rendering performance. 172 173 Every time the source or effect properties are changed, the pixels in 174 the cache must be updated. Memory consumption is increased, because an 175 extra buffer of memory is required for storing the effect output. 176 177 It is recommended to disable the cache when the source or the effect 178 properties are animated. 179 180 By default, the property is set to \c false. 181 */ 182 property bool cached: false 183 184 SourceProxy { 185 id: sourceProxy 186 input: rootItem.source 187 } 188 189 SourceProxy { 190 id: maskSourceProxy 191 input: rootItem.maskSource 192 } 193 194 ShaderEffectSource { 195 id: cacheItem 196 anchors.fill: parent 197 visible: rootItem.cached 198 smooth: true 199 sourceItem: shaderItem 200 live: true 201 hideSource: visible 202 } 203 204 ShaderEffect { 205 id: shaderItem 206 property variant source: sourceProxy.output 207 property variant maskSource: maskSourceProxy.output 208 property real threshold: rootItem.threshold 209 property real spread: rootItem.spread 210 211 anchors.fill: parent 212 213 fragmentShader: "qrc:/qt-project.org/imports/QtGraphicalEffects/shaders/thresholdmask.frag" 214 } 215} 216