## Colors

Colors — Color management and manipulation.

## Synopsis

    struct              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);

    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);

    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

### struct ClutterColor

    struct ClutterColor {
      guint8 red;
      guint8 green;
      guint8 blue;

      guint8 alpha;
    };

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

### 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`. If alpha is not specified it will be set full opaque.

The `color` is not allocated.

The color may be defined by any of the formats understood by `pango_color_from_string()`; these include literal color names, like `Red` or `DarkSlateGray`, or hexadecimal specifications like `#3050b2` or `#333`.

`color` : | return location for a ClutterColor. [out caller-allocates]
`str` : | a string specifiying a color (named color or RRGGBBAA)
Returns : | `TRUE` if parsing succeeded.

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 hex 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]

### 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