## GwyRGBA

GwyRGBA — Bit depth independet RGBA colors

## Synopsis

    #include <libdraw/gwydraw.h>

    #define             GWY_TYPE_RGBA
                        GwyRGBA;
    GType               gwy_rgba_get_type                   (void);
    GwyRGBA*            gwy_rgba_copy                       (const GwyRGBA *rgba);
    void                gwy_rgba_free                       (GwyRGBA *rgba);
    void                gwy_rgba_to_gdk_color               (const GwyRGBA *rgba,
                                                             GdkColor *gdkcolor);
    guint16             gwy_rgba_to_gdk_alpha               (const GwyRGBA *rgba);
    void                gwy_rgba_from_gdk_color             (GwyRGBA *rgba,
                                                             const GdkColor *gdkcolor);
    void                gwy_rgba_from_gdk_color_and_alpha   (GwyRGBA *rgba,
                                                             const GdkColor *gdkcolor,
                                                             guint16 gdkalpha);
    void                gwy_rgba_interpolate                (const GwyRGBA *src1,
                                                             const GwyRGBA *src2,
                                                             gdouble x,
                                                             GwyRGBA *rgba);
    gboolean            gwy_rgba_get_from_container         (GwyRGBA *rgba,
                                                             GwyContainer *container,
                                                             const gchar *prefix);
    void                gwy_rgba_store_to_container         (const GwyRGBA *rgba,
                                                             GwyContainer *container,
                                                             const gchar *prefix);
    gboolean            gwy_rgba_remove_from_container      (GwyContainer *container,
                                                             const gchar *prefix);
    void                gwy_rgba_set_gdk_gc_fg              (const GwyRGBA *rgba,
                                                             GdkGC *gc);
    void                gwy_rgba_set_gdk_gc_bg              (const GwyRGBA *rgba,
                                                             GdkGC *gc);

## Description

GwyRGBA is a bit depth independent representation of an RGB or RGBA color, using floating point values from the [0,1] interval.

GwyRGBA is not an object, but a simple struct that can be allocated on stack on created with `g_new()` or `malloc()`. Helper functions for conversion between GwyRGBA and GdkColor (`gwy_rgba_to_gdk_color()`, `gwy_rgba_from_gdk_color()`) and for GwyContainer storage by component (`gwy_rgba_store_to_container()`, `gwy_rgba_get_from_container()`) are provided.

## Details

### GWY_TYPE_RGBA

    #define GWY_TYPE_RGBA                         (gwy_rgba_get_type())

### GwyRGBA

    typedef struct {
        gdouble r;
        gdouble g;
        gdouble b;
        gdouble a;
    } GwyRGBA;

RGB[A] color specification type.

All values are from the range [0,1].

gdouble `r`; | The red component.
gdouble `g`; | The green component.
gdouble `b`; | The blue component.
gdouble `a`; | The alpha (opacity) value.

### gwy_rgba_get_type ()

    GType               gwy_rgba_get_type                   (void);

Returns : |

### gwy_rgba_copy ()

    GwyRGBA*            gwy_rgba_copy                       (const GwyRGBA *rgba);

Makes a copy of a rgba structure. The result must be freed using `gwy_rgba_free()`.

`rgba` : | A RGBA color.
Returns : | A copy of `rgba`.

### gwy_rgba_free ()

    void                gwy_rgba_free                       (GwyRGBA *rgba);

Frees an rgba structure created with `gwy_rgba_copy()`.

`rgba` : | A RGBA color.

### gwy_rgba_to_gdk_color ()

    void                gwy_rgba_to_gdk_color               (const GwyRGBA *rgba,
                                                             GdkColor *gdkcolor);

Converts a rgba to a Gdk color.

Note no allocation is performed, just channel value conversion.

`rgba` : | A RGBA color.
`gdkcolor` : | A GdkColor.

### gwy_rgba_to_gdk_alpha ()

    guint16             gwy_rgba_to_gdk_alpha               (const GwyRGBA *rgba);

Converts a rgba to a Gdk opacity value.

`rgba` : | A RGBA color.
Returns : | The opacity value as a 16bit integer.

### gwy_rgba_from_gdk_color ()

    void                gwy_rgba_from_gdk_color             (GwyRGBA *rgba,
                                                             const GdkColor *gdkcolor);

Converts a Gdk color to a rgba.

The alpha value is unchanged, as GdkColor has no opacity information.

`rgba` : | A RGBA color.
`gdkcolor` : | A GdkColor.

### gwy_rgba_from_gdk_color_and_alpha ()

    void                gwy_rgba_from_gdk_color_and_alpha   (GwyRGBA *rgba,
                                                             const GdkColor *gdkcolor,
                                                             guint16 gdkalpha);

Converts a Gdk color plus an opacity value to a rgba.

`rgba` : | A RGBA color.
`gdkcolor` : | A GdkColor.
`gdkalpha` : | Gdk 16bit opacity value.

### gwy_rgba_interpolate ()

    void                gwy_rgba_interpolate                (const GwyRGBA *src1,
                                                             const GwyRGBA *src2,
                                                             gdouble x,
                                                             GwyRGBA *rgba);

Linearly interpolates two colors, including alpha blending.

Correct blending of two not fully opaque colors is tricky. Always use this function, not simple independent interpolation of r, g, b, and a.

`src1` : | Color at point `x` = 0.0.
`src2` : | Color at point `x` = 1.0.
`x` : | Point in interval 0..1 to take color from.
`rgba` : | A GwyRGBA to store result to.

### gwy_rgba_get_from_container ()

    gboolean            gwy_rgba_get_from_container         (GwyRGBA *rgba,
                                                             GwyContainer *container,
                                                             const gchar *prefix);

Gets RGBA color components from a container.

This is a convenience function to get the components in the common arrangement.

`rgba` : | A RGBA color.
`container` : | A GwyContainer to get the color components from.
`prefix` : | Prefix in `container`, e.g. "/0/mask" (it would try to fetch "/0/mask/red", "/0/mask/green", etc. then).
Returns : | Whether all `rgba` components were successfully found and set.

### gwy_rgba_store_to_container ()

    void                gwy_rgba_store_to_container         (const GwyRGBA *rgba,
                                                             GwyContainer *container,
                                                             const gchar *prefix);

Stores RGBA color components to a container.

This is a convenience function to store the components in the common arrangement.

`rgba` : | A RGBA color.
`container` : | A GwyContainer to store the color components to.
`prefix` : | Prefix in `container`, e.g. "/0/mask" (it will store "/0/mask/red", "/0/mask/green", etc. then).

### gwy_rgba_remove_from_container ()

    gboolean            gwy_rgba_remove_from_container      (GwyContainer *container,
                                                             const gchar *prefix);

Removes RGBA color components from a container.

This is a convenience function to remove the components in the common arrangement.

`container` : | A GwyContainer to remove the color components from.
`prefix` : | Prefix in `container`, e.g. "/0/mask" (it will remove "/0/mask/red", "/0/mask/green", etc. then).
Returns : | `TRUE` if anything was removed.

### gwy_rgba_set_gdk_gc_fg ()

    void                gwy_rgba_set_gdk_gc_fg              (const GwyRGBA *rgba,
                                                             GdkGC *gc);

Sets foreground color of a Gdk graphics context from a RGBA color.

This is a convenience wrapper around `gdk_gc_set_rgb_fg_color()`, see its documentation for details and caveats.

`rgba` : | A RGBA color. Its alpha component is ignored, only RGB is used.
`gc` : | A Gdk graphics context to set forgeground color of.

### gwy_rgba_set_gdk_gc_bg ()

    void                gwy_rgba_set_gdk_gc_bg              (const GwyRGBA *rgba,
                                                             GdkGC *gc);

Sets foreground color of a Gdk graphics context from a RGBA color.

This is a convenience wrapper around `gdk_gc_set_rgb_bg_color()`, see its documentation for details and caveats.

`rgba` : | A RGBA color. Its alpha component is ignored, only RGB is used.
`gc` : | A Gdk graphics context to set forgeground color of.