## Colors

Colors — Color management and manipulation.

## Synopsis

                        ClutterColor;
    ClutterColor *      clutter_color_copy                  (const ClutterColor *color);
    void                clutter_color_free                  (ClutterColor *color);

    gboolean            clutter_color_parse                 (const gchar *color,
                                                             ClutterColor *dest);
    void                clutter_color_from_hls              (ClutterColor *dest,
                                                             guint8 hue,
                                                             guint8 luminance,
                                                             guint8 saturation);
    void                clutter_color_from_hlsx             (ClutterColor *dest,
                                                             ClutterFixed hue,
                                                             ClutterFixed luminance,
                                                             ClutterFixed saturation);
    void                clutter_color_from_pixel            (ClutterColor *dest,
                                                             guint32 pixel);

    void                clutter_color_add                   (const ClutterColor *src1,
                                                             const ClutterColor *src2,
                                                             ClutterColor *dest);
    void                clutter_color_subtract              (const ClutterColor *src1,
                                                             const ClutterColor *src2,
                                                             ClutterColor *dest);
    gboolean            clutter_color_equal                 (const ClutterColor *a,
                                                             const ClutterColor *b);
    void                clutter_color_lighten               (const ClutterColor *src,
                                                             ClutterColor *dest);
    void                clutter_color_darken                (const ClutterColor *src,
                                                             ClutterColor *dest);
    void                clutter_color_shade                 (const ClutterColor *src,
                                                             ClutterColor *dest,
                                                             gdouble shade);
    void                clutter_color_shadex                (const ClutterColor *src,
                                                             ClutterColor *dest,
                                                             ClutterFixed shade);

    void                clutter_color_to_hls                (const ClutterColor *src,
                                                             guint8 *hue,
                                                             guint8 *luminance,
                                                             guint8 *saturation);
    void                clutter_color_to_hlsx               (const ClutterColor *src,
                                                             ClutterFixed *hue,
                                                             ClutterFixed *luminance,
                                                             ClutterFixed *saturation);
    guint32             clutter_color_to_pixel              (const ClutterColor *src);
    gchar *             clutter_color_to_string             (const ClutterColor *color);

                        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,
                                                             ClutterColor *color);
    const ClutterColor * clutter_value_get_color            (const GValue *value);

## Description

ClutterColor is a simple type for representing colors.

## 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_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_parse ()

    gboolean            clutter_color_parse                 (const gchar *color,
                                                             ClutterColor *dest);

Parses a string definition of a color, filling the `red`, `green`, `blue` and `alpha` channels of `dest`. If alpha is not specified it will be set full opaque. The color in `dest` is not allocated.

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

`color` : | a string specifiying a color (named color or RRGGBBAA)
`dest` : | return location for a ClutterColor
Returns : | `TRUE` if parsing succeeded.

Since 0.2

### clutter_color_from_hls ()

    void                clutter_color_from_hls              (ClutterColor *dest,
                                                             guint8 hue,
                                                             guint8 luminance,
                                                             guint8 saturation);

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

`dest` : | return location for a ClutterColor
`hue` : | hue value (0 .. 255)
`luminance` : | luminance value (0 .. 255)
`saturation` : | saturation value (0 .. 255)

### clutter_color_from_hlsx ()

    void                clutter_color_from_hlsx             (ClutterColor *dest,
                                                             ClutterFixed hue,
                                                             ClutterFixed luminance,
                                                             ClutterFixed saturation);

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

`dest` : | return location for a ClutterColor
`hue` : | hue value (0 .. 360)
`luminance` : | luminance value (0 .. 1)
`saturation` : | saturation value (0 .. 1)

### clutter_color_from_pixel ()

    void                clutter_color_from_pixel            (ClutterColor *dest,
                                                             guint32 pixel);

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

`dest` : | return location for a ClutterColor
`pixel` : | a 32 bit packed integer containing a color

### clutter_color_add ()

    void                clutter_color_add                   (const ClutterColor *src1,
                                                             const ClutterColor *src2,
                                                             ClutterColor *dest);

Adds `src2` to `src1` and saves the resulting color inside `dest`.

The alpha channel of `dest` is as the maximum value between the alpha channels of `src1` and `src2`.

`src1` : | a ClutterColor
`src2` : | a ClutterColor
`dest` : | return location for the result

### clutter_color_subtract ()

    void                clutter_color_subtract              (const ClutterColor *src1,
                                                             const ClutterColor *src2,
                                                             ClutterColor *dest);

Subtracts `src2` from `src1` and saves the resulting color inside `dest`. This function assumes that the components of `src1` are greater than the components of `src2`; the result is, otherwise, undefined.

The alpha channel of `dest` is set as the minimum value between the alpha channels of `src1` and `src2`.

`src1` : | a ClutterColor
`src2` : | a ClutterColor
`dest` : | return location for the result

### clutter_color_equal ()

    gboolean            clutter_color_equal                 (const ClutterColor *a,
                                                             const ClutterColor *b);

Compares two ClutterColors and checks if they are the same.

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

Since 0.2

### clutter_color_lighten ()

    void                clutter_color_lighten               (const ClutterColor *src,
                                                             ClutterColor *dest);

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

`src` : | a ClutterColor
`dest` : | return location for the lighter color

### clutter_color_darken ()

    void                clutter_color_darken                (const ClutterColor *src,
                                                             ClutterColor *dest);

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

`src` : | a ClutterColor
`dest` : | return location for the darker color

### clutter_color_shade ()

    void                clutter_color_shade                 (const ClutterColor *src,
                                                             ClutterColor *dest,
                                                             gdouble shade);

Shades `src` by the factor of `shade` and saves the modified color into `dest`.

`src` : | a ClutterColor
`dest` : | return location for the shaded color
`shade` : | the shade factor to apply

### clutter_color_shadex ()

    void                clutter_color_shadex                (const ClutterColor *src,
                                                             ClutterColor *dest,
                                                             ClutterFixed shade);

Fixed point version of `clutter_color_shade()`.

Shades `src` by the factor of `shade` and saves the modified color into `dest`.

`src` : | a ClutterColor
`dest` : | return location for the shaded color
`shade` : | ClutterFixed the shade factor to apply

Since 0.2

### clutter_color_to_hls ()

    void                clutter_color_to_hls                (const ClutterColor *src,
                                                             guint8 *hue,
                                                             guint8 *luminance,
                                                             guint8 *saturation);

Converts `src` to the HLS format. Returned HLS values are from interval 0 .. 255.

`src` : | 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_to_hlsx ()

    void                clutter_color_to_hlsx               (const ClutterColor *src,
                                                             ClutterFixed *hue,
                                                             ClutterFixed *luminance,
                                                             ClutterFixed *saturation);

Converts `src` to the HLS format. Returned hue is in degrees (0 .. 360), luminance and saturation from interval <0 .. 1>.

`src` : | 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_to_pixel ()

    guint32             clutter_color_to_pixel              (const ClutterColor *src);

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

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

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

### ClutterParamSpecColor

    typedef struct {
      ClutterColor *default_value;
    } ClutterParamSpecColor;

ClutterColor *`default_value`; | default color value

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