## GwyGradient

GwyGradient — A map from numbers to RGBA colors

## Synopsis

    #include <libdraw/gwydraw.h>

    #define             GWY_GRADIENT_DEFAULT
                        GwyGradientPoint;
                        GwyGradient;
                        GwyGradientClass;
    void                gwy_gradient_get_color              (GwyGradient *gradient,
                                                             gdouble x,
                                                             GwyRGBA *color);
    const guchar*       gwy_gradient_get_samples            (GwyGradient *gradient,
                                                             gint *nsamples);
    guchar*             gwy_gradient_sample                 (GwyGradient *gradient,
                                                             gint nsamples,
                                                             guchar *samples);
    void                gwy_gradient_sample_to_pixbuf       (GwyGradient *gradient,
                                                             GdkPixbuf *pixbuf);
    gint                gwy_gradient_get_npoints            (GwyGradient *gradient);
    GwyGradientPoint    gwy_gradient_get_point              (GwyGradient *gradient,
                                                             gint index_);
    void                gwy_gradient_set_point              (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyGradientPoint *point);
    void                gwy_gradient_set_point_color        (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyRGBA *color);
    void                gwy_gradient_insert_point           (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyGradientPoint *point);
    gint                gwy_gradient_insert_point_sorted    (GwyGradient *gradient,
                                                             const GwyGradientPoint *point);
    void                gwy_gradient_delete_point           (GwyGradient *gradient,
                                                             gint index_);
    void                gwy_gradient_reset                  (GwyGradient *gradient);
    const GwyGradientPoint* gwy_gradient_get_points         (GwyGradient *gradient,
                                                             gint *npoints);
    void                gwy_gradient_set_points             (GwyGradient *gradient,
                                                             gint npoints,
                                                             const GwyGradientPoint *points);
    void                gwy_gradient_set_from_samples       (GwyGradient *gradient,
                                                             gint nsamples,
                                                             const guchar *samples,
                                                             gdouble threshold);
    GwyInventory*       gwy_gradients                       (void);
    GwyGradient*        gwy_gradients_get_gradient          (const gchar *name);

## Object Hierarchy

      GObject
       +----GwyResource
             +----GwyGradient

## Description

Gradient is a map from interval [0,1] to RGB(A) color space. Each gradient is defined by an ordered set of color points, the first of them is always at 0.0, the last at 1.0 (thus each gradient must consist of at least two points). Between them, the color is interpolated. Color points of modifiable gradients (see GwyResource) can be edited with functions like `gwy_gradient_insert_point()`, `gwy_gradient_set_point_color()`, or `gwy_gradient_set_points()`.

Gradient objects can be obtained from `gwy_gradients_get_gradient()`. New gradients can be created with `gwy_inventory_new_item()` on the GwyInventory returned by `gwy_gradients()`.

## Details

### GWY_GRADIENT_DEFAULT

    #define GWY_GRADIENT_DEFAULT "Gray"

The name of the default gray color gradient.

It is guaranteed to always exist.

Note this is not the same as user's default gradient which corresponds to the default item in `gwy_gradients()` inventory and it changes over time.

### GwyGradientPoint

    typedef struct {
        gdouble x;
        GwyRGBA color;
    } GwyGradientPoint;

Gradient color point struct.

gdouble `x`; | Color point position (in interval [0,1]).
GwyRGBA `color`; | The color at position `x`.

### GwyGradient

    typedef struct _GwyGradient GwyGradient;

GwyGradient struct contains private data only and should be accessed using the functions below.

### GwyGradientClass

    typedef struct _GwyGradientClass GwyGradientClass;

GwyGradientClass does not contain any public members.

### gwy_gradient_get_color ()

    void                gwy_gradient_get_color              (GwyGradient *gradient,
                                                             gdouble x,
                                                             GwyRGBA *color);

Computes the color at a given position of a color gradient.

`gradient` : | A color gradient.
`x` : | Position in gradient, in range 0..1.
`color` : | Color to fill with interpolated color at position `x`.

### gwy_gradient_get_samples ()

    const guchar*       gwy_gradient_get_samples            (GwyGradient *gradient,
                                                             gint *nsamples);

Returns color gradient sampled to integers in GdkPixbuf-like scheme.

The returned samples are owned by `gradient` and must not be modified or freed. They are automatically updated when the gradient changes, although their number never changes. The returned pointer is valid only as long as the gradient used, indicated by `gwy_resource_use()`.

`gradient` : | A color gradient to get samples of.
`nsamples` : | A location to store the number of samples (or `NULL`).
Returns : | Sampled `gradient` as a sequence of GdkPixbuf-like RRGGBBAA quadruplets.

### gwy_gradient_sample ()

    guchar*             gwy_gradient_sample                 (GwyGradient *gradient,
                                                             gint nsamples,
                                                             guchar *samples);

Samples a gradient to an array GdkPixbuf-like samples.

If `samples` is not `NULL`, it's resized to 4*`nsamples` bytes, otherwise a new buffer is allocated.

If you don't have a reason for specific sample size (and are not going to modify the samples or otherwise dislike the automatic resampling on gradient definition change), use `gwy_gradient_get_samples()` instead. This function does not need the gradient to be in use, though.

`gradient` : | A color gradient to sample.
`nsamples` : | Required number of samples.
`samples` : | Pointer to array to be filled.
Returns : | Sampled `gradient` as a sequence of GdkPixbuf-like RRGGBBAA quadruplets.

### gwy_gradient_sample_to_pixbuf ()

    void                gwy_gradient_sample_to_pixbuf       (GwyGradient *gradient,
                                                             GdkPixbuf *pixbuf);

Samples a color gradient to a provided pixbuf.

Unlike `gwy_gradient_sample()` which simply takes samples at equidistant points this method uses supersampling and thus it gives a bit better looking gradient presentation.

`gradient` : | A color gradient to sample.
`pixbuf` : | A pixbuf to sample gradient to (in horizontal direction).

### gwy_gradient_get_npoints ()

    gint                gwy_gradient_get_npoints            (GwyGradient *gradient);

Returns the number of points in a color gradient.

`gradient` : | A color gradient.
Returns : | The number of points in `gradient`.

### gwy_gradient_get_point ()

    GwyGradientPoint    gwy_gradient_get_point              (GwyGradient *gradient,
                                                             gint index_);

Returns the point at given index of a color gradient.

`gradient` : | A color gradient.
`index_` : | Color point index in `gradient`.
Returns : | Color point at `index_`.

### gwy_gradient_set_point ()

    void                gwy_gradient_set_point              (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyGradientPoint *point);

Sets a single color point in a color gradient.

It is an error to try to move points beyond its neighbours, or to move first (or last) point from 0 (or 1).

`gradient` : | A color gradient.
`index_` : | Color point index in `gradient`.
`point` : | Color point to replace current point at `index_` with.

### gwy_gradient_set_point_color ()

    void                gwy_gradient_set_point_color        (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyRGBA *color);

Sets the color of a color gradient point without moving it.

`gradient` : | A color gradient.
`index_` : | Color point index in `gradient`.
`color` : | Color to set the point to.

### gwy_gradient_insert_point ()

    void                gwy_gradient_insert_point           (GwyGradient *gradient,
                                                             gint index_,
                                                             const GwyGradientPoint *point);

Inserts a point to a color gradient.

It is an error to try to position a outside its future neighbours, or to move the first (or last) point from 0 (or 1).

`gradient` : | A color gradient.
`index_` : | Color point index in `gradient`.
`point` : | Color point to insert at `index_`.

### gwy_gradient_insert_point_sorted ()

    gint                gwy_gradient_insert_point_sorted    (GwyGradient *gradient,
                                                             const GwyGradientPoint *point);

Inserts a point into a color gradient based on its x position.

`gradient` : | A color gradient.
`point` : | Color point to insert.
Returns : | The index `point` was inserted at.

### gwy_gradient_delete_point ()

    void                gwy_gradient_delete_point           (GwyGradient *gradient,
                                                             gint index_);

Deletes a point at given index in a color gradient.

It is not possible to delete points in gradients with less than 3 points. First and last points should not be deleted unless there's another point with `x` = 0 or `x` = 1 present.

`gradient` : | A color gradient.
`index_` : | Color point index in `gradient`.

### gwy_gradient_reset ()

    void                gwy_gradient_reset                  (GwyGradient *gradient);

Resets a gradient to the default two-point gray scale state.

`gradient` : | A color gradient.

### gwy_gradient_get_points ()

    const GwyGradientPoint* gwy_gradient_get_points         (GwyGradient *gradient,
                                                             gint *npoints);

Returns the complete set of color points of a gradient.

`gradient` : | A color gradient.
`npoints` : | A location to store the number of color points (or `NULL`).
Returns : | Complete set `gradient`'s color points. The returned array is owned by `gradient` and must not be modified or freed.

### gwy_gradient_set_points ()

    void                gwy_gradient_set_points             (GwyGradient *gradient,
                                                             gint npoints,
                                                             const GwyGradientPoint *points);

Sets the complete color gradient definition to a given set of points.

The point positions should be ordered, and first point should start at 0.0, last end at 1.0. There should be no redundant points.

`gradient` : | A color gradient.
`npoints` : | The length of `points`.
`points` : | Color points to set as new gradient definition.

### gwy_gradient_set_from_samples ()

    void                gwy_gradient_set_from_samples       (GwyGradient *gradient,
                                                             gint nsamples,
                                                             const guchar *samples,
                                                             gdouble threshold);

Reconstructs a color gradient definition from sampled colors.

The result is usually approximate.

`gradient` : | A color gradient.
`nsamples` : | Number of samples, it must be at least one.
`samples` : | Sampled color gradient in GdkPixbuf-like RRGGBBAA form.
`threshold` : | Maximum allowed difference (for color components in range 0..1). When negative, default value 1/80 suitable for most purposes is used.

### gwy_gradients ()

    GwyInventory*       gwy_gradients                       (void);

Gets inventory with all the gradients.

Returns : | Gradient inventory.

### gwy_gradients_get_gradient ()

    GwyGradient*        gwy_gradients_get_gradient          (const gchar *name);

Convenience function to get a gradient from `gwy_gradients()` by name.

`name` : | Gradient name. May be `NULL` to get the default gradient.
Returns : | Gradient identified by `name` or the default gradient if `name` does not exist.

## See Also

gwypixfield -- Drawing data with gradients, GwyInventory -- the container holding all gradients, GwyDataView -- 2D data display widget, GwyColorAxis -- false color axis widget