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 Colorize
45    \inqmlmodule QtGraphicalEffects
46    \since QtGraphicalEffects 1.0
47    \inherits QtQuick2::Item
48    \ingroup qtgraphicaleffects-color
49    \brief Sets the color in the HSL color space.
50
51    The effect is similar to what happens when a colorized glass is put on top
52    of a grayscale image. Colorize uses the hue, saturation, and lightness (HSL)
53    color space. You can specify a desired value for each property. You can
54    shift all HSL values with the
55    \l{QtGraphicalEffects::HueSaturation}{HueSaturation} effect.
56
57    Alternatively, you can use the
58    \l{QtGraphicalEffects::ColorOverlay}{ColorOverlay} effect to colorize the
59    source item in the RGBA color space.
60
61    \table
62    \header
63        \li Source
64        \li Effect applied
65    \row
66        \li \image Original_bug.png
67        \li \image Colorize_bug.png
68    \endtable
69
70    \note This effect is available when running with OpenGL.
71
72    \section1 Example
73
74    The following example shows how to apply the effect.
75    \snippet Colorize-example.qml example
76*/
77Item {
78    id: rootItem
79
80    /*!
81        This property defines the source item that provides the source pixels
82        for the effect.
83
84        \note It is not supported to let the effect include itself, for
85        instance by setting source to the effect's parent.
86    */
87    property variant source
88
89    /*!
90        This property defines the hue value which is used to colorize the
91        source.
92
93        The value ranges from 0.0 to 1.0. By default, the property is set to \c
94        0.0, which produces a slightly red color.
95
96        \table
97        \header
98            \li Allowed hue values
99        \row
100            \li \image Colorize_hue_scale.png
101        \endtable
102
103        \table
104        \header
105        \li Output examples with different hue values
106        \li
107        \li
108        \row
109            \li \image Colorize_hue1.png
110            \li \image Colorize_hue2.png
111            \li \image Colorize_hue3.png
112        \row
113            \li \b { hue: 0.2 }
114            \li \b { hue: 0.5 }
115            \li \b { hue: 0.8 }
116        \row
117            \li \l saturation: 1
118            \li \l saturation: 1
119            \li \l saturation: 1
120        \row
121            \li \l lightness: 0
122            \li \l lightness: 0
123            \li \l lightness: 0
124        \endtable
125    */
126    property real hue: 0.0
127
128    /*!
129        This property defines the saturation value which is used to colorize the
130        source.
131
132        The value ranges from 0.0 (desaturated) to 1.0 (saturated). By default,
133        the property is set to \c 1.0 (saturated).
134
135        \table
136        \header
137        \li Output examples with different saturation values
138        \li
139        \li
140        \row
141            \li \image Colorize_saturation1.png
142            \li \image Colorize_saturation2.png
143            \li \image Colorize_saturation3.png
144        \row
145            \li \b { saturation: 0 }
146            \li \b { saturation: 0.5 }
147            \li \b { saturation: 1 }
148        \row
149            \li \l hue: 0
150            \li \l hue: 0
151            \li \l hue: 0
152        \row
153            \li \l lightness: 0
154            \li \l lightness: 0
155            \li \l lightness: 0
156        \endtable
157    */
158    property real saturation: 1.0
159
160    /*!
161        This property defines how much the source lightness value is increased
162        or decreased.
163
164        Unlike hue and saturation properties, lightness does not set the used
165        value, but it shifts the existing source pixel lightness value.
166
167        The value ranges from -1.0 (decreased) to 1.0 (increased). By default,
168        the property is set to \c 0.0 (no change).
169
170        \table
171        \header
172        \li Output examples with different lightness values
173        \li
174        \li
175        \row
176            \li \image Colorize_lightness1.png
177            \li \image Colorize_lightness2.png
178            \li \image Colorize_lightness3.png
179        \row
180            \li \b { lightness: -0.75 }
181            \li \b { lightness: 0 }
182            \li \b { lightness: 0.75 }
183        \row
184            \li \l hue: 0
185            \li \l hue: 0
186            \li \l hue: 0
187        \row
188            \li \l saturation: 1
189            \li \l saturation: 1
190            \li \l saturation: 1
191        \endtable
192    */
193    property real lightness: 0.0
194
195    /*!
196        This property allows the effect output pixels to be cached in order to
197        improve the rendering performance.
198
199        Every time the source or effect properties are changed, the pixels in
200        the cache must be updated. Memory consumption is increased, because an
201        extra buffer of memory is required for storing the effect output.
202
203        It is recommended to disable the cache when the source or the effect
204        properties are animated.
205
206        By default, the property is set to \c false.
207    */
208    property bool cached: false
209
210    SourceProxy {
211        id: sourceProxy
212        input: rootItem.source
213        interpolation: input && input.smooth ? SourceProxy.LinearInterpolation : SourceProxy.NearestInterpolation
214    }
215
216    ShaderEffectSource {
217        id: cacheItem
218        anchors.fill: parent
219        visible: rootItem.cached
220        smooth: true
221        sourceItem: shaderItem
222        live: true
223        hideSource: visible
224    }
225
226    ShaderEffect {
227        id: shaderItem
228        property variant source: sourceProxy.output
229        property real hue: rootItem.hue
230        property real saturation: rootItem.saturation
231        property real lightness: rootItem.lightness
232
233        anchors.fill: parent
234
235        fragmentShader: "qrc:/qt-project.org/imports/QtGraphicalEffects/shaders/colorize.frag"
236
237    }
238}
239