GwyRGBA: Gwyddion Library Reference Manual

## GwyRGBA GwyRGBA — Bit depth independent RGBA colors |

## Functions

GwyRGBA * | gwy_rgba_new ()
GwyRGBA * | gwy_rgba_copy ()
void | gwy_rgba_free ()
gboolean | gwy_rgba_equal ()
void | gwy_rgba_interpolate ()
gboolean | gwy_rgba_get_from_dict ()
void | gwy_rgba_store_to_dict ()
gboolean | gwy_rgba_remove_from_dict ()
void | gwy_rgba_to_hex6 ()
void | gwy_rgba_to_hex8 ()
guint32 | gwy_rgba_to_pixbuf_pixel ()
void | gwy_rgba_from_pixbuf_pixel ()

## Includes

    #include <libgwyddion/gwyddion.h>

## 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()`. It is registered as a serializable boxed type and can used with functions such as `gwy_dict_get_boxed()` and `gwy_dict_set_boxed()`. Helper functions for GwyDict storage by component (`gwy_rgba_store_to_dict()`, `gwy_rgba_get_from_dict()`) are also provided.

GwyRGBA is fact bit-for-bit identical to GdkRGBA form GTK+. However, the fields are named differently and libgwyddion is a non-GUI library, so it cannot use Gdk types.

## Functions

### gwy_rgba_new()

    GwyRGBA *
    gwy_rgba_new (gdouble r,
                  gdouble g,
                  gdouble b,
                  gdouble a);

Creates RGBA colour specification.

This is mostly useful for language bindings.

#### Parameters

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

#### Returns

New RGBA colour structure. The result should be freed with `gwy_rgba_free()`.

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

#### Parameters

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

#### Parameters

rgba | A RGBA color. |

### gwy_rgba_equal()

    gboolean
    gwy_rgba_equal (const GwyRGBA *rgba,
                    const GwyRGBA *other);

Checks two RGBA colours for equality.

#### Parameters

rgba | A GwyRGBA colour. |
other | Another GwyRGBA colour. |

#### Returns

`TRUE` if the two colours are identical, `FALSE` if they differ.

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

#### Parameters

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 the result to. |

### gwy_rgba_get_from_dict()

    gboolean
    gwy_rgba_get_from_dict (GwyRGBA *rgba,
                            GwyDict *dict,
                            const gchar *prefix);

Gets RGBA color components from a dictionary.

This is a convenience function to get the components in the common arrangement. GwyRGBA is a serializable boxed type and can be stored directly in GwyDict. This function is, therefore, useful for settings and legacy storage, where the components are stored individualy.

#### Parameters

rgba | A RGBA color. |
dict | A GwyDict to get the color components from. |
prefix | Prefix in `dict` , e.g. "/foo/mask" (it would try to fetch "/foo/mask/red", "/foo/mask/green", etc. then). |

#### Returns

Whether all `rgba` components were successfully found and set.

### gwy_rgba_store_to_dict()

    void
    gwy_rgba_store_to_dict (const GwyRGBA *rgba,
                            GwyDict *dict,
                            const gchar *prefix);

Stores RGBA color components to a dictionary.

This is a convenience function to store the components in the common arrangement. GwyRGBA is a serializable boxed type and can be stored directly in GwyDict. This function is, therefore, useful for settings and legacy storage, where the components are stored individualy.

#### Parameters

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

### gwy_rgba_remove_from_dict()

    gboolean
    gwy_rgba_remove_from_dict (GwyDict *dict,
                               const gchar *prefix);

Removes RGBA color components from a dictionary.

This is a convenience function to remove the components in the common arrangement. GwyRGBA is a serializable boxed type and can be stored directly in GwyDict. This function is, therefore, useful for settings and legacy storage, where the components are stored individualy.

#### Parameters

dict | A GwyDict to remove the color components from. |
prefix | Prefix in `dict` , e.g. "/foo/mask" (it will remove "/foo/mask/red", "/foo/mask/green", etc. then). |

#### Returns

`TRUE` if anything was removed.

### gwy_rgba_to_hex6()

    void
    gwy_rgba_to_hex6 (const GwyRGBA *rgba,
                      gchar *hexout);

Formats the R, G and B components of a RGBA color to hexadecimal string.

The component order is R, G and B. The output has always exactly 6 bytes and does not include any "#" prefix which is used in some contexts.

#### Parameters

rgba | A RGBA color. Its alpha component is ignored, only RGB is used. |
hexout | Buffer at least seven character long where the hexadecimal representation (e.g. "ff0000" for red) will be stored. | [out]

### gwy_rgba_to_hex8()

    void
    gwy_rgba_to_hex8 (const GwyRGBA *rgba,
                      gchar *hexout);

Formats all components of a RGBA color to hexadecimal string.

The component order is A, R, G and B. Note that while this order is a common it is by no means universal. The output has always exactly 8 bytes and does not include any "#" prefix which is used in some contexts.

#### Parameters

rgba | A RGBA color. |
hexout | Buffer at least nine character long where the hexadecimal representation (e.g. "ffff0000" for opaque red) will be stored. | [out]

### gwy_rgba_to_pixbuf_pixel()

    guint32
    gwy_rgba_to_pixbuf_pixel (const GwyRGBA *rgba);

Converts a RGBA color to pixbuf pixel.

The returned pixel value includes opacity. If `rgba` is partially transparent, so is the pixel.

#### Parameters

rgba | A RGBA color. |

#### Returns

The pixel value as a 32-bit integer.

### gwy_rgba_from_pixbuf_pixel()

    void
    gwy_rgba_from_pixbuf_pixel (GwyRGBA *rgba,
                                guint32 pixel);

Converts a pixbuf pixel value to a RGBA color.

The conversion includes opacity. If the opacity channel is undefined or should be ignored, you need to either set the lowest byte of `pixel` to 0xff or fix `rgba` afterwards.

#### Parameters

rgba | A GwyRGBA to store the result to. |
pixel | Pixbuf pixel value as a 32-bit integer. |