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 ColorOverlay
45    \inqmlmodule QtGraphicalEffects
46    \since QtGraphicalEffects 1.0
47    \inherits QtQuick2::Item
48    \ingroup qtgraphicaleffects-color
49    \brief Alters the colors of the source item by applying an overlay color.
50
51    The effect is similar to what happens when a colorized glass is put on top
52    of a grayscale image. The color for the overlay is given in the RGBA format.
53
54    \table
55    \header
56        \li Source
57        \li Effect applied
58    \row
59        \li \image Original_butterfly.png
60        \li \image ColorOverlay_butterfly.png
61    \endtable
62
63    \note This effect is available when running with OpenGL.
64
65    \section1 Example
66
67    The following example shows how to apply the effect.
68    \snippet ColorOverlay-example.qml example
69
70*/
71Item {
72    id: rootItem
73
74    /*!
75        This property defines the source item that provides the source pixels
76        for the effect.
77
78        \note It is not supported to let the effect include itself, for
79        instance by setting source to the effect's parent.
80    */
81    property variant source
82
83    /*!
84        This property defines the RGBA color value which is used to colorize the
85        source.
86
87        By default, the property is set to \c "transparent".
88
89        \table
90        \header
91        \li Output examples with different color values
92        \li
93        \li
94        \row
95            \li \image ColorOverlay_color1.png
96            \li \image ColorOverlay_color2.png
97            \li \image ColorOverlay_color3.png
98        \row
99            \li \b { color: #80ff0000 }
100            \li \b { color: #8000ff00 }
101            \li \b { color: #800000ff }
102        \endtable
103
104    */
105    property color color: "transparent"
106
107    /*!
108        This property allows the effect output pixels to be cached in order to
109        improve the rendering performance.
110
111        Every time the source or effect properties are changed, the pixels in
112        the cache must be updated. Memory consumption is increased, because an
113        extra buffer of memory is required for storing the effect output.
114
115        It is recommended to disable the cache when the source or the effect
116        properties are animated.
117
118        By default, the property is set to \c false.
119
120    */
121    property bool cached: false
122
123    SourceProxy {
124        id: sourceProxy
125        input: rootItem.source
126        interpolation: input && input.smooth ? SourceProxy.LinearInterpolation : SourceProxy.NearestInterpolation
127    }
128
129    ShaderEffectSource {
130        id: cacheItem
131        anchors.fill: parent
132        visible: rootItem.cached
133        smooth: true
134        sourceItem: shaderItem
135        live: true
136        hideSource: visible
137    }
138
139    ShaderEffect {
140        id: shaderItem
141        property variant source: sourceProxy.output
142        property color color: rootItem.color
143
144        anchors.fill: parent
145
146        fragmentShader: "qrc:/qt-project.org/imports/QtGraphicalEffects/shaders/coloroverlay.frag"
147    }
148}
149