GwyGradient: Gwyddion Library Reference Manual

## GwyGradient GwyGradient — A map from numbers to RGBA colors |

## Functions

void | gwy_gradient_get_color ()
guchar * | gwy_gradient_sample ()
gint | gwy_gradient_get_n_points ()
GwyGradientPoint | gwy_gradient_get_point ()
void | gwy_gradient_set_point ()
void | gwy_gradient_set_point_color ()
void | gwy_gradient_insert_point ()
gint | gwy_gradient_insert_point_sorted ()
void | gwy_gradient_delete_point ()
void | gwy_gradient_reset ()
const GwyGradientPoint * | gwy_gradient_get_points ()
void | gwy_gradient_set_points ()
void | gwy_gradient_set_from_samples ()
GwyInventory * | gwy_gradients ()
GwyGradient * | gwy_gradients_get_gradient ()

## Types and Values

#define | GWY_GRADIENT_DEFAULT
| GwyGradientPoint
struct | GwyGradient
struct | GwyGradientClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyGradient

## Implemented Interfaces

GwyGradient implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

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

## Functions

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

#### Parameters

gradient | A color gradient. |
x | Position in gradient, in interval [0,1]. |
color | Color to fill with interpolated color at position `x` . |

### gwy_gradient_sample()

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

Samples a gradient to an array Gdk pixbuf-like samples.

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

#### Parameters

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 Gdk pixbuf-like RRGGBBAA quadruplets.

### gwy_gradient_get_n_points()

    gint
    gwy_gradient_get_n_points (GwyGradient *gradient);

Returns the number of points in a color gradient.

#### Parameters

gradient | A color gradient. |

#### Returns

The number of points in `gradient` .

### gwy_gradient_get_point()

    GwyGradientPoint
    gwy_gradient_get_point (GwyGradient *gradient,
                            gint i);

Returns the point at given index of a color gradient.

#### Parameters

gradient | A color gradient. |
i | Color point index in `gradient` . |

#### Returns

Color point at index `i` .

[transfer none]

### gwy_gradient_set_point()

    void
    gwy_gradient_set_point (GwyGradient *gradient,
                            gint i,
                            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).

#### Parameters

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

### gwy_gradient_set_point_color()

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

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

#### Parameters

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

### gwy_gradient_insert_point()

    void
    gwy_gradient_insert_point (GwyGradient *gradient,
                               gint i,
                               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). Consider `gwy_gradient_insert_point_sorted()` if you have the position and want the index to be determined automatically.

#### Parameters

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

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

#### Parameters

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 i);

Deletes a point at given index in a color gradient.

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

#### Parameters

gradient | A color gradient. |
i | 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.

#### Parameters

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.

#### Parameters

gradient | A color gradient. |
npoints | A location to store the number of color points (or `NULL`). | [out]

#### Returns

Complete set `gradient` 's color points. The returned array is owned by `gradient` and must not be modified or freed.

[array length=npoints]

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

#### Parameters

gradient | A color gradient. |
npoints | The length of `points` . |
points | Color points to set as new gradient definition. | [array length=npoints]

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

#### Parameters

gradient | A color gradient. |
nsamples | Number of samples, it must be at least one. |
samples | Sampled color gradient in Gdk pixbuf-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.

[transfer none]

### gwy_gradients_get_gradient()

    GwyGradient *
    gwy_gradients_get_gradient (const gchar *name);

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

#### Parameters

name | Gradient name. May be `NULL` to get the default gradient. | [nullable]

#### Returns

Gradient identified by `name` or the default gradient if `name` does not exist.

[transfer none]

## Types and Values

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

#### Members

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

### struct GwyGradient

    struct GwyGradient;

### struct GwyGradientClass

    struct GwyGradientClass {
        GwyResourceClass parent_class;
    };

## See Also

pixbuf-render --

low level functions for painting data fields, GwyInventory -- the container holding all gradients, GwyDataView -- 2D data display widget, GwyColorAxis -- false color axis widget