4 * An OpenGL based 'interactive canvas' library.
6 * Authored By Matthew Allum <mallum@openedhand.com>
8 * Copyright (C) 2006 OpenedHand
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
25 * SECTION:clutter-color
26 * @short_description: Color management and manipulation.
28 * #ClutterColor is a simple type for representing colors in Clutter.
30 * A #ClutterColor is expressed as a 4-tuple of values ranging from
31 * zero to 255, one for each color channel plus one for the alpha.
33 * The alpha channel is fully opaque at 255 and fully transparent at 0.
42 #include <pango/pango-attributes.h>
44 #include "clutter-main.h"
45 #include "clutter-color.h"
46 #include "clutter-private.h"
47 #include "clutter-debug.h"
53 * @result: (out caller-allocates): return location for the result
55 * Adds @a to @b and saves the resulting color inside @result.
57 * The alpha channel of @result is set as as the maximum value
58 * between the alpha channels of @a and @b.
61 clutter_color_add (const ClutterColor *a,
62 const ClutterColor *b,
65 g_return_if_fail (a != NULL);
66 g_return_if_fail (b != NULL);
67 g_return_if_fail (result != NULL);
69 result->red = CLAMP (a->red + b->red, 0, 255);
70 result->green = CLAMP (a->green + b->green, 0, 255);
71 result->blue = CLAMP (a->blue + b->blue, 0, 255);
73 result->alpha = MAX (a->alpha, b->alpha);
77 * clutter_color_subtract:
80 * @result: (out caller-allocates): return location for the result
82 * Subtracts @b from @a and saves the resulting color inside @result.
84 * This function assumes that the components of @a are greater than the
85 * components of @b; the result is, otherwise, undefined.
87 * The alpha channel of @result is set as the minimum value
88 * between the alpha channels of @a and @b.
91 clutter_color_subtract (const ClutterColor *a,
92 const ClutterColor *b,
95 g_return_if_fail (a != NULL);
96 g_return_if_fail (b != NULL);
97 g_return_if_fail (result != NULL);
99 result->red = CLAMP (a->red - b->red, 0, 255);
100 result->green = CLAMP (a->green - b->green, 0, 255);
101 result->blue = CLAMP (a->blue - b->blue, 0, 255);
103 result->alpha = MIN (a->alpha, b->alpha);
107 * clutter_color_lighten:
108 * @color: a #ClutterColor
109 * @result: (out caller-allocates): return location for the lighter color
111 * Lightens @color by a fixed amount, and saves the changed color
115 clutter_color_lighten (const ClutterColor *color,
116 ClutterColor *result)
118 clutter_color_shade (color, 1.3, result);
122 * clutter_color_darken:
123 * @color: a #ClutterColor
124 * @result: (out caller-allocates): return location for the darker color
126 * Darkens @color by a fixed amount, and saves the changed color
130 clutter_color_darken (const ClutterColor *color,
131 ClutterColor *result)
133 clutter_color_shade (color, 0.7, result);
137 * clutter_color_to_hls:
138 * @color: a #ClutterColor
139 * @hue: (out): return location for the hue value or %NULL
140 * @luminance: (out): return location for the luminance value or %NULL
141 * @saturation: (out): return location for the saturation value or %NULL
143 * Converts @color to the HLS format.
145 * The @hue value is in the 0 .. 360 range. The @luminance and
146 * @saturation values are in the 0 .. 1 range.
149 clutter_color_to_hls (const ClutterColor *color,
154 float red, green, blue;
155 float min, max, delta;
158 g_return_if_fail (color != NULL);
160 red = color->red / 255.0;
161 green = color->green / 255.0;
162 blue = color->blue / 255.0;
196 s = (max - min) / (max + min);
198 s = (max - min) / (2.0 - max - min);
203 h = (green - blue) / delta;
204 else if (green == max)
205 h = 2.0 + (blue - red) / delta;
206 else if (blue == max)
207 h = 4.0 + (red - green) / delta;
226 * clutter_color_from_hls:
227 * @color: (out): return location for a #ClutterColor
228 * @hue: hue value, in the 0 .. 360 range
229 * @luminance: luminance value, in the 0 .. 1 range
230 * @saturation: saturation value, in the 0 .. 1 range
232 * Converts a color expressed in HLS (hue, luminance and saturation)
233 * values into a #ClutterColor.
236 clutter_color_from_hls (ClutterColor *color,
250 color->red = color->green = color->blue = (luminance * 255);
255 if (luminance <= 0.5)
256 tmp2 = luminance * (1.0 + saturation);
258 tmp2 = luminance + saturation - (luminance * saturation);
260 tmp1 = 2.0 * luminance - tmp2;
262 tmp3[0] = hue + 1.0 / 3.0;
264 tmp3[2] = hue - 1.0 / 3.0;
266 for (i = 0; i < 3; i++)
274 if (6.0 * tmp3[i] < 1.0)
275 clr[i] = tmp1 + (tmp2 - tmp1) * tmp3[i] * 6.0;
276 else if (2.0 * tmp3[i] < 1.0)
278 else if (3.0 * tmp3[i] < 2.0)
279 clr[i] = (tmp1 + (tmp2 - tmp1) * ((2.0 / 3.0) - tmp3[i]) * 6.0);
284 color->red = floorf (clr[0] * 255.0 + 0.5);
285 color->green = floorf (clr[1] * 255.0 + 0.5);
286 color->blue = floorf (clr[2] * 255.0 + 0.5);
290 * clutter_color_shade:
291 * @color: a #ClutterColor
292 * @factor: the shade factor to apply
293 * @result: (out caller-allocates): return location for the shaded color
295 * Shades @color by @factor and saves the modified color into @result.
298 clutter_color_shade (const ClutterColor *color,
300 ClutterColor *result)
304 g_return_if_fail (color != NULL);
305 g_return_if_fail (result != NULL);
307 clutter_color_to_hls (color, &h, &l, &s);
321 clutter_color_from_hls (result, h, l, s);
323 result->alpha = color->alpha;
327 * clutter_color_to_pixel:
328 * @color: a #ClutterColor
330 * Converts @color into a packed 32 bit integer, containing
331 * all the four 8 bit channels used by #ClutterColor.
333 * Return value: a packed color
336 clutter_color_to_pixel (const ClutterColor *color)
338 g_return_val_if_fail (color != NULL, 0);
340 return (color->alpha |
347 * clutter_color_from_pixel:
348 * @color: (out caller-allocates): return location for a #ClutterColor
349 * @pixel: a 32 bit packed integer containing a color
351 * Converts @pixel from the packed representation of a four 8 bit channel
352 * color to a #ClutterColor.
355 clutter_color_from_pixel (ClutterColor *color,
358 g_return_if_fail (color != NULL);
360 color->red = pixel >> 24;
361 color->green = (pixel >> 16) & 0xff;
362 color->blue = (pixel >> 8) & 0xff;
363 color->alpha = pixel & 0xff;
367 * clutter_color_from_string:
368 * @color: (out caller-allocates): return location for a #ClutterColor
369 * @str: a string specifiying a color (named color or #RRGGBBAA)
371 * Parses a string definition of a color, filling the
372 * <structfield>red</structfield>, <structfield>green</structfield>,
373 * <structfield>blue</structfield> and <structfield>alpha</structfield>
374 * channels of @color. If alpha is not specified it will be set full opaque.
376 * The @color is not allocated.
378 * The color may be defined by any of the formats understood by
379 * pango_color_from_string(); these include literal color names, like
380 * <literal>Red</literal> or <literal>DarkSlateGray</literal>, or
381 * hexadecimal specifications like <literal>#3050b2</literal> or
382 * <literal>#333</literal>.
384 * Return value: %TRUE if parsing succeeded.
389 clutter_color_from_string (ClutterColor *color,
392 PangoColor pango_color = { 0, };
394 g_return_val_if_fail (color != NULL, FALSE);
395 g_return_val_if_fail (str != NULL, FALSE);
397 /* if the string contains a color encoded using the hexadecimal
398 * notations (#rrggbbaa or #rgba) we attempt a rough pass at
399 * parsing the color ourselves, as we need the alpha channel that
400 * Pango can't retrieve.
406 if (sscanf (str + 1, "%x", &result))
408 gsize length = strlen (str);
412 case 9: /* rrggbbaa */
413 color->red = (result >> 24) & 0xff;
414 color->green = (result >> 16) & 0xff;
415 color->blue = (result >> 8) & 0xff;
417 color->alpha = result & 0xff;
421 case 7: /* #rrggbb */
422 color->red = (result >> 16) & 0xff;
423 color->green = (result >> 8) & 0xff;
424 color->blue = result & 0xff;
431 color->red = ((result >> 12) & 0xf);
432 color->green = ((result >> 8) & 0xf);
433 color->blue = ((result >> 4) & 0xf);
434 color->alpha = result & 0xf;
436 color->red = (color->red << 4) | color->red;
437 color->green = (color->green << 4) | color->green;
438 color->blue = (color->blue << 4) | color->blue;
439 color->alpha = (color->alpha << 4) | color->alpha;
444 color->red = ((result >> 8) & 0xf);
445 color->green = ((result >> 4) & 0xf);
446 color->blue = result & 0xf;
448 color->red = (color->red << 4) | color->red;
449 color->green = (color->green << 4) | color->green;
450 color->blue = (color->blue << 4) | color->blue;
457 /* pass through to Pango */
463 /* Fall back to pango for named colors */
464 if (pango_color_parse (&pango_color, str))
466 color->red = pango_color.red;
467 color->green = pango_color.green;
468 color->blue = pango_color.blue;
479 * clutter_color_to_string:
480 * @color: a #ClutterColor
482 * Returns a textual specification of @color in the hexadecimal form
483 * <literal>#rrggbbaa</literal>, where <literal>r</literal>,
484 * <literal>g</literal>, <literal>b</literal> and <literal>a</literal> are
485 * hex digits representing the red, green, blue and alpha components
488 * Return value: (transfer full): a newly-allocated text string
493 clutter_color_to_string (const ClutterColor *color)
495 g_return_val_if_fail (color != NULL, NULL);
497 return g_strdup_printf ("#%02x%02x%02x%02x",
505 * clutter_color_equal:
506 * @v1: a #ClutterColor
507 * @v2: a #ClutterColor
509 * Compares two #ClutterColor<!-- -->s and checks if they are the same.
511 * This function can be passed to g_hash_table_new() as the @key_equal_func
512 * parameter, when using #ClutterColor<!-- -->s as keys in a #GHashTable.
514 * Return value: %TRUE if the two colors are the same.
519 clutter_color_equal (gconstpointer v1,
522 const ClutterColor *a, *b;
524 g_return_val_if_fail (v1 != NULL, FALSE);
525 g_return_val_if_fail (v2 != NULL, FALSE);
533 return (a->red == b->red &&
534 a->green == b->green &&
535 a->blue == b->blue &&
536 a->alpha == b->alpha);
540 * clutter_color_hash:
541 * @v: a #ClutterColor
543 * Converts a #ClutterColor to a hash value.
545 * This function can be passed to g_hash_table_new() as the @hash_func
546 * parameter, when using #ClutterColor<!-- -->s as keys in a #GHashTable.
548 * Return value: a hash value corresponding to the color
553 clutter_color_hash (gconstpointer v)
555 return clutter_color_to_pixel ((const ClutterColor *) v);
559 * clutter_color_copy:
560 * @color: a #ClutterColor
562 * Makes a copy of the color structure. The result must be
563 * freed using clutter_color_free().
565 * Return value: (transfer full): an allocated copy of @color.
570 clutter_color_copy (const ClutterColor *color)
572 if (G_LIKELY (color != NULL))
573 return g_slice_dup (ClutterColor, color);
579 * clutter_color_free:
580 * @color: a #ClutterColor
582 * Frees a color structure created with clutter_color_copy().
587 clutter_color_free (ClutterColor *color)
589 if (G_LIKELY (color != NULL))
590 g_slice_free (ClutterColor, color);
595 * @red: red component of the color, between 0 and 255
596 * @green: green component of the color, between 0 and 255
597 * @blue: blue component of the color, between 0 and 255
598 * @alpha: alpha component of the color, between 0 and 255
600 * Creates a new #ClutterColor with the given values.
602 * Return value: (transfer full): the newly allocated color.
603 * Use clutter_color_free() when done
608 clutter_color_new (guint8 red,
615 color = g_slice_new (ClutterColor);
618 color->green = green;
620 color->alpha = alpha;
626 clutter_value_transform_color_string (const GValue *src,
629 const ClutterColor *color = g_value_get_boxed (src);
633 gchar *string = clutter_color_to_string (color);
635 g_value_take_string (dest, string);
638 g_value_set_string (dest, NULL);
642 clutter_value_transform_string_color (const GValue *src,
645 const char *str = g_value_get_string (src);
649 ClutterColor color = { 0, };
651 clutter_color_from_string (&color, str);
653 clutter_value_set_color (dest, &color);
656 clutter_value_set_color (dest, NULL);
660 clutter_color_get_type (void)
662 static GType _clutter_color_type = 0;
664 if (G_UNLIKELY (_clutter_color_type == 0))
666 _clutter_color_type =
667 g_boxed_type_register_static (I_("ClutterColor"),
668 (GBoxedCopyFunc) clutter_color_copy,
669 (GBoxedFreeFunc) clutter_color_free);
671 g_value_register_transform_func (_clutter_color_type, G_TYPE_STRING,
672 clutter_value_transform_color_string);
673 g_value_register_transform_func (G_TYPE_STRING, _clutter_color_type,
674 clutter_value_transform_string_color);
677 return _clutter_color_type;
681 * clutter_value_set_color:
682 * @value: a #GValue initialized to #CLUTTER_TYPE_COLOR
683 * @color: the color to set
685 * Sets @value to @color.
690 clutter_value_set_color (GValue *value,
691 const ClutterColor *color)
693 g_return_if_fail (CLUTTER_VALUE_HOLDS_COLOR (value));
695 g_value_set_boxed (value, color);
699 * clutter_value_get_color:
700 * @value: a #GValue initialized to #CLUTTER_TYPE_COLOR
702 * Gets the #ClutterColor contained in @value.
704 * Return value: (transfer none): the color inside the passed #GValue
708 G_CONST_RETURN ClutterColor *
709 clutter_value_get_color (const GValue *value)
711 g_return_val_if_fail (CLUTTER_VALUE_HOLDS_COLOR (value), NULL);
713 return g_value_get_boxed (value);
717 param_color_init (GParamSpec *pspec)
719 ClutterParamSpecColor *cspec = CLUTTER_PARAM_SPEC_COLOR (pspec);
721 cspec->default_value = NULL;
725 param_color_finalize (GParamSpec *pspec)
727 ClutterParamSpecColor *cspec = CLUTTER_PARAM_SPEC_COLOR (pspec);
729 clutter_color_free (cspec->default_value);
733 param_color_set_default (GParamSpec *pspec,
736 const ClutterColor *default_value =
737 CLUTTER_PARAM_SPEC_COLOR (pspec)->default_value;
738 clutter_value_set_color (value, default_value);
742 param_color_values_cmp (GParamSpec *pspec,
743 const GValue *value1,
744 const GValue *value2)
746 const ClutterColor *color1 = g_value_get_boxed (value1);
747 const ClutterColor *color2 = g_value_get_boxed (value2);
751 return color2 == NULL ? 0 : -1;
753 pixel1 = clutter_color_to_pixel (color1);
754 pixel2 = clutter_color_to_pixel (color2);
758 else if (pixel1 == pixel2)
765 clutter_param_color_get_type (void)
767 static GType pspec_type = 0;
769 if (G_UNLIKELY (pspec_type == 0))
771 const GParamSpecTypeInfo pspec_info = {
772 sizeof (ClutterParamSpecColor),
776 param_color_finalize,
777 param_color_set_default,
779 param_color_values_cmp,
782 pspec_type = g_param_type_register_static (I_("ClutterParamSpecColor"),
790 * clutter_param_spec_color: (skip)
791 * @name: name of the property
793 * @blurb: description (can be translatable)
794 * @default_value: default value
795 * @flags: flags for the param spec
797 * Creates a #GParamSpec for properties using #ClutterColor.
799 * Return value: the newly created #GParamSpec
804 clutter_param_spec_color (const gchar *name,
807 const ClutterColor *default_value,
810 ClutterParamSpecColor *cspec;
812 cspec = g_param_spec_internal (CLUTTER_TYPE_PARAM_COLOR,
813 name, nick, blurb, flags);
815 cspec->default_value = clutter_color_copy (default_value);
817 return G_PARAM_SPEC (cspec);