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 BrightnessContrast
45    \inqmlmodule QtGraphicalEffects
46    \since QtGraphicalEffects 1.0
47    \inherits QtQuick2::Item
48    \ingroup qtgraphicaleffects-color
49    \brief Adjusts brightness and contrast.
50
51    This effect adjusts the source item colors.
52    Brightness adjustment changes the perceived luminance of the source item.
53    Contrast adjustment increases or decreases the color
54    and brightness variations.
55
56    \table
57    \header
58        \li Source
59        \li Effect applied
60    \row
61        \li \image Original_bug.png
62        \li \image BrightnessContrast_bug.png
63    \endtable
64
65    \note This effect is available when running with OpenGL.
66
67    \section1 Example
68
69    The following example shows how to apply the effect.
70    \snippet BrightnessContrast-example.qml example
71
72*/
73Item {
74    id: rootItem
75
76    /*!
77        This property defines the source item that provides the source pixels
78        for the effect.
79
80        \note It is not supported to let the effect include itself, for
81        instance by setting source to the effect's parent.
82    */
83    property variant source
84
85    /*!
86        This property defines how much the source brightness is increased or
87        decreased.
88
89        The value ranges from -1.0 to 1.0. By default, the property is set to \c
90        0.0 (no change).
91
92        \table
93        \header
94        \li Output examples with different brightness values
95        \li
96        \li
97        \row
98            \li \image BrightnessContrast_brightness1.png
99            \li \image BrightnessContrast_brightness2.png
100            \li \image BrightnessContrast_brightness3.png
101        \row
102            \li \b { brightness: -0.25 }
103            \li \b { brightness: 0 }
104            \li \b { brightness: 0.5 }
105        \row
106            \li \l contrast: 0
107            \li \l contrast: 0
108            \li \l contrast: 0
109        \endtable
110
111    */
112    property real brightness: 0.0
113
114    /*!
115        This property defines how much the source contrast is increased or
116        decreased. The decrease of the contrast is linear, but the increase is
117        applied with a non-linear curve to allow very high contrast adjustment at
118        the high end of the value range.
119
120        \table
121        \header
122            \li Contrast adjustment curve
123        \row
124            \li \image BrightnessContrast_contrast_graph.png
125        \endtable
126
127       The value ranges from -1.0 to 1.0. By default, the property is set to \c 0.0 (no change).
128
129        \table
130        \header
131        \li Output examples with different contrast values
132        \li
133        \li
134        \row
135            \li \image BrightnessContrast_contrast1.png
136            \li \image BrightnessContrast_contrast2.png
137            \li \image BrightnessContrast_contrast3.png
138        \row
139            \li \b { contrast: -0.5 }
140            \li \b { contrast: 0 }
141            \li \b { contrast: 0.5 }
142        \row
143            \li \l brightness: 0
144            \li \l brightness: 0
145            \li \l brightness: 0
146        \endtable
147
148    */
149    property real contrast: 0.0
150
151    /*!
152        This property allows the effect output pixels to be cached in order to
153        improve the rendering performance.
154
155        Every time the source or effect properties are changed, the pixels in
156        the cache must be updated. Memory consumption is increased, because an
157        extra buffer of memory is required for storing the effect output.
158
159        It is recommended to disable the cache when the source or the effect
160        properties are animated.
161
162        By default, the property is set to \c false.
163
164    */
165    property bool cached: false
166
167    SourceProxy {
168        id: sourceProxy
169        input: rootItem.source
170        interpolation: input && input.smooth ? SourceProxy.LinearInterpolation : SourceProxy.NearestInterpolation
171    }
172
173    ShaderEffectSource {
174        id: cacheItem
175        anchors.fill: parent
176        visible: rootItem.cached
177        smooth: true
178        sourceItem: shaderItem
179        live: true
180        hideSource: visible
181    }
182
183    ShaderEffect {
184        id: shaderItem
185        property variant source: sourceProxy.output
186        property real brightness: rootItem.brightness
187        property real contrast: rootItem.contrast
188
189        anchors.fill: parent
190        blending: !rootItem.cached
191
192        fragmentShader: "qrc:/qt-project.org/imports/QtGraphicalEffects/shaders/brightnesscontrast.frag"
193    }
194}
195