GimpRGB

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

## Synopsis

                GimpRGB;
    enum        GimpRGBCompositeMode;
    void        gimp_rgb_set                    (GimpRGB *rgb,
                                                 gdouble red,
                                                 gdouble green,
                                                 gdouble blue);
    void        gimp_rgb_set_alpha              (GimpRGB *rgb,
                                                 gdouble alpha);
    void        gimp_rgb_set_uchar              (GimpRGB *rgb,
                                                 guchar red,
                                                 guchar green,
                                                 guchar blue);
    void        gimp_rgb_get_uchar              (const GimpRGB *rgb,
                                                 guchar *red,
                                                 guchar *green,
                                                 guchar *blue);
    gboolean    gimp_rgb_parse_name             (GimpRGB *rgb,
                                                 const gchar *name,
                                                 gint len);
    gboolean    gimp_rgb_parse_hex              (GimpRGB *rgb,
                                                 const gchar *hex,
                                                 gint len);
    gboolean    gimp_rgb_parse_css              (GimpRGB *rgb,
                                                 const gchar *css,
                                                 gint len);
    gint        gimp_rgb_list_names             (const gchar ***names,
                                                 GimpRGB **colors);
    void        gimp_rgb_add                    (GimpRGB *rgb1,
                                                 const GimpRGB *rgb2);
    void        gimp_rgb_subtract               (GimpRGB *rgb1,
                                                 const GimpRGB *rgb2);
    void        gimp_rgb_multiply               (GimpRGB *rgb1,
                                                 gdouble factor);
    gdouble     gimp_rgb_distance               (const GimpRGB *rgb1,
                                                 const GimpRGB *rgb2);
    gdouble     gimp_rgb_max                    (const GimpRGB *rgb);
    gdouble     gimp_rgb_min                    (const GimpRGB *rgb);
    void        gimp_rgb_clamp                  (GimpRGB *rgb);
    void        gimp_rgb_gamma                  (GimpRGB *rgb,
                                                 gdouble gamma);
    gdouble     gimp_rgb_intensity              (const GimpRGB *rgb);
    guchar      gimp_rgb_intensity_uchar        (const GimpRGB *rgb);
    void        gimp_rgb_composite              (GimpRGB *color1,
                                                 const GimpRGB *color2,
                                                 GimpRGBCompositeMode mode);
    void        gimp_rgba_set                   (GimpRGB *rgba,
                                                 gdouble red,
                                                 gdouble green,
                                                 gdouble blue,
                                                 gdouble alpha);
    void        gimp_rgba_set_uchar             (GimpRGB *rgba,
                                                 guchar red,
                                                 guchar green,
                                                 guchar blue,
                                                 guchar alpha);
    void        gimp_rgba_get_uchar             (const GimpRGB *rgba,
                                                 guchar *red,
                                                 guchar *green,
                                                 guchar *blue,
                                                 guchar *alpha);
    gboolean    gimp_rgba_parse_css             (GimpRGB *rgba,
                                                 const gchar *css,
                                                 gint len);
    void        gimp_rgba_add                   (GimpRGB *rgba1,
                                                 const GimpRGB *rgba2);
    void        gimp_rgba_subtract              (GimpRGB *rgba1,
                                                 const GimpRGB *rgba2);
    void        gimp_rgba_multiply              (GimpRGB *rgba,
                                                 gdouble factor);
    gdouble     gimp_rgba_distance              (const GimpRGB *rgba1,
                                                 const GimpRGB *rgba2);
    #define     GIMP_RGB_INTENSITY              (r,g,b)
    #define     GIMP_RGB_INTENSITY_RED
    #define     GIMP_RGB_INTENSITY_GREEN
    #define     GIMP_RGB_INTENSITY_BLUE
    #define     GIMP_TYPE_RGB
    #define     GIMP_VALUE_HOLDS_RGB            (value)

## Description

Definitions and Functions relating to RGB colors.

## Details

### GimpRGB

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

### enum GimpRGBCompositeMode

    typedef enum
    {
      GIMP_RGB_COMPOSITE_NONE = 0,
      GIMP_RGB_COMPOSITE_NORMAL,
      GIMP_RGB_COMPOSITE_BEHIND
    } GimpRGBCompositeMode;

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

`rgb` : | a GimpRGB struct
`red` : |
`green` : |
`blue` : |

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

`rgb` : | a GimpRGB struct
`alpha` : |

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

`rgb` : | a GimpRGB struct
`red` : |
`green` : |
`blue` : |

### gimp_rgb_get_uchar ()

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

`rgb` : |
`red` : |
`green` : |
`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 RGB hex values or SVG 1.0 color keywords. The format of an RGB value in hexadecimal notation is a '#' immediately followed by either three or six hexadecimal characters.

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

`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 GIMP 2.2

### gimp_rgb_parse_hex ()

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

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

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

`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 GIMP 2.2

### gimp_rgb_parse_css ()

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

Attempts to parse a string describing a color in RGB value 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 funcion does not touch the alpha component of `rgb`.

`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 GIMP 2.2

### gimp_rgb_list_names ()

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

Allows to retrieve 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.

`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 GIMP 2.2

### gimp_rgb_add ()

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

`rgb1` : |
`rgb2` : |

### gimp_rgb_subtract ()

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

`rgb1` : |
`rgb2` : |

### gimp_rgb_multiply ()

    void        gimp_rgb_multiply               (GimpRGB *rgb1,
                                                 gdouble factor);

`rgb1` : |
`factor` : |

### gimp_rgb_distance ()

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

`rgb1` : |
`rgb2` : |
Returns : |

### gimp_rgb_max ()

    gdouble     gimp_rgb_max                    (const GimpRGB *rgb);

`rgb` : |
Returns : |

### gimp_rgb_min ()

    gdouble     gimp_rgb_min                    (const GimpRGB *rgb);

`rgb` : |
Returns : |

### gimp_rgb_clamp ()

    void        gimp_rgb_clamp                  (GimpRGB *rgb);

`rgb` : |

### gimp_rgb_gamma ()

    void        gimp_rgb_gamma                  (GimpRGB *rgb,
                                                 gdouble gamma);

`rgb` : |
`gamma` : |

### gimp_rgb_intensity ()

    gdouble     gimp_rgb_intensity              (const GimpRGB *rgb);

`rgb` : |
Returns : |

### gimp_rgb_intensity_uchar ()

    guchar      gimp_rgb_intensity_uchar        (const GimpRGB *rgb);

`rgb` : |
Returns : |

### gimp_rgb_composite ()

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

`color1` : |
`color2` : |
`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.

`rgba` : | a GimpRGB struct
`red` : |
`green` : |
`blue` : |
`alpha` : |

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

`rgba` : | a GimpRGB struct
`red` : |
`green` : |
`blue` : |
`alpha` : |

### gimp_rgba_get_uchar ()

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

`rgba` : |
`red` : |
`green` : |
`blue` : |
`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.

`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 GIMP 2.2

### gimp_rgba_add ()

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

`rgba1` : |
`rgba2` : |

### gimp_rgba_subtract ()

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

`rgba1` : |
`rgba2` : |

### gimp_rgba_multiply ()

    void        gimp_rgba_multiply              (GimpRGB *rgba,
                                                 gdouble factor);

`rgba` : |
`factor` : |

### gimp_rgba_distance ()

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

`rgba1` : |
`rgba2` : |
Returns : |

### GIMP_RGB_INTENSITY()

    #define     GIMP_RGB_INTENSITY(r,g,b)

This macro calculates the intensity of an RGB value based on coefficients taken from the NTSC analog television standard.

`r` : | red
`g` : | green
`b` : | blue

### GIMP_RGB_INTENSITY_RED

    #define GIMP_RGB_INTENSITY_RED    0.30

### GIMP_RGB_INTENSITY_GREEN

    #define GIMP_RGB_INTENSITY_GREEN  0.59

### GIMP_RGB_INTENSITY_BLUE

    #define GIMP_RGB_INTENSITY_BLUE   0.11

### GIMP_TYPE_RGB

    #define GIMP_TYPE_RGB               (gimp_rgb_get_type ())

GIMP_TYPE_RGB is a GType derived from G_TYPE_BOXED.

### GIMP_VALUE_HOLDS_RGB()

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

`value` : |