1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef UI_GFX_COLOR_UTILS_H_
6 #define UI_GFX_COLOR_UTILS_H_
7 
8 #include <string>
9 #include <tuple>
10 
11 #include "base/optional.h"
12 #include "third_party/skia/include/core/SkColor.h"
13 #include "ui/gfx/gfx_export.h"
14 
15 class SkBitmap;
16 
17 namespace color_utils {
18 
19 // Represents an HSL color.
20 struct HSL {
21   double h;
22   double s;
23   double l;
24 };
25 
26 // The blend alpha and resulting color when blending to achieve a desired
27 // contrast raio.
28 struct BlendResult {
29   SkAlpha alpha;
30   SkColor color;
31 };
32 
33 // The minimum contrast between text and background that is still readable.
34 // This value is taken from w3c accessibility guidelines.
35 constexpr float kMinimumReadableContrastRatio = 4.5f;
36 
37 // Determines the contrast ratio of two colors or two relative luminance values
38 // (as computed by RelativeLuminance()), calculated according to
39 // http://www.w3.org/TR/WCAG20/#contrast-ratiodef .
40 GFX_EXPORT float GetContrastRatio(SkColor color_a, SkColor color_b);
41 GFX_EXPORT float GetContrastRatio(float luminance_a, float luminance_b);
42 
43 // The relative luminance of |color|, that is, the weighted sum of the
44 // linearized RGB components, normalized to 0..1, per BT.709.  See
45 // http://www.w3.org/TR/WCAG20/#relativeluminancedef .
46 GFX_EXPORT float GetRelativeLuminance(SkColor color);
47 
48 // The luma of |color|, that is, the weighted sum of the gamma-compressed R'G'B'
49 // components, per BT.601, a.k.a. the Y' in Y'UV.  See
50 // https://en.wikipedia.org/wiki/Luma_(video).
51 GFX_EXPORT uint8_t GetLuma(SkColor color);
52 
53 // Note: these transformations assume sRGB as the source color space
54 GFX_EXPORT void SkColorToHSL(SkColor c, HSL* hsl);
55 GFX_EXPORT SkColor HSLToSkColor(const HSL& hsl, SkAlpha alpha);
56 
57 // Determines whether the given |hsl| falls within the given range for each
58 // component. All components of |hsl| are expected to be in the range [0, 1].
59 //
60 // If a component is negative in either |lower_bound| or |upper_bound|, that
61 // component will be ignored.
62 //
63 // For hue, the lower bound should be in the range [0, 1] and the upper bound
64 // should be in the range [(lower bound), (lower bound + 1)].
65 // For saturation and value, bounds should be specified in the range [0, 1],
66 // with the lower bound less than the upper bound.
67 GFX_EXPORT bool IsWithinHSLRange(const HSL& hsl,
68                                  const HSL& lower_bound,
69                                  const HSL& upper_bound);
70 
71 // Makes |hsl| valid input for HSLShift(). Sets values of hue, saturation
72 // and lightness which are outside of the valid range [0, 1] to -1.  -1 is a
73 // special value which indicates 'no change'.
74 GFX_EXPORT void MakeHSLShiftValid(HSL* hsl);
75 
76 // Returns whether pasing |hsl| to HSLShift() would have any effect.  Assumes
77 // |hsl| is a valid shift (as defined by MakeHSLShiftValid()).
78 GFX_EXPORT bool IsHSLShiftMeaningful(const HSL& hsl);
79 
80 // HSL-Shift an SkColor. The shift values are in the range of 0-1, with the
81 // option to specify -1 for 'no change'. The shift values are defined as:
82 // hsl_shift[0] (hue): The absolute hue value - 0 and 1 map
83 //    to 0 and 360 on the hue color wheel (red).
84 // hsl_shift[1] (saturation): A saturation shift, with the
85 //    following key values:
86 //    0 = remove all color.
87 //    0.5 = leave unchanged.
88 //    1 = fully saturate the image.
89 // hsl_shift[2] (lightness): A lightness shift, with the
90 //    following key values:
91 //    0 = remove all lightness (make all pixels black).
92 //    0.5 = leave unchanged.
93 //    1 = full lightness (make all pixels white).
94 GFX_EXPORT SkColor HSLShift(SkColor color, const HSL& shift);
95 
96 // Builds a histogram based on the Y' of the Y'UV representation of this image.
97 GFX_EXPORT void BuildLumaHistogram(const SkBitmap& bitmap, int histogram[256]);
98 
99 // Calculates how "boring" an image is. The boring score is the
100 // 0,1 ranged percentage of pixels that are the most common
101 // luma. Higher boring scores indicate that a higher percentage of a
102 // bitmap are all the same brightness.
103 GFX_EXPORT double CalculateBoringScore(const SkBitmap& bitmap);
104 
105 // Returns a blend of the supplied colors, ranging from |background| (for
106 // |alpha| == 0) to |foreground| (for |alpha| == 255). The alpha channels of
107 // the supplied colors are also taken into account, so the returned color may
108 // be partially transparent.
109 GFX_EXPORT SkColor AlphaBlend(SkColor foreground,
110                               SkColor background,
111                               SkAlpha alpha);
112 
113 // As above, but with alpha specified as 0..1.
114 GFX_EXPORT SkColor AlphaBlend(SkColor foreground,
115                               SkColor background,
116                               float alpha);
117 
118 // Returns the color that results from painting |foreground| on top of
119 // |background|.
120 GFX_EXPORT SkColor GetResultingPaintColor(SkColor foreground,
121                                           SkColor background);
122 
123 // Returns true if |color| contrasts more with white than the darkest color.
124 GFX_EXPORT bool IsDark(SkColor color);
125 
126 // Returns whichever of white or the darkest available color contrasts more with
127 // |color|.
128 GFX_EXPORT SkColor GetColorWithMaxContrast(SkColor color);
129 
130 // Returns whichever of white or the darkest available color contrasts less with
131 // |color|.
132 GFX_EXPORT SkColor GetEndpointColorWithMinContrast(SkColor color);
133 
134 // Blends towards the color with max contrast by |alpha|. The alpha of
135 // the original color is preserved.
136 GFX_EXPORT SkColor BlendTowardMaxContrast(SkColor color, SkAlpha alpha);
137 
138 // Returns whichever of |foreground1| or |foreground2| has higher contrast with
139 // |background|.
140 GFX_EXPORT SkColor PickContrastingColor(SkColor foreground1,
141                                         SkColor foreground2,
142                                         SkColor background);
143 
144 // Alpha-blends |default_foreground| toward either |high_contrast_foreground|
145 // (if specified) or the color with max contrast with |background| until either
146 // the result has a contrast ratio against |background| of at least
147 // |contrast_ratio| or the blend can go no further.  Returns the blended color
148 // and the alpha used to achieve that blend.  If |default_foreground| already
149 // has sufficient contrast, returns an alpha of 0 and color of
150 // |default_foreground|.
151 GFX_EXPORT BlendResult BlendForMinContrast(
152     SkColor default_foreground,
153     SkColor background,
154     base::Optional<SkColor> high_contrast_foreground = base::nullopt,
155     float contrast_ratio = kMinimumReadableContrastRatio);
156 
157 // Invert a color.
158 GFX_EXPORT SkColor InvertColor(SkColor color);
159 
160 // Gets a Windows system color as a SkColor
161 GFX_EXPORT SkColor GetSysSkColor(int which);
162 
163 // Derives a color for icons on a UI surface based on the text color on the same
164 // surface.
165 GFX_EXPORT SkColor DeriveDefaultIconColor(SkColor text_color);
166 
167 // Creates an rgba string for an SkColor. For example: 'rgba(255,0,255,0.5)'.
168 GFX_EXPORT std::string SkColorToRgbaString(SkColor color);
169 
170 // Creates an rgb string for an SkColor. For example: '255,0,255'.
171 GFX_EXPORT std::string SkColorToRgbString(SkColor color);
172 
173 // Sets the darkest available color to |color|.  Returns the previous darkest
174 // color.
175 GFX_EXPORT SkColor SetDarkestColorForTesting(SkColor color);
176 
177 // Returns the luminance of the darkest, midpoint, and lightest colors.
178 GFX_EXPORT std::tuple<float, float, float> GetLuminancesForTesting();
179 
180 }  // namespace color_utils
181 
182 #endif  // UI_GFX_COLOR_UTILS_H_
183