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

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

                        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.

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

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`.

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.
`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

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`
`luminance` : | return location for the luminance value or `NULL`
`saturation` : | return location for the saturation value or `NULL`

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

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

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

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

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

### ClutterParamSpecColor

    typedef struct {
      ClutterColor *default_value;
    } ClutterParamSpecColor;

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 colors inside the passed GValue

Since 0.8.4