1/* This file is part of the KDE project
2 SPDX-FileCopyrightText: 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
3 SPDX-FileCopyrightText: 2007 Thomas Zander <zander@kde.org>
4 SPDX-FileCopyrightText: 2007 Zack Rusin <zack@kde.org>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef KCOLORUTILS_H
10#define KCOLORUTILS_H
11
12#include <kguiaddons_export.h>
13
14#include <QPainter>
15
16class QColor;
17
18/**
19 * A set of methods used to work with colors.
20 */
21namespace KColorUtils
22{
23/**
24 * Calculate the hue of a color. The range is from 0.0 (red) to almost 1.0 (slightly blue-ish red).
25 *
26 * The result is computed in linear (not sRGB) color space and may differ slightly from QColor::hue().
27 *
28 * @see https://en.wikipedia.org/wiki/Hue
29 * @since 5.68
30 */
31KGUIADDONS_EXPORT qreal hue(const QColor &);
32
33/**
34 * Calculate the chroma of a color. The range is from 0.0 (none) to 1.0 (full).
35 *
36 * The result is computed in linear (not sRGB) color space.
37 *
38 * @see https://en.wikipedia.org/wiki/Colorfulness
39 * @since 5.68
40 */
41KGUIADDONS_EXPORT qreal chroma(const QColor &);
42
43/**
44 * Calculate the luma of a color. Luma is weighted sum of gamma-adjusted
45 * R'G'B' components of a color. The result is similar to qGray. The range
46 * is from 0.0 (black) to 1.0 (white).
47 *
48 * The result is computed in linear (not sRGB) color space.
49 *
50 * KColorUtils::darken(), KColorUtils::lighten() and KColorUtils::shade()
51 * operate on the luma of a color.
52 *
53 * @see http://en.wikipedia.org/wiki/Luma_(video)
54 */
55KGUIADDONS_EXPORT qreal luma(const QColor &);
56
57/**
58 * Calculate hue, chroma and luma of a color in one call.
59 *
60 * The range of hue is from 0.0 (red) to almost 1.0 (slightly blue-ish red).
61 * The range of chroma is from 0.0 (none) to 1.0 (full).
62 * The range of luma is from 0.0 (black) to 1.0 (white).
63 *
64 * The hue, chroma and luma values are computed in linear (not sRGB) color space.
65 *
66 * @since 5.0
67 */
68KGUIADDONS_EXPORT void getHcy(const QColor &, qreal *hue, qreal *chroma, qreal *luma, qreal *alpha = nullptr);
69
70/**
71 * Return a QColor based on the given hue, chroma, luma and alpha values.
72 *
73 * The range of hue is cyclical. For example, 0.0 and 1.0 are both red while -0.166667 and 0.833333 are both magenta.
74 * The range of chroma is from 0.0 (none) to 1.0 (full). Out of range values will be clamped.
75 * The range of luma is from 0.0 (black) to 1.0 (white). Out of range values will be clamped.
76 *
77 * The hue, chroma and luma values are computed in linear (not sRGB) color space.
78 *
79 * @since 5.68
80 */
81KGUIADDONS_EXPORT QColor hcyColor(qreal hue, qreal chroma, qreal luma, qreal alpha = 1.0);
82
83/**
84 * Calculate the contrast ratio between two colors, according to the
85 * W3C/WCAG2.0 algorithm, (Lmax + 0.05)/(Lmin + 0.05), where Lmax and Lmin
86 * are the luma values of the lighter color and the darker color,
87 * respectively.
88 *
89 * A contrast ration of 5:1 (result == 5.0) is the minimum for "normal"
90 * text to be considered readable (large text can go as low as 3:1). The
91 * ratio ranges from 1:1 (result == 1.0) to 21:1 (result == 21.0).
92 *
93 * @see KColorUtils::luma
94 */
95KGUIADDONS_EXPORT qreal contrastRatio(const QColor &, const QColor &);
96
97/**
98 * Adjust the luma of a color by changing its distance from white.
99 *
100 * @li amount == 1.0 gives white
101 * @li amount == 0.5 results in a color whose luma is halfway between 1.0
102 * and that of the original color
103 * @li amount == 0.0 gives the original color
104 * @li amount == -1.0 gives a color that is 'twice as far from white' as
105 * the original color, that is luma(result) == 1.0 - 2*(1.0 - luma(color))
106 *
107 * @param amount factor by which to adjust the luma component of the color
108 * @param chromaInverseGain (optional) factor by which to adjust the chroma
109 * component of the color; 1.0 means no change, 0.0 maximizes chroma
110 * @see KColorUtils::shade
111 */
112KGUIADDONS_EXPORT QColor lighten(const QColor &, qreal amount = 0.5, qreal chromaInverseGain = 1.0);
113
114/**
115 * Adjust the luma of a color by changing its distance from black.
116 *
117 * @li amount == 1.0 gives black
118 * @li amount == 0.5 results in a color whose luma is halfway between 0.0
119 * and that of the original color
120 * @li amount == 0.0 gives the original color
121 * @li amount == -1.0 gives a color that is 'twice as far from black' as
122 * the original color, that is luma(result) == 2*luma(color)
123 *
124 * @param amount factor by which to adjust the luma component of the color
125 * @param chromaGain (optional) factor by which to adjust the chroma
126 * component of the color; 1.0 means no change, 0.0 minimizes chroma
127 * @see KColorUtils::shade
128 */
129KGUIADDONS_EXPORT QColor darken(const QColor &, qreal amount = 0.5, qreal chromaGain = 1.0);
130
131/**
132 * Adjust the luma and chroma components of a color. The amount is added
133 * to the corresponding component.
134 *
135 * @param lumaAmount amount by which to adjust the luma component of the
136 * color; 0.0 results in no change, -1.0 turns anything black, 1.0 turns
137 * anything white
138 * @param chromaAmount (optional) amount by which to adjust the chroma
139 * component of the color; 0.0 results in no change, -1.0 minimizes chroma,
140 * 1.0 maximizes chroma
141 * @see KColorUtils::luma
142 */
143KGUIADDONS_EXPORT QColor shade(const QColor &, qreal lumaAmount, qreal chromaAmount = 0.0);
144
145/**
146 * Create a new color by tinting one color with another. This function is
147 * meant for creating additional colors withings the same class (background,
148 * foreground) from colors in a different class. Therefore when @p amount
149 * is low, the luma of @p base is mostly preserved, while the hue and
150 * chroma of @p color is mostly inherited.
151 *
152 * @param base color to be tinted
153 * @param color color with which to tint
154 * @param amount how strongly to tint the base; 0.0 gives @p base,
155 * 1.0 gives @p color
156 */
157KGUIADDONS_EXPORT QColor tint(const QColor &base, const QColor &color, qreal amount = 0.3);
158
159/**
160 * Blend two colors into a new color by linear combination.
161 * @code
162 QColor lighter = KColorUtils::mix(myColor, Qt::white)
163 * @endcode
164 * @param c1 first color.
165 * @param c2 second color.
166 * @param bias weight to be used for the mix. @p bias <= 0 gives @p c1,
167 * @p bias >= 1 gives @p c2. @p bias == 0.5 gives a 50% blend of @p c1
168 * and @p c2.
169 */
170KGUIADDONS_EXPORT QColor mix(const QColor &c1, const QColor &c2, qreal bias = 0.5);
171
172/**
173 * Blend two colors into a new color by painting the second color over the
174 * first using the specified composition mode.
175 * @code
176 QColor white(Qt::white);
177 white.setAlphaF(0.5);
178 QColor lighter = KColorUtils::overlayColors(myColor, white);
179 @endcode
180 * @param base the base color (alpha channel is ignored).
181 * @param paint the color to be overlaid onto the base color.
182 * @param comp the CompositionMode used to do the blending.
183 */
184KGUIADDONS_EXPORT QColor overlayColors(const QColor &base, const QColor &paint, QPainter::CompositionMode comp = QPainter::CompositionMode_SourceOver);
185}
186
187#endif // KCOLORUTILS_H
188

source code of kguiaddons/src/colors/kcolorutils.h