Clutter Reference Manual: Colors

## Colors Colors — Color management and manipulation. |

## Functions

#define | CLUTTER_COLOR_INIT()
ClutterColor * | clutter_color_new ()
ClutterColor * | clutter_color_alloc ()
ClutterColor * | clutter_color_init ()
ClutterColor * | clutter_color_copy ()
void | clutter_color_free ()
gboolean | clutter_color_equal ()
guint | clutter_color_hash ()
const ClutterColor * | clutter_color_get_static ()
gboolean | clutter_color_from_string ()
gchar * | clutter_color_to_string ()
void | clutter_color_from_hls ()
void | clutter_color_to_hls ()
void | clutter_color_from_pixel ()
guint32 | clutter_color_to_pixel ()
void | clutter_color_add ()
void | clutter_color_subtract ()
void | clutter_color_lighten ()
void | clutter_color_darken ()
void | clutter_color_shade ()
void | clutter_color_interpolate ()
GParamSpec * | clutter_param_spec_color ()
#define | CLUTTER_VALUE_HOLDS_COLOR()
void | clutter_value_set_color ()
const ClutterColor * | clutter_value_get_color ()

## Types and Values

| ClutterColor
enum | ClutterStaticColor
struct | ClutterParamSpecColor

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

## Functions

### CLUTTER_COLOR_INIT()

    #define CLUTTER_COLOR_INIT(r,g,b,a)     { (r), (g), (b), (a) }

A macro that initializes a ClutterColor, to be used when declaring it.

#### Parameters

r | value for the red channel, between 0 and 255 |
g | value for the green channel, between 0 and 255 |
b | value for the blue channel, between 0 and 255 |
a | value for the alpha channel, between 0 and 255 |

Since 1.12

### clutter_color_new ()

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

Creates a new ClutterColor with the given values.

This function is the equivalent of:

    1
    clutter_color_init (clutter_color_alloc (), red, green, blue, alpha);

#### Parameters

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_alloc ()

    ClutterColor *
    clutter_color_alloc (void);

Allocates a new, transparent black ClutterColor.

#### Returns

the newly allocated ClutterColor; use `clutter_color_free()` to free its resources.

[transfer full]

Since 1.12

### clutter_color_init ()

    ClutterColor *
    clutter_color_init (ClutterColor *color,
                        guint8 red,
                        guint8 green,
                        guint8 blue,
                        guint8 alpha);

Initializes `color` with the given values.

#### Parameters

color | a ClutterColor |
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 initialized ClutterColor.

[transfer none]

Since 1.12

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

#### Parameters

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

#### Parameters

color | a ClutterColor |

Since 0.2

### clutter_color_equal ()

    gboolean
    clutter_color_equal (gconstpointer v1,
                         gconstpointer v2);

Compares two ClutterColor<!-- -->s 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 ClutterColor<!-- -->s as keys in a GHashTable.

#### Parameters

v1 | a ClutterColor. | [type Clutter.Color]
v2 | a ClutterColor. | [type Clutter.Color]

#### 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 ClutterColor<!-- -->s as keys in a GHashTable.

#### Parameters

v | a ClutterColor. | [type Clutter.Color]

#### Returns

a hash value corresponding to the color

Since 1.0

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

#### Parameters

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 <structfield>red</structfield>, <structfield>green</structfield>, <structfield>blue</structfield> and <structfield>alpha</structfield> 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) is an angle between 0 and 360.0 degrees; the 'l' and 's' values (luminance and saturation) are percentage values in the range between 0% and 100%. 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.

#### Parameters

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 <literal>#rrggbbaa</literal>, where <literal>r</literal>, <literal>g</literal>, <literal>b</literal> and <literal>a</literal> are hexadecimal digits representing the red, green, blue and alpha components respectively.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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` ClutterColor<!-- -->s using `progress`

#### Parameters

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

Since 1.6

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

#### Parameters

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

#### Parameters

x | a GValue |

Since 1.0

### clutter_value_set_color ()

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

Sets `value` to `color` .

#### Parameters

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

#### Parameters

value | a GValue initialized to CLUTTER_TYPE_COLOR |

#### Returns

the color inside the passed GValue.

[transfer none]

Since 0.8.4

## Types and Values

### ClutterColor

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

      guint8 alpha;
    } ClutterColor;

Color representation.

#### Members

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 |

### enum ClutterStaticColor

Named colors, for accessing global colors defined by Clutter

#### Members

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

### struct ClutterParamSpecColor

    struct ClutterParamSpecColor {
      ClutterColor *default_value;
    };

A GParamSpec subclass for defining properties holding a ClutterColor.

#### Members

ClutterColor *`default_value`; | default color value |

Since 1.0