GwyGradient

GwyGradient — A map from numbers to RGBA colors.

Synopsis




#define     GWY_GRADIENT_DEFAULT
            GwyGradientPoint;
void        (*GwyGradientFunc)              (const gchar *name,
                                             GwyGradient *gradient,
                                             gpointer user_data);
            GwyGradient;
            GwyGradientClass;
const gchar* gwy_gradient_get_name          (GwyGradient *gradient);
gboolean    gwy_gradient_get_modifiable     (GwyGradient *gradient);
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);
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_,
                                             GwyGradientPoint *point);
gint        gwy_gradient_insert_point_sorted
                                            (GwyGradient *gradient,
                                             GwyGradientPoint *point);
void        gwy_gradient_delete_point       (GwyGradient *gradient,
                                             gint index_);
void        gwy_gradient_reset              (GwyGradient *gradient);
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,
                                             guchar *samples);
GString*    gwy_gradient_dump               (GwyGradient *gradient);
GwyGradient* gwy_gradient_parse             (const gchar *text);
gboolean    gwy_gradients_gradient_exists   (const gchar *name);
GwyGradient* gwy_gradients_get_gradient     (const gchar *name);
void        gwy_gradients_foreach           (GwyGradientFunc function,
                                             gpointer user_data);

Object Hierarchy


  GObject
   +----GwyGradient

Implemented Interfaces

GwyGradient implements GwySerializable.

Signal Prototypes


"data-changed"
            void        user_function      (GwyGradient *gwygradient,
                                            gpointer user_data);

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 below) 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_gradients_new_gradient() and gwy_gradients_new_gradient_as_copy(). However, GwyGradient objects are more or less singletons, all gradients of the same name are normally the same objects (the only exception are gradients that survived gwy_gradients_delete_gradient(), see its desciption for more). Normally you don't need to care about this, except that you have to excplicitely add your reference to a gradient returned by some of above functions.

Some gradients are predefined and cannot be modified and deleted (most notably "Gray" gradient), gradients created by gwy_gradients_new_gradient() and gwy_gradients_new_gradient_as_copy() are modifiable; the state can be queried with gwy_gradient_is_modifiable().

Details

GWY_GRADIENT_DEFAULT

#define GWY_GRADIENT_DEFAULT "Gray"

Default gradient name.

The default grayscale gradient is guaranteed to always exist (once libgwydraw was initialized with gwy_draw_type_init(), that is).


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.

GwyGradientFunc ()

void        (*GwyGradientFunc)              (const gchar *name,
                                             GwyGradient *gradient,
                                             gpointer user_data);

The type of function passed to gwy_gradients_foreach().

It is called for each gradient in sequence and must not delete or create gradients.

name : Gradient name.
gradient : Gradient.
user_data : User data passed to gwy_gradients_foreach().

GwyGradient

typedef struct _GwyGradient GwyGradient;

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


GwyGradientClass

typedef struct {
    GObjectClass parent_class;

    GHashTable *gradients;

    void (*data_changed)(GwyGradient *gradient);

    gpointer reserved1;
    gpointer reserved2;
} GwyGradientClass;


gwy_gradient_get_name ()

const gchar* gwy_gradient_get_name          (GwyGradient *gradient);

Returns color gradient name.

gradient : A color gradient.
Returns : Name of gradient. The string is owned by gradient and must not be modfied or freed.

gwy_gradient_get_modifiable ()

gboolean    gwy_gradient_get_modifiable     (GwyGradient *gradient);

Returns whether a color gradient is modifiable.

It is an error to try to insert, delete, or set points in fixed (system) gradients, or to try to delete them.

gradient : A color gradient.
Returns : TRUE if gradient is modifiable, FALSE if it's system gradient.

gwy_gradient_get_color ()

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

Computes color at 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. Their contents changes when the gradient changes, although their number never changes. The returned pointer is valid only during gradient lifetime, for system gradient it means practically always, but user-defined gradients may be destroyed.

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

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_get_npoints ()

gint        gwy_gradient_get_npoints        (GwyGradient *gradient);

Returns the number of points in a 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 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 is 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 a color of 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_,
                                             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 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,
                                             GwyGradientPoint *point);

Inserts a point into 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 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 default two-point gray scale.

gradient : A color gradient.

gwy_gradient_get_points ()

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 complete color gradient definition to 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,
                                             guchar *samples);

Reconstructs color gradient definition from sampled colors.

The result is usually approximate.

gradient : A color gradient.
nsamples : Number of samples.
samples : Sampled color gradient in GdkPixbuf-like RRGGBBAA form.

gwy_gradient_dump ()

GString*    gwy_gradient_dump               (GwyGradient *gradient);

Dumps text a color gradient definition.

gradient : A color gradient.
Returns : A GString with gradient text representation.

gwy_gradient_parse ()

GwyGradient* gwy_gradient_parse             (const gchar *text);

Creates a color gradient from a text dump.

This function fails if the gradient already exists.

text : A color gradient definition dump, as created with gwy_gradient_dump().
Returns : The reconstructed gradient.

gwy_gradients_gradient_exists ()

gboolean    gwy_gradients_gradient_exists   (const gchar *name);

Checks whether a color gradient exists.

name : Color gradient name.
Returns : TRUE if gradient name exists, FALSE if there's no such gradient.

gwy_gradients_get_gradient ()

GwyGradient* gwy_gradients_get_gradient     (const gchar *name);

Returns gradient of given name.

Its reference count is not increased, if you want the gradient object to survive gwy_gradients_delete_gradient(), you have to add a reference yourself.

name : Color gradient name.
Returns : Color gradient name if it exists, NULL if there's no such gradient.

gwy_gradients_foreach ()

void        gwy_gradients_foreach           (GwyGradientFunc function,
                                             gpointer user_data);

Calls a function for each color gradient.

Note the function must not delete or create gradients.

function : Function to call on each color gradient.
user_data : Data to pass as user_data to function.

Signals

The "data-changed" signal

void        user_function                  (GwyGradient *gwygradient,
                                            gpointer user_data);

gwygradient :the object which received the signal.
user_data :user data set when the signal handler was connected.