GimpRGB: GIMP Color Library Reference Manual

## GimpRGB GimpRGB — Definitions and Functions relating to RGB colors. |

## Functions

void | gimp_rgb_set ()
void | gimp_rgb_set_alpha ()
void | gimp_rgb_set_pixel ()
void | gimp_rgb_get_pixel ()
void | gimp_rgb_set_uchar ()
void | gimp_rgb_get_uchar ()
gboolean | gimp_rgb_parse_name ()
gboolean | gimp_rgb_parse_hex ()
gboolean | gimp_rgb_parse_css ()
gint | gimp_rgb_list_names ()
void | gimp_rgb_add ()
void | gimp_rgb_subtract ()
void | gimp_rgb_multiply ()
gdouble | gimp_rgb_distance ()
gdouble | gimp_rgb_max ()
gdouble | gimp_rgb_min ()
void | gimp_rgb_clamp ()
void | gimp_rgb_gamma ()
gdouble | gimp_rgb_luminance ()
guchar | gimp_rgb_luminance_uchar ()
gdouble | gimp_rgb_intensity ()
guchar | gimp_rgb_intensity_uchar ()
void | gimp_rgb_composite ()
void | gimp_rgba_set ()
void | gimp_rgba_set_pixel ()
void | gimp_rgba_get_pixel ()
void | gimp_rgba_set_uchar ()
void | gimp_rgba_get_uchar ()
gboolean | gimp_rgba_parse_css ()
void | gimp_rgba_add ()
void | gimp_rgba_subtract ()
void | gimp_rgba_multiply ()
gdouble | gimp_rgba_distance ()
#define | GIMP_RGB_LUMINANCE()
#define | GIMP_RGB_INTENSITY()
GParamSpec * | gimp_param_spec_rgb ()
void | gimp_param_spec_rgb_get_default ()
gboolean | gimp_param_spec_rgb_has_alpha ()
#define | GIMP_VALUE_HOLDS_RGB()
void | gimp_value_get_rgb ()
void | gimp_value_set_rgb ()

## Types and Values

struct | GimpRGB
enum | GimpRGBCompositeMode
#define | GIMP_RGB_LUMINANCE_RED
#define | GIMP_RGB_LUMINANCE_GREEN
#define | GIMP_RGB_LUMINANCE_BLUE
#define | GIMP_RGB_INTENSITY_RED
#define | GIMP_RGB_INTENSITY_GREEN
#define | GIMP_RGB_INTENSITY_BLUE
#define | GIMP_TYPE_RGB
#define | GIMP_TYPE_PARAM_RGB

## Description

Definitions and Functions relating to RGB colors.

## Functions

### gimp_rgb_set ()

    void
    gimp_rgb_set (GimpRGB *rgb,
                  gdouble red,
                  gdouble green,
                  gdouble blue);

Sets the red, green and blue components of `rgb` and leaves the alpha component unchanged. The color values should be between 0.0 and 1.0 but there is no check to enforce this and the values are set exactly as they are passed in.

#### Parameters

rgb | a GimpRGB struct |
red | the red component |
green | the green component |
blue | the blue component |

### gimp_rgb_set_alpha ()

    void
    gimp_rgb_set_alpha (GimpRGB *rgb,
                        gdouble alpha);

Sets the alpha component of `rgb` and leaves the RGB components unchanged.

#### Parameters

rgb | a GimpRGB struct |
alpha | the alpha component |

### gimp_rgb_set_pixel ()

    void
    gimp_rgb_set_pixel (GimpRGB *rgb,
                        const Babl *format,
                        gconstpointer pixel);

Sets the red, green and blue components of `rgb` from the color stored in `pixel` . The pixel format of `pixel` is determined by `format` .

#### Parameters

rgb | a GimpRGB struct |
format | a Babl format |
pixel | pointer to the source pixel |

Since: 2.10

### gimp_rgb_get_pixel ()

    void
    gimp_rgb_get_pixel (const GimpRGB *rgb,
                        const Babl *format,
                        gpointer pixel);

Writes the red, green, blue and alpha components of `rgb` to the color stored in `pixel` . The pixel format of `pixel` is determined by `format` .

#### Parameters

rgb | a GimpRGB struct |
format | a Babl format |
pixel | pointer to the destination pixel |

Since: 2.10

### gimp_rgb_set_uchar ()

    void
    gimp_rgb_set_uchar (GimpRGB *rgb,
                        guchar red,
                        guchar green,
                        guchar blue);

Sets the red, green and blue components of `rgb` from 8bit values (0 to 255) and leaves the alpha component unchanged.

#### Parameters

rgb | a GimpRGB struct |
red | the red component |
green | the green component |
blue | the blue component |

### gimp_rgb_get_uchar ()

    void
    gimp_rgb_get_uchar (const GimpRGB *rgb,
                        guchar *red,
                        guchar *green,
                        guchar *blue);

### gimp_rgb_parse_name ()

    gboolean
    gimp_rgb_parse_name (GimpRGB *rgb,
                         const gchar *name,
                         gint len);

Attempts to parse a color name. This function accepts SVG 1.0 color keywords.

This function does not touch the alpha component of `rgb` .

#### Parameters

rgb | a GimpRGB struct used to return the parsed color |
name | a color name (in UTF-8 encoding) |
len | the length of `name` , in bytes. or -1 if `name` is nul-terminated |

#### Returns

`TRUE` if `name` was parsed successfully and `rgb` has been set, `FALSE` otherwise

Since: 2.2

### gimp_rgb_parse_hex ()

    gboolean
    gimp_rgb_parse_hex (GimpRGB *rgb,
                        const gchar *hex,
                        gint len);

Attempts to parse a string describing an RGB color in hexadecimal notation (optionally prefixed with a '#').

This function does not touch the alpha component of `rgb` .

#### Parameters

rgb | a GimpRGB struct used to return the parsed color |
hex | a string describing a color in hexadecimal notation |
len | the length of `hex` , in bytes. or -1 if `hex` is nul-terminated |

#### Returns

`TRUE` if `hex` was parsed successfully and `rgb` has been set, `FALSE` otherwise

Since: 2.2

### gimp_rgb_parse_css ()

    gboolean
    gimp_rgb_parse_css (GimpRGB *rgb,
                        const gchar *css,
                        gint len);

Attempts to parse a string describing an RGB color in CSS notation. This can be either a numerical representation (`rgb(255,0,0)` or `rgb(100%,0%,0%)`) or a hexadecimal notation as parsed by `gimp_rgb_parse_hex()` (`#ff0000`) or a color name as parsed by `gimp_rgb_parse_name()` (`red`).

This function does not touch the alpha component of `rgb` .

#### Parameters

rgb | a GimpRGB struct used to return the parsed color |
css | a string describing a color in CSS notation |
len | the length of `hex` , in bytes. or -1 if `hex` is nul-terminated |

#### Returns

`TRUE` if `css` was parsed successfully and `rgb` has been set, `FALSE` otherwise

Since: 2.2

### gimp_rgb_list_names ()

    gint
    gimp_rgb_list_names (const gchar ***names,
                         GimpRGB **colors);

Returns the list of SVG 1.0 color keywords that is used by `gimp_rgb_parse_name()`.

The returned strings are const and must not be freed. Only the two arrays are allocated dynamically. You must call `g_free()` on the `names` and `colors` arrays when they are not any longer needed.

#### Parameters

names | return location for an array of color names |
colors | return location for an array of GimpRGB structs |

#### Returns

the number of named colors (i.e. the length of the returned arrays)

Since: 2.2

### gimp_rgb_add ()

    void
    gimp_rgb_add (GimpRGB *rgb1,
                  const GimpRGB *rgb2);

### gimp_rgb_subtract ()

    void
    gimp_rgb_subtract (GimpRGB *rgb1,
                       const GimpRGB *rgb2);

### gimp_rgb_multiply ()

    void
    gimp_rgb_multiply (GimpRGB *rgb1,
                       gdouble factor);

### gimp_rgb_distance ()

    gdouble
    gimp_rgb_distance (const GimpRGB *rgb1,
                       const GimpRGB *rgb2);

### gimp_rgb_max ()

    gdouble
    gimp_rgb_max (const GimpRGB *rgb);

### gimp_rgb_min ()

    gdouble
    gimp_rgb_min (const GimpRGB *rgb);

### gimp_rgb_clamp ()

    void
    gimp_rgb_clamp (GimpRGB *rgb);

### gimp_rgb_gamma ()

    void
    gimp_rgb_gamma (GimpRGB *rgb,
                    gdouble gamma);

### gimp_rgb_luminance ()

    gdouble
    gimp_rgb_luminance (const GimpRGB *rgb);

#### Parameters

rgb | a GimpRGB struct |

#### Returns

the luminous intensity of the range from 0.0 to 1.0.

Since: 2.4

### gimp_rgb_luminance_uchar ()

    guchar
    gimp_rgb_luminance_uchar (const GimpRGB *rgb);

#### Parameters

rgb | a GimpRGB struct |

#### Returns

the luminous intensity in the range from 0 to 255.

Since: 2.4

### gimp_rgb_intensity ()

    gdouble
    gimp_rgb_intensity (const GimpRGB *rgb);

`gimp_rgb_intensity` is deprecated and should not be used in newly-written code.

This function is deprecated! Use `gimp_rgb_luminance()` instead.

#### Parameters

rgb | a GimpRGB struct |

#### Returns

the intensity in the range from 0.0 to 1.0.

### gimp_rgb_intensity_uchar ()

    guchar
    gimp_rgb_intensity_uchar (const GimpRGB *rgb);

`gimp_rgb_intensity_uchar` is deprecated and should not be used in newly-written code.

This function is deprecated! Use `gimp_rgb_luminance_uchar()` instead.

#### Parameters

rgb | a GimpRGB struct |

#### Returns

the intensity in the range from 0 to 255.

### gimp_rgb_composite ()

    void
    gimp_rgb_composite (GimpRGB *color1,
                        const GimpRGB *color2,
                        GimpRGBCompositeMode mode);

### gimp_rgba_set ()

    void
    gimp_rgba_set (GimpRGB *rgba,
                   gdouble red,
                   gdouble green,
                   gdouble blue,
                   gdouble alpha);

Sets the red, green, blue and alpha components of `rgb` . The values should be between 0.0 and 1.0 but there is no check to enforce this and the values are set exactly as they are passed in.

#### Parameters

rgba | a GimpRGB struct |
red | the red component |
green | the green component |
blue | the blue component |
alpha | the alpha component |

### gimp_rgba_set_pixel ()

    void
    gimp_rgba_set_pixel (GimpRGB *rgba,
                         const Babl *format,
                         gconstpointer pixel);

Sets the red, green, blue and alpha components of `rgba` from the color stored in `pixel` . The pixel format of `pixel` is determined by `format` .

#### Parameters

rgba | a GimpRGB struct |
format | a Babl format |
pixel | pointer to the source pixel |

Since: 2.10

### gimp_rgba_get_pixel ()

    void
    gimp_rgba_get_pixel (const GimpRGB *rgba,
                         const Babl *format,
                         gpointer pixel);

Writes the red, green, blue and alpha components of `rgba` to the color stored in `pixel` . The pixel format of `pixel` is determined by `format` .

#### Parameters

rgba | a GimpRGB struct |
format | a Babl format |
pixel | pointer to the destination pixel |

Since: 2.10

### gimp_rgba_set_uchar ()

    void
    gimp_rgba_set_uchar (GimpRGB *rgba,
                         guchar red,
                         guchar green,
                         guchar blue,
                         guchar alpha);

Sets the red, green, blue and alpha components of `rgb` from 8bit values (0 to 255).

#### Parameters

rgba | a GimpRGB struct |
red | the red component |
green | the green component |
blue | the blue component |
alpha | the alpha component |

### gimp_rgba_get_uchar ()

    void
    gimp_rgba_get_uchar (const GimpRGB *rgba,
                         guchar *red,
                         guchar *green,
                         guchar *blue,
                         guchar *alpha);

### gimp_rgba_parse_css ()

    gboolean
    gimp_rgba_parse_css (GimpRGB *rgba,
                         const gchar *css,
                         gint len);

Similar to `gimp_rgb_parse_css()` but handles RGB colors with alpha channel in the numerical CSS notation (`rgba(255,0,0,255)` or `rgba(100%,0%,0%,1000%)`).

It doesn't handle the hexadecimal notation or color names because they leave the alpha channel unspecified.

#### Parameters

rgba | a GimpRGB struct used to return the parsed color |
css | a string describing a color in CSS notation |
len | the length of `hex` , in bytes. or -1 if `hex` is nul-terminated |

#### Returns

`TRUE` if `css` was parsed successfully and `rgb` has been set, `FALSE` otherwise

Since: 2.2

### gimp_rgba_add ()

    void
    gimp_rgba_add (GimpRGB *rgba1,
                   const GimpRGB *rgba2);

### gimp_rgba_subtract ()

    void
    gimp_rgba_subtract (GimpRGB *rgba1,
                        const GimpRGB *rgba2);

### gimp_rgba_multiply ()

    void
    gimp_rgba_multiply (GimpRGB *rgba,
                        gdouble factor);

### gimp_rgba_distance ()

    gdouble
    gimp_rgba_distance (const GimpRGB *rgba1,
                        const GimpRGB *rgba2);

### GIMP_RGB_LUMINANCE()

    #define             GIMP_RGB_LUMINANCE(r,g,b)

### GIMP_RGB_INTENSITY()

    #define             GIMP_RGB_INTENSITY(r,g,b)

`GIMP_RGB_INTENSITY` is deprecated and should not be used in newly-written code.

### gimp_param_spec_rgb ()

    GParamSpec *
    gimp_param_spec_rgb (const gchar *name,
                         const gchar *nick,
                         const gchar *blurb,
                         gboolean has_alpha,
                         const GimpRGB *default_value,
                         GParamFlags flags);

Creates a param spec to hold an GimpRGB value. See `g_param_spec_internal()` for more information.

#### Parameters

name | Canonical name of the param |
nick | Nickname of the param |
blurb | Brief description of param. |
has_alpha | `TRUE` if the alpha channel has relevance. |
default_value | Value to use if none is assigned. |
flags | a combination of GParamFlags |

#### Returns

a newly allocated GParamSpec instance

Since: 2.4

### gimp_param_spec_rgb_get_default ()

    void
    gimp_param_spec_rgb_get_default (GParamSpec *pspec,
                                     GimpRGB *default_value);

Returns the `pspec` 's default color value.

#### Parameters

pspec | a GimpParamSpecRGB. |
default_value | return location for `pspec` 's default value |

Since: 2.10.14

### gimp_param_spec_rgb_has_alpha ()

    gboolean
    gimp_param_spec_rgb_has_alpha (GParamSpec *pspec);

#### Parameters

pspec | a GParamSpec to hold an GimpRGB value. |

#### Returns

`TRUE` if the alpha channel is relevant.

Since: 2.4

### GIMP_VALUE_HOLDS_RGB()

    #define GIMP_VALUE_HOLDS_RGB(value) (G_TYPE_CHECK_VALUE_TYPE ((value), GIMP_TYPE_RGB))

### gimp_value_get_rgb ()

    void
    gimp_value_get_rgb (const GValue *value,
                        GimpRGB *rgb);

### gimp_value_set_rgb ()

    void
    gimp_value_set_rgb (GValue *value,
                        const GimpRGB *rgb);

## Types and Values

### struct GimpRGB

    struct GimpRGB {
      gdouble r, g, b, a;
    };

Used to keep RGB and RGBA colors. All components are in a range of [0.0..1.0].

#### Members

gdouble `r`; | the red component |
gdouble `g`; | the green component |
gdouble `b`; | the blue component |
gdouble `a`; | the alpha component |

### enum GimpRGBCompositeMode

#### Members

GIMP_RGB_COMPOSITE_NONE | don't do compositing |
GIMP_RGB_COMPOSITE_NORMAL | composite on top |
GIMP_RGB_COMPOSITE_BEHIND | composite behind |

### GIMP_RGB_LUMINANCE_RED

    #define GIMP_RGB_LUMINANCE_RED    (0.22248840)

### GIMP_RGB_LUMINANCE_GREEN

    #define GIMP_RGB_LUMINANCE_GREEN  (0.71690369)

### GIMP_RGB_LUMINANCE_BLUE

    #define GIMP_RGB_LUMINANCE_BLUE   (0.06060791)

### GIMP_RGB_INTENSITY_RED

    #define GIMP_RGB_INTENSITY_RED    (0.30)

`GIMP_RGB_INTENSITY_RED` is deprecated and should not be used in newly-written code.

### GIMP_RGB_INTENSITY_GREEN

    #define GIMP_RGB_INTENSITY_GREEN  (0.59)

`GIMP_RGB_INTENSITY_GREEN` is deprecated and should not be used in newly-written code.

### GIMP_RGB_INTENSITY_BLUE

    #define GIMP_RGB_INTENSITY_BLUE   (0.11)

`GIMP_RGB_INTENSITY_BLUE` is deprecated and should not be used in newly-written code.

### GIMP_TYPE_RGB

    #define GIMP_TYPE_RGB               (gimp_rgb_get_type ())

### GIMP_TYPE_PARAM_RGB

    #define GIMP_TYPE_PARAM_RGB           (gimp_param_rgb_get_type ())