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 GammaAdjust
45    \inqmlmodule QtGraphicalEffects
46    \since QtGraphicalEffects 1.0
47    \inherits QtQuick2::Item
48    \ingroup qtgraphicaleffects-color
49    \brief Alters the luminance of the source item.
50
51    GammaAdjust is applied to each pixel according to the curve which is
52    pre-defined as a power-law expression, where the property gamma is used as the
53    reciprocal scaling exponent. Refer to the property documentation of \l{GammaAdjust::gamma}{gamma}
54    for more details.
55
56    \table
57    \header
58        \li Source
59        \li Effect applied
60    \row
61        \li \image Original_bug.png
62        \li \image GammaAdjust_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 GammaAdjust-example.qml example
71
72*/
73Item {
74    id: rootItem
75
76    /*!
77        This property defines the source item for which the luminance is going to be
78        adjusted.
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 the change factor for how the luminance of each pixel
87        is altered according to the equation:
88
89        \code
90luminance = pow(original_luminance, 1.0 / gamma); // The luminance is assumed to be between 0.0 and 1.0
91        \endcode
92
93        Setting the gamma values under 1.0 makes the image darker, the values
94        above 1.0 lighten it.
95
96        The value ranges from 0.0 (darkest) to inf (lightest). By default, the
97        property is set to \c 1.0 (no change).
98
99        \table
100        \header
101        \li Output examples with different gamma values
102        \li
103        \li
104        \row
105            \li \image GammaAdjust_gamma1.png
106            \li \image GammaAdjust_gamma2.png
107            \li \image GammaAdjust_gamma3.png
108        \row
109            \li \b { gamma: 0.5 }
110            \li \b { gamma: 1.0 }
111            \li \b { gamma: 2.0 }
112        \endtable
113
114        \table
115        \header
116            \li Pixel luminance curves of the above images.
117            \li
118            \li
119        \row
120            \li \image GammaAdjust_gamma1_graph.png
121            \li \image GammaAdjust_gamma2_graph.png
122            \li \image GammaAdjust_gamma3_graph.png
123        \row
124            \li Red curve: default gamma (1.0)
125            \li
126            \li
127        \row
128            \li Yellow curve: effect applied
129            \li
130            \li
131        \row
132            \li X-axis: pixel original luminance
133            \li
134            \li
135        \row
136            \li Y-axis: pixel luminance with effect applied
137            \li
138            \li
139        \endtable
140
141    */
142    property real gamma: 1.0
143
144    /*!
145        This property allows the effect output pixels to be cached in order to
146        improve the rendering performance.
147
148        Every time the source or effect properties are changed, the pixels in
149        the cache must be updated. Memory consumption is increased, because an
150        extra buffer of memory is required for storing the effect output.
151
152        It is recommended to disable the cache when the source or the effect
153        properties are animated.
154
155        By default, the property is set to \c false.
156    */
157    property bool cached: false
158
159    SourceProxy {
160        id: sourceProxy
161        input: rootItem.source
162        interpolation: input && input.smooth ? SourceProxy.LinearInterpolation : SourceProxy.NearestInterpolation
163    }
164
165    ShaderEffectSource {
166        id: cacheItem
167        anchors.fill: parent
168        visible: rootItem.cached
169        smooth: true
170        sourceItem: shaderItem
171        live: true
172        hideSource: visible
173    }
174
175    ShaderEffect {
176        id: shaderItem
177        property variant source: sourceProxy.output
178        property real gamma: 1.0 / Math.max(rootItem.gamma, 0.0001)
179
180        anchors.fill: parent
181
182        fragmentShader: "qrc:/qt-project.org/imports/QtGraphicalEffects/shaders/gammaadjust.frag"
183    }
184}
185