## Colors

Colors — Color management and manipulation.

## Synopsis

                        ClutterColor;
    ClutterColor *      clutter_color_new                   (guint8 red,
                                                             guint8 green,
                                                             guint8 blue,
                                                             guint8 alpha);
    ClutterColor *      clutter_color_copy                  (const ClutterColor *color);
    void                clutter_color_free                  (ClutterColor *color);
    gboolean            clutter_color_equal                 (gconstpointer v1,
                                                             gconstpointer v2);
    guint               clutter_color_hash                  (gconstpointer v);
    enum                ClutterStaticColor;
    const ClutterColor * clutter_color_get_static           (ClutterStaticColor color);

    gboolean            clutter_color_from_string           (ClutterColor *color,
                                                             const gchar *str);
    gchar *             clutter_color_to_string             (const ClutterColor *color);
    void                clutter_color_from_hls              (ClutterColor *color,
                                                             gfloat hue,
                                                             gfloat luminance,
                                                             gfloat saturation);
    void                clutter_color_to_hls                (const ClutterColor *color,
                                                             gfloat *hue,
                                                             gfloat *luminance,
                                                             gfloat *saturation);
    void                clutter_color_from_pixel            (ClutterColor *color,
                                                             guint32 pixel);
    guint32             clutter_color_to_pixel              (const ClutterColor *color);

    void                clutter_color_add                   (const ClutterColor *a,
                                                             const ClutterColor *b,
                                                             ClutterColor *result);
    void                clutter_color_subtract              (const ClutterColor *a,
                                                             const ClutterColor *b,
                                                             ClutterColor *result);
    void                clutter_color_lighten               (const ClutterColor *color,
                                                             ClutterColor *result);
    void                clutter_color_darken                (const ClutterColor *color,
                                                             ClutterColor *result);
    void                clutter_color_shade                 (const ClutterColor *color,
                                                             gdouble factor,
                                                             ClutterColor *result);
    void                clutter_color_interpolate           (const ClutterColor *initial,
                                                             const ClutterColor *final,
                                                             gdouble progress,
                                                             ClutterColor *result);

    struct              ClutterParamSpecColor;
    GParamSpec *        clutter_param_spec_color            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             const ClutterColor *default_value,
                                                             GParamFlags flags);
    #define             CLUTTER_VALUE_HOLDS_COLOR           (x)
    void                clutter_value_set_color             (GValue *value,
                                                             const ClutterColor *color);
    const ClutterColor * clutter_value_get_color            (const GValue *value);

## Description

ClutterColor is a simple type for representing colors in Clutter.

A ClutterColor is expressed as a 4-tuple of values ranging from zero to 255, one for each color channel plus one for the alpha.

The alpha channel is fully opaque at 255 and fully transparent at 0.

## Details

### ClutterColor

    typedef struct {
      guint8 red;
      guint8 green;
      guint8 blue;

      guint8 alpha;
    } ClutterColor;

Color representation.

guint8 `red`; | red component, between 0 and 255
guint8 `green`; | green component, between 0 and 255
guint8 `blue`; | blue component, between 0 and 255
guint8 `alpha`; | alpha component, between 0 and 255

### clutter_color_new ()

    ClutterColor *      clutter_color_new                   (guint8 red,
                                                             guint8 green,
                                                             guint8 blue,
                                                             guint8 alpha);

Creates a new ClutterColor with the given values.

`red` : | red component of the color, between 0 and 255
`green` : | green component of the color, between 0 and 255
`blue` : | blue component of the color, between 0 and 255
`alpha` : | alpha component of the color, between 0 and 255
Returns : | the newly allocated color. Use `clutter_color_free()` when done. [transfer full]

Since 0.8.4

### clutter_color_copy ()

    ClutterColor *      clutter_color_copy                  (const ClutterColor *color);

Makes a copy of the color structure. The result must be freed using `clutter_color_free()`.

`color` : | a ClutterColor
Returns : | an allocated copy of `color`. [transfer full]

Since 0.2

### clutter_color_free ()

    void                clutter_color_free                  (ClutterColor *color);

Frees a color structure created with `clutter_color_copy()`.

`color` : | a ClutterColor

Since 0.2

### clutter_color_equal ()

    gboolean            clutter_color_equal                 (gconstpointer v1,
                                                             gconstpointer v2);

Compares two ClutterColors and checks if they are the same.

This function can be passed to `g_hash_table_new()` as the `key_equal_func` parameter, when using ClutterColors as keys in a GHashTable.

`v1` : | a ClutterColor
`v2` : | a ClutterColor
Returns : | `TRUE` if the two colors are the same.

Since 0.2

### clutter_color_hash ()

    guint               clutter_color_hash                  (gconstpointer v);

Converts a ClutterColor to a hash value.

This function can be passed to `g_hash_table_new()` as the `hash_func` parameter, when using ClutterColors as keys in a GHashTable.

`v` : | a ClutterColor
Returns : | a hash value corresponding to the color

Since 1.0

### enum ClutterStaticColor

    typedef enum {
     /*< prefix=CLUTTER_COLOR >*/
      /* CGA/EGA-like palette */
      CLUTTER_COLOR_WHITE           = 0,
      CLUTTER_COLOR_BLACK,
      CLUTTER_COLOR_RED,
      CLUTTER_COLOR_DARK_RED,
      CLUTTER_COLOR_GREEN,
      CLUTTER_COLOR_DARK_GREEN,
      CLUTTER_COLOR_BLUE,
      CLUTTER_COLOR_DARK_BLUE,
      CLUTTER_COLOR_CYAN,
      CLUTTER_COLOR_DARK_CYAN,
      CLUTTER_COLOR_MAGENTA,
      CLUTTER_COLOR_DARK_MAGENTA,
      CLUTTER_COLOR_YELLOW,
      CLUTTER_COLOR_DARK_YELLOW,
      CLUTTER_COLOR_GRAY,
      CLUTTER_COLOR_DARK_GRAY,
      CLUTTER_COLOR_LIGHT_GRAY,

      /* Tango icon palette */
      CLUTTER_COLOR_BUTTER,
      CLUTTER_COLOR_BUTTER_LIGHT,
      CLUTTER_COLOR_BUTTER_DARK,
      CLUTTER_COLOR_ORANGE,
      CLUTTER_COLOR_ORANGE_LIGHT,
      CLUTTER_COLOR_ORANGE_DARK,
      CLUTTER_COLOR_CHOCOLATE,
      CLUTTER_COLOR_CHOCOLATE_LIGHT,
      CLUTTER_COLOR_CHOCOLATE_DARK,
      CLUTTER_COLOR_CHAMELEON,
      CLUTTER_COLOR_CHAMELEON_LIGHT,
      CLUTTER_COLOR_CHAMELEON_DARK,
      CLUTTER_COLOR_SKY_BLUE,
      CLUTTER_COLOR_SKY_BLUE_LIGHT,
      CLUTTER_COLOR_SKY_BLUE_DARK,
      CLUTTER_COLOR_PLUM,
      CLUTTER_COLOR_PLUM_LIGHT,
      CLUTTER_COLOR_PLUM_DARK,
      CLUTTER_COLOR_SCARLET_RED,
      CLUTTER_COLOR_SCARLET_RED_LIGHT,
      CLUTTER_COLOR_SCARLET_RED_DARK,
      CLUTTER_COLOR_ALUMINIUM_1,
      CLUTTER_COLOR_ALUMINIUM_2,
      CLUTTER_COLOR_ALUMINIUM_3,
      CLUTTER_COLOR_ALUMINIUM_4,
      CLUTTER_COLOR_ALUMINIUM_5,
      CLUTTER_COLOR_ALUMINIUM_6,

      /* Fully transparent black */
      CLUTTER_COLOR_TRANSPARENT
    } ClutterStaticColor;

Named colors, for accessing global colors defined by Clutter

`CLUTTER_COLOR_WHITE` | White color (ffffffff)
`CLUTTER_COLOR_BLACK` | Black color (000000ff)
`CLUTTER_COLOR_RED` | Red color (ff0000ff)
`CLUTTER_COLOR_DARK_RED` | Dark red color (800000ff)
`CLUTTER_COLOR_GREEN` | Green color (00ff00ff)
`CLUTTER_COLOR_DARK_GREEN` | Dark green color (008000ff)
`CLUTTER_COLOR_BLUE` | Blue color (0000ffff)
`CLUTTER_COLOR_DARK_BLUE` | Dark blue color (000080ff)
`CLUTTER_COLOR_CYAN` | Cyan color (00ffffff)
`CLUTTER_COLOR_DARK_CYAN` | Dark cyan color (008080ff)
`CLUTTER_COLOR_MAGENTA` | Magenta color (ff00ffff)
`CLUTTER_COLOR_DARK_MAGENTA` | Dark magenta color (800080ff)
`CLUTTER_COLOR_YELLOW` | Yellow color (ffff00ff)
`CLUTTER_COLOR_DARK_YELLOW` | Dark yellow color (808000ff)
`CLUTTER_COLOR_GRAY` | Gray color (a0a0a4ff)
`CLUTTER_COLOR_DARK_GRAY` | Dark Gray color (808080ff)
`CLUTTER_COLOR_LIGHT_GRAY` | Light gray color (c0c0c0ff)
`CLUTTER_COLOR_BUTTER` | Butter color (edd400ff)
`CLUTTER_COLOR_BUTTER_LIGHT` | Light butter color (fce94fff)
`CLUTTER_COLOR_BUTTER_DARK` | Dark butter color (c4a000ff)
`CLUTTER_COLOR_ORANGE` | Orange color (f57900ff)
`CLUTTER_COLOR_ORANGE_LIGHT` | Light orange color (fcaf3fff)
`CLUTTER_COLOR_ORANGE_DARK` | Dark orange color (ce5c00ff)
`CLUTTER_COLOR_CHOCOLATE` | Chocolate color (c17d11ff)
`CLUTTER_COLOR_CHOCOLATE_LIGHT` | Light chocolate color (e9b96eff)
`CLUTTER_COLOR_CHOCOLATE_DARK` | Dark chocolate color (8f5902ff)
`CLUTTER_COLOR_CHAMELEON` | Chameleon color (73d216ff)
`CLUTTER_COLOR_CHAMELEON_LIGHT` | Light chameleon color (8ae234ff)
`CLUTTER_COLOR_CHAMELEON_DARK` | Dark chameleon color (4e9a06ff)
`CLUTTER_COLOR_SKY_BLUE` | Sky color (3465a4ff)
`CLUTTER_COLOR_SKY_BLUE_LIGHT` | Light sky color (729fcfff)
`CLUTTER_COLOR_SKY_BLUE_DARK` | Dark sky color (204a87ff)
`CLUTTER_COLOR_PLUM` | Plum color (75507bff)
`CLUTTER_COLOR_PLUM_LIGHT` | Light plum color (ad7fa8ff)
`CLUTTER_COLOR_PLUM_DARK` | Dark plum color (5c3566ff)
`CLUTTER_COLOR_SCARLET_RED` | Scarlet red color (cc0000ff)
`CLUTTER_COLOR_SCARLET_RED_LIGHT` | Light scarlet red color (ef2929ff)
`CLUTTER_COLOR_SCARLET_RED_DARK` | Dark scarlet red color (a40000ff)
`CLUTTER_COLOR_ALUMINIUM_1` | Aluminium, first variant (eeeeecff)
`CLUTTER_COLOR_ALUMINIUM_2` | Aluminium, second variant (d3d7cfff)
`CLUTTER_COLOR_ALUMINIUM_3` | Aluminium, third variant (babdb6ff)
`CLUTTER_COLOR_ALUMINIUM_4` | Aluminium, fourth variant (888a85ff)
`CLUTTER_COLOR_ALUMINIUM_5` | Aluminium, fifth variant (555753ff)
`CLUTTER_COLOR_ALUMINIUM_6` | Aluminium, sixth variant (2e3436ff)
`CLUTTER_COLOR_TRANSPARENT` | Transparent color (00000000)

Since 1.6

### clutter_color_get_static ()

    const ClutterColor * clutter_color_get_static           (ClutterStaticColor color);

Retrieves a static color for the given `color` name

Static colors are created by Clutter and are guaranteed to always be available and valid

`color` : | the named global color
Returns : | a pointer to a static color; the returned pointer is owned by Clutter and it should never be modified or freed

Since 1.6

### clutter_color_from_string ()

    gboolean            clutter_color_from_string           (ClutterColor *color,
                                                             const gchar *str);

Parses a string definition of a color, filling the `red`, `green`, `blue` and `alpha` channels of `color`.

The `color` is not allocated.

The format of `str` can be either one of:

- a standard name (as taken from the X11 rgb.txt file)

- an hexadecimal value in the form: `#rgb`, `#rrggbb`, `#rgba` or `#rrggbbaa`

- a RGB color in the form: `rgb(r, g, b)`

- a RGB color in the form: `rgba(r, g, b, a)`

- a HSL color in the form: `hsl(h, s, l)`

- a HSL color in the form: `hsla(h, s, l, a)`

where 'r', 'g', 'b' and 'a' are (respectively) the red, green, blue color intensities and the opacity. The 'h', 's' and 'l' are (respectively) the hue, saturation and luminance values.

In the `rgb()` and `rgba()` formats, the 'r', 'g', and 'b' values are either integers between 0 and 255, or percentage values in the range between 0% and 100%; the percentages require the '%' character. The 'a' value, if specified, can only be a floating point value between 0.0 and 1.0.

In the `hls()` and `hlsa()` formats, the 'h' value (hue) it's an angle between 0 and 360.0 degrees; the 'l' and 's' values (luminance and saturation) are a floating point value between 0.0 and 1.0. The 'a' value, if specified, can only be a floating point value between 0.0 and 1.0.

Whitespace inside the definitions is ignored; no leading whitespace is allowed.

If the alpha component is not specified then it is assumed to be set to be fully opaque.

`color` : | return location for a ClutterColor. [out caller-allocates]
`str` : | a string specifiying a color
Returns : | `TRUE` if parsing succeeded, and `FALSE` otherwise

Since 1.0

### clutter_color_to_string ()

    gchar *             clutter_color_to_string             (const ClutterColor *color);

Returns a textual specification of `color` in the hexadecimal form `#rrggbbaa`, where `r`, `g`, `b` and `a` are hexadecimal digits representing the red, green, blue and alpha components respectively.

`color` : | a ClutterColor
Returns : | a newly-allocated text string. [transfer full]

Since 0.2

### clutter_color_from_hls ()

    void                clutter_color_from_hls              (ClutterColor *color,
                                                             gfloat hue,
                                                             gfloat luminance,
                                                             gfloat saturation);

Converts a color expressed in HLS (hue, luminance and saturation) values into a ClutterColor.

`color` : | return location for a ClutterColor. [out]
`hue` : | hue value, in the 0 .. 360 range
`luminance` : | luminance value, in the 0 .. 1 range
`saturation` : | saturation value, in the 0 .. 1 range

### clutter_color_to_hls ()

    void                clutter_color_to_hls                (const ClutterColor *color,
                                                             gfloat *hue,
                                                             gfloat *luminance,
                                                             gfloat *saturation);

Converts `color` to the HLS format.

The `hue` value is in the 0 .. 360 range. The `luminance` and `saturation` values are in the 0 .. 1 range.

`color` : | a ClutterColor
`hue` : | return location for the hue value or `NULL`. [out]
`luminance` : | return location for the luminance value or `NULL`. [out]
`saturation` : | return location for the saturation value or `NULL`. [out]

### clutter_color_from_pixel ()

    void                clutter_color_from_pixel            (ClutterColor *color,
                                                             guint32 pixel);

Converts `pixel` from the packed representation of a four 8 bit channel color to a ClutterColor.

`color` : | return location for a ClutterColor. [out caller-allocates]
`pixel` : | a 32 bit packed integer containing a color

### clutter_color_to_pixel ()

    guint32             clutter_color_to_pixel              (const ClutterColor *color);

Converts `color` into a packed 32 bit integer, containing all the four 8 bit channels used by ClutterColor.

`color` : | a ClutterColor
Returns : | a packed color

### clutter_color_add ()

    void                clutter_color_add                   (const ClutterColor *a,
                                                             const ClutterColor *b,
                                                             ClutterColor *result);

Adds `a` to `b` and saves the resulting color inside `result`.

The alpha channel of `result` is set as as the maximum value between the alpha channels of `a` and `b`.

`a` : | a ClutterColor
`b` : | a ClutterColor
`result` : | return location for the result. [out caller-allocates]

### clutter_color_subtract ()

    void                clutter_color_subtract              (const ClutterColor *a,
                                                             const ClutterColor *b,
                                                             ClutterColor *result);

Subtracts `b` from `a` and saves the resulting color inside `result`.

This function assumes that the components of `a` are greater than the components of `b`; the result is, otherwise, undefined.

The alpha channel of `result` is set as the minimum value between the alpha channels of `a` and `b`.

`a` : | a ClutterColor
`b` : | a ClutterColor
`result` : | return location for the result. [out caller-allocates]

### clutter_color_lighten ()

    void                clutter_color_lighten               (const ClutterColor *color,
                                                             ClutterColor *result);

Lightens `color` by a fixed amount, and saves the changed color in `result`.

`color` : | a ClutterColor
`result` : | return location for the lighter color. [out caller-allocates]

### clutter_color_darken ()

    void                clutter_color_darken                (const ClutterColor *color,
                                                             ClutterColor *result);

Darkens `color` by a fixed amount, and saves the changed color in `result`.

`color` : | a ClutterColor
`result` : | return location for the darker color. [out caller-allocates]

### clutter_color_shade ()

    void                clutter_color_shade                 (const ClutterColor *color,
                                                             gdouble factor,
                                                             ClutterColor *result);

Shades `color` by `factor` and saves the modified color into `result`.

`color` : | a ClutterColor
`factor` : | the shade factor to apply
`result` : | return location for the shaded color. [out caller-allocates]

### clutter_color_interpolate ()

    void                clutter_color_interpolate           (const ClutterColor *initial,
                                                             const ClutterColor *final,
                                                             gdouble progress,
                                                             ClutterColor *result);

Interpolates between `initial` and `final` ClutterColors using `progress`

`initial` : | the initial ClutterColor
`final` : | the final ClutterColor
`progress` : | the interpolation progress
`result` : | return location for the interpolation. [out]

Since 1.6

### struct ClutterParamSpecColor

    struct ClutterParamSpecColor {
      ClutterColor *default_value;
    };

A GParamSpec subclass for defining properties holding a ClutterColor.

ClutterColor *`default_value`; | default color value

Since 1.0

### clutter_param_spec_color ()

    GParamSpec *        clutter_param_spec_color            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             const ClutterColor *default_value,
                                                             GParamFlags flags);

Creates a GParamSpec for properties using ClutterColor.

`name` : | name of the property
`nick` : | short name
`blurb` : | description (can be translatable)
`default_value` : | default value
`flags` : | flags for the param spec
Returns : | the newly created GParamSpec

Since 0.8.4

### CLUTTER_VALUE_HOLDS_COLOR()

    #define CLUTTER_VALUE_HOLDS_COLOR(x)       (G_VALUE_HOLDS ((x), CLUTTER_TYPE_COLOR))

Evaluates to `TRUE` if `x` holds a ClutterColor.

`x` : | a GValue

Since 1.0

### clutter_value_set_color ()

    void                clutter_value_set_color             (GValue *value,
                                                             const ClutterColor *color);

Sets `value` to `color`.

`value` : | a GValue initialized to CLUTTER_TYPE_COLOR
`color` : | the color to set

Since 0.8.4

### clutter_value_get_color ()

    const ClutterColor * clutter_value_get_color            (const GValue *value);

Gets the ClutterColor contained in `value`.

`value` : | a GValue initialized to CLUTTER_TYPE_COLOR
Returns : | the color inside the passed GValue. [transfer none]

Since 0.8.4