1 /*
2 * Copyright 2006 The Android Open Source Project
3 *
4 * Use of this source code is governed by a BSD-style license that can be
5 * found in the LICENSE file.
6 */
7
8 /* Generated by tools/bookmaker from include/core/SkColor.h and docs/SkColor_Reference.bmh
9 on 2018-06-14 13:13:34. Additional documentation and examples can be found at:
10 https://skia.org/user/api/SkColor_Reference
11
12 You may edit either file directly. Structural changes to public interfaces require
13 editing both files. After editing docs/SkColor_Reference.bmh, run:
14 bookmaker -b docs -i include/core/SkColor.h -p
15 to create an updated version of this file.
16 */
17
18 #ifndef SkColor_DEFINED
19 #define SkColor_DEFINED
20
21 #include "SkImageInfo.h"
22 #include "SkScalar.h"
23 #include "SkTypes.h"
24
25 /** \file SkColor.h
26
27 Types, consts, functions, and macros for colors.
28 */
29
30 /** 8-bit type for an alpha value. 255 is 100% opaque, zero is 100% transparent.
31 */
32 typedef uint8_t SkAlpha;
33
34 /** 32-bit ARGB color value, unpremultiplied. Color components are always in
35 a known order. This is different from SkPMColor, which has its bytes in a configuration
36 dependent order, to match the format of kBGRA_8888_SkColorType bitmaps. SkColor
37 is the type used to specify colors in SkPaint and in gradients.
38
39 Color that is premultiplied has the same component values as color
40 that is unpremultiplied if alpha is 255, fully opaque, although may have the
41 component values in a different order.
42 */
43 typedef uint32_t SkColor;
44
45 /** Returns color value from 8-bit component values. Asserts if SK_DEBUG is defined
46 if a, r, g, or b exceed 255. Since color is unpremultiplied, a may be smaller
47 than the largest of r, g, and b.
48
49 @param a amount of alpha, from fully transparent (0) to fully opaque (255)
50 @param r amount of red, from no red (0) to full red (255)
51 @param g amount of green, from no green (0) to full green (255)
52 @param b amount of blue, from no blue (0) to full blue (255)
53 @return color and alpha, unpremultiplied
54 */
SkColorSetARGB(U8CPU a,U8CPU r,U8CPU g,U8CPU b)55 static constexpr inline SkColor SkColorSetARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) {
56 return SkASSERT(a <= 255 && r <= 255 && g <= 255 && b <= 255),
57 (a << 24) | (r << 16) | (g << 8) | (b << 0);
58 }
59
60 /** Returns color value from 8-bit component values, with alpha set
61 fully opaque to 255.
62 */
63 #define SkColorSetRGB(r, g, b) SkColorSetARGB(0xFF, r, g, b)
64
65 /** Returns alpha byte from color value.
66 */
67 #define SkColorGetA(color) (((color) >> 24) & 0xFF)
68
69 /** Returns red component of color, from zero to 255.
70 */
71 #define SkColorGetR(color) (((color) >> 16) & 0xFF)
72
73 /** Returns green component of color, from zero to 255.
74 */
75 #define SkColorGetG(color) (((color) >> 8) & 0xFF)
76
77 /** Returns blue component of color, from zero to 255.
78 */
79 #define SkColorGetB(color) (((color) >> 0) & 0xFF)
80
81 /** Returns unpremultiplied color with red, blue, and green set from c; and alpha set
82 from a. Alpha component of c is ignored and is replaced by a in result.
83
84 @param c packed RGB, eight bits per component
85 @param a alpha: transparent at zero, fully opaque at 255
86 @return color with transparency
87 */
SkColorSetA(SkColor c,U8CPU a)88 static constexpr inline SkColor SkColorSetA(SkColor c, U8CPU a) {
89 return (c & 0x00FFFFFF) | (a << 24);
90 }
91
92 /** Represents fully transparent SkAlpha value. SkAlpha ranges from zero,
93 fully transparent; to 255, fully opaque.
94 */
95 constexpr SkAlpha SK_AlphaTRANSPARENT = 0x00;
96
97 /** Represents fully opaque SkAlpha value. SkAlpha ranges from zero,
98 fully transparent; to 255, fully opaque.
99 */
100 constexpr SkAlpha SK_AlphaOPAQUE = 0xFF;
101
102 /** Represents fully transparent SkColor. May be used to initialize a destination
103 containing a mask or a non-rectangular image.
104 */
105 constexpr SkColor SK_ColorTRANSPARENT = SkColorSetARGB(0x00, 0x00, 0x00, 0x00);
106
107 /** Represents fully opaque black.
108 */
109 constexpr SkColor SK_ColorBLACK = SkColorSetARGB(0xFF, 0x00, 0x00, 0x00);
110
111 /** Represents fully opaque dark gray.
112 Note that SVG dark gray is equivalent to 0xFFA9A9A9.
113 */
114 constexpr SkColor SK_ColorDKGRAY = SkColorSetARGB(0xFF, 0x44, 0x44, 0x44);
115
116 /** Represents fully opaque gray.
117 Note that HTML gray is equivalent to 0xFF808080.
118 */
119 constexpr SkColor SK_ColorGRAY = SkColorSetARGB(0xFF, 0x88, 0x88, 0x88);
120
121 /** Represents fully opaque light gray. HTML silver is equivalent to 0xFFC0C0C0.
122 Note that SVG light gray is equivalent to 0xFFD3D3D3.
123 */
124 constexpr SkColor SK_ColorLTGRAY = SkColorSetARGB(0xFF, 0xCC, 0xCC, 0xCC);
125
126 /** Represents fully opaque white.
127 */
128 constexpr SkColor SK_ColorWHITE = SkColorSetARGB(0xFF, 0xFF, 0xFF, 0xFF);
129
130 /** Represents fully opaque red.
131 */
132 constexpr SkColor SK_ColorRED = SkColorSetARGB(0xFF, 0xFF, 0x00, 0x00);
133
134 /** Represents fully opaque green. HTML lime is equivalent.
135 Note that HTML green is equivalent to 0xFF008000.
136 */
137 constexpr SkColor SK_ColorGREEN = SkColorSetARGB(0xFF, 0x00, 0xFF, 0x00);
138
139 /** Represents fully opaque blue.
140 */
141 constexpr SkColor SK_ColorBLUE = SkColorSetARGB(0xFF, 0x00, 0x00, 0xFF);
142
143 /** Represents fully opaque yellow.
144 */
145 constexpr SkColor SK_ColorYELLOW = SkColorSetARGB(0xFF, 0xFF, 0xFF, 0x00);
146
147 /** Represents fully opaque cyan. HTML aqua is equivalent.
148 */
149 constexpr SkColor SK_ColorCYAN = SkColorSetARGB(0xFF, 0x00, 0xFF, 0xFF);
150
151 /** Represents fully opaque magenta. HTML fuchsia is equivalent.
152 */
153 constexpr SkColor SK_ColorMAGENTA = SkColorSetARGB(0xFF, 0xFF, 0x00, 0xFF);
154
155 /** Converts RGB to its HSV components.
156 hsv[0] contains hsv hue, a value from zero to less than 360.
157 hsv[1] contains hsv saturation, a value from zero to one.
158 hsv[2] contains hsv value, a value from zero to one.
159
160 @param red red component value from zero to 255
161 @param green green component value from zero to 255
162 @param blue blue component value from zero to 255
163 @param hsv three element array which holds the resulting HSV components
164 */
165 SK_API void SkRGBToHSV(U8CPU red, U8CPU green, U8CPU blue, SkScalar hsv[3]);
166
167 /** Converts ARGB to its HSV components. Alpha in ARGB is ignored.
168 hsv[0] contains hsv hue, and is assigned a value from zero to less than 360.
169 hsv[1] contains hsv saturation, a value from zero to one.
170 hsv[2] contains hsv value, a value from zero to one.
171
172 @param color ARGB color to convert
173 @param hsv three element array which holds the resulting HSV components
174 */
SkColorToHSV(SkColor color,SkScalar hsv[3])175 static inline void SkColorToHSV(SkColor color, SkScalar hsv[3]) {
176 SkRGBToHSV(SkColorGetR(color), SkColorGetG(color), SkColorGetB(color), hsv);
177 }
178
179 /** Converts HSV components to an ARGB color. Alpha is passed through unchanged.
180 hsv[0] represents hsv hue, an angle from zero to less than 360.
181 hsv[1] represents hsv saturation, and varies from zero to one.
182 hsv[2] represents hsv value, and varies from zero to one.
183
184 Out of range hsv values are pinned.
185
186 @param alpha alpha component of the returned ARGB color
187 @param hsv three element array which holds the input HSV components
188 @return ARGB equivalent to HSV
189 */
190 SK_API SkColor SkHSVToColor(U8CPU alpha, const SkScalar hsv[3]);
191
192 /** Converts HSV components to an ARGB color. Alpha is set to 255.
193 hsv[0] represents hsv hue, an angle from zero to less than 360.
194 hsv[1] represents hsv saturation, and varies from zero to one.
195 hsv[2] represents hsv value, and varies from zero to one.
196
197 Out of range hsv values are pinned.
198
199 @param hsv three element array which holds the input HSV components
200 @return RGB equivalent to HSV
201 */
SkHSVToColor(const SkScalar hsv[3])202 static inline SkColor SkHSVToColor(const SkScalar hsv[3]) {
203 return SkHSVToColor(0xFF, hsv);
204 }
205
206 /** 32-bit ARGB color value, premultiplied. The byte order for this value is
207 configuration dependent, matching the format of kBGRA_8888_SkColorType bitmaps.
208 This is different from SkColor, which is unpremultiplied, and is always in the
209 same byte order.
210 */
211 typedef uint32_t SkPMColor;
212
213 /** Returns a SkPMColor value from unpremultiplied 8-bit component values.
214
215 @param a amount of alpha, from fully transparent (0) to fully opaque (255)
216 @param r amount of red, from no red (0) to full red (255)
217 @param g amount of green, from no green (0) to full green (255)
218 @param b amount of blue, from no blue (0) to full blue (255)
219 @return premultiplied color
220 */
221 SK_API SkPMColor SkPreMultiplyARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b);
222
223 /** Returns pmcolor closest to color c. Multiplies c RGB components by the c alpha,
224 and arranges the bytes to match the format of kN32_SkColorType.
225
226 @param c unpremultiplied ARGB color
227 @return premultiplied color
228 */
229 SK_API SkPMColor SkPreMultiplyColor(SkColor c);
230
231 /** \struct SkRGBA4f
232 RGBA color value, holding four floating point components. Color components are always in
233 a known order. kAT determines if the SkRGBA4f's R, G, and B components are premultiplied
234 by alpha or not.
235
236 Skia's public API always uses unpremultiplied colors, which can be stored as
237 SkRGBA4f<kUnpremul_SkAlphaType>. For convenience, this type can also be referred to
238 as SkColor4f.
239 */
240 template <SkAlphaType kAT>
241 struct SkRGBA4f {
242 float fR; //!< red component
243 float fG; //!< green component
244 float fB; //!< blue component
245 float fA; //!< alpha component
246
247 /** Compares SkRGBA4f with other, and returns true if all components are equal.
248
249 @param other SkRGBA4f to compare
250 @return true if SkRGBA4f equals other
251 */
252 bool operator==(const SkRGBA4f& other) const {
253 return fA == other.fA && fR == other.fR && fG == other.fG && fB == other.fB;
254 }
255
256 /** Compares SkRGBA4f with other, and returns true if not all components are equal.
257
258 @param other SkRGBA4f to compare
259 @return true if SkRGBA4f is not equal to other
260 */
261 bool operator!=(const SkRGBA4f& other) const {
262 return !(*this == other);
263 }
264
265 /** Returns SkRGBA4f multiplied by scale.
266
267 @param scale value to multiply by
268 @return SkRGBA4f as (fR * scale, fG * scale, fB * scale, fA * scale)
269 */
270 SkRGBA4f operator*(float scale) const {
271 return { fR * scale, fG * scale, fB * scale, fA * scale };
272 }
273
274 /** Returns SkRGBA4f multiplied component-wise by scale.
275
276 @param scale SkRGBA4f to multiply by
277 @return SkRGBA4f as (fR * scale.fR, fG * scale.fG, fB * scale.fB, fA * scale.fA)
278 */
279 SkRGBA4f operator*(const SkRGBA4f& scale) const {
280 return { fR * scale.fR, fG * scale.fG, fB * scale.fB, fA * scale.fA };
281 }
282
283 /** Returns a pointer to components of SkRGBA4f, for array access.
284
285 @return pointer to array [fR, fG, fB, fA]
286 */
vecSkRGBA4f287 const float* vec() const { return &fR; }
288
289 /** Returns a pointer to components of SkRGBA4f, for array access.
290
291 @return pointer to array [fR, fG, fB, fA]
292 */
vecSkRGBA4f293 float* vec() { return &fR; }
294
295 /** Returns one component. Asserts if index is out of range and SK_DEBUG is defined.
296
297 @param index one of: 0 (fR), 1 (fG), 2 (fB), 3 (fA)
298 @return value corresponding to index
299 */
300 float operator[](int index) const {
301 SkASSERT(index >= 0 && index < 4);
302 return this->vec()[index];
303 }
304
305 /** Returns one component. Asserts if index is out of range and SK_DEBUG is defined.
306
307 @param index one of: 0 (fR), 1 (fG), 2 (fB), 3 (fA)
308 @return value corresponding to index
309 */
310 float& operator[](int index) {
311 SkASSERT(index >= 0 && index < 4);
312 return this->vec()[index];
313 }
314
315 /** Returns true if SkRGBA4f is an opaque color. Asserts if fA is out of range and
316 SK_DEBUG is defined.
317
318 @return true if SkRGBA4f is opaque
319 */
isOpaqueSkRGBA4f320 bool isOpaque() const {
321 SkASSERT(fA <= 1.0f && fA >= 0.0f);
322 return fA == 1.0f;
323 }
324
325 /** Returns true if all channels are in [0, 1]. */
fitsInBytesSkRGBA4f326 bool fitsInBytes() const {
327 SkASSERT(fA >= 0.0f && fA <= 1.0f);
328 return fR >= 0.0f && fR <= 1.0f &&
329 fG >= 0.0f && fG <= 1.0f &&
330 fB >= 0.0f && fB <= 1.0f;
331 }
332
333 /** Returns closest SkRGBA4f to SkColor. Only allowed if SkRGBA4f is unpremultiplied.
334
335 @param color Color with Alpha, red, blue, and green components
336 @return SkColor as SkRGBA4f
337 */
338 static SkRGBA4f FromColor(SkColor color); // impl. depends on kAT
339
340 /** Returns closest SkColor to SkRGBA4f. Only allowed if SkRGBA4f is unpremultiplied.
341
342 @return color as SkColor
343 */
344 SkColor toSkColor() const; // impl. depends on kAT
345
346 /** Returns closest SkRGBA4f to SkPMColor. Only allowed if SkRGBA4f is premultiplied.
347
348 @return SkPMColor as SkRGBA4f
349 */
350 static SkRGBA4f FromPMColor(SkPMColor); // impl. depends on kAT
351
352 /** Returns SkRGBA4f premultiplied by alpha. Asserts at compile time if SkRGBA4f is
353 already premultiplied.
354
355 @return premultiplied color
356 */
premulSkRGBA4f357 SkRGBA4f<kPremul_SkAlphaType> premul() const {
358 static_assert(kAT == kUnpremul_SkAlphaType, "");
359 return { fR * fA, fG * fA, fB * fA, fA };
360 }
361
362 /** Returns SkRGBA4f unpremultiplied by alpha. Asserts at compile time if SkRGBA4f is
363 already unpremultiplied.
364
365 @return unpremultiplied color
366 */
unpremulSkRGBA4f367 SkRGBA4f<kUnpremul_SkAlphaType> unpremul() const {
368 static_assert(kAT == kPremul_SkAlphaType, "");
369
370 if (fA == 0.0f) {
371 return { 0, 0, 0, 0 };
372 } else {
373 float invAlpha = 1 / fA;
374 return { fR * invAlpha, fG * invAlpha, fB * invAlpha, fA };
375 }
376 }
377
378 // This produces bytes in RGBA order (eg GrColor). Impl. is the same, regardless of kAT
379 uint32_t toBytes_RGBA() const;
380 static SkRGBA4f FromBytes_RGBA(uint32_t color);
381
makeOpaqueSkRGBA4f382 SkRGBA4f makeOpaque() const {
383 return { fR, fG, fB, 1.0f };
384 }
385 };
386
387 /** \struct SkColor4f
388 RGBA color value, holding four floating point components. Color components are always in
389 a known order, and are unpremultiplied.
390
391 This is a specialization of SkRGBA4f. For details, @see SkRGBA4f.
392 */
393 using SkColor4f = SkRGBA4f<kUnpremul_SkAlphaType>;
394
395 template <> SK_API SkColor4f SkColor4f::FromColor(SkColor);
396 template <> SK_API SkColor SkColor4f::toSkColor() const;
397
398 #endif
399