## Pixbuf rendering

Pixbuf rendering — Draw GwyFields to GdkPixbufs

## Functions

void | gwy_draw_field_pixbuf_full ()
void | gwy_draw_field_pixbuf_with_range ()
void | gwy_draw_field_pixbuf_adaptive ()
void | gwy_map_field_adaptive ()
void | gwy_draw_field_pixbuf ()
void | gwy_draw_field_pixbuf_mask ()
void | gwy_draw_nield_pixbuf_mask ()

## Types and Values

enum | GwyColorMappingType

## Includes

    #include <libgwyui/gwyui.h>

## Description

The simpliest method to render a GwyField to a GdkPixbuf with a false colour scale is `gwy_draw_field_pixbuf_full()` which uniformly stretches the colour gradient from value minimum to maximum. Functions `gwy_draw_field_pixbuf_with_range()` and `gwy_draw_field_pixbuf_adaptive()` offer other false colour mapping possibilities. A bit different is `gwy_draw_field_pixbuf_mask()` which represents the values as opacities of a single colour.

## Functions

### gwy_draw_field_pixbuf_full()

    void
    gwy_draw_field_pixbuf_full (GdkPixbuf *pixbuf,
                                GwyField *field,
                                GwyGradient *gradient);

Renders a data field to a pixbuf with an auto-stretched colour gradient.

Minimum data value is mapped to start of `gradient` , maximum value to its end, values between are mapped linearly to `gradient` .

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
field | A data field to draw. | [transfer none]
gradient | A colour gradient to draw with. | [transfer none]

### gwy_draw_field_pixbuf_with_range()

    void
    gwy_draw_field_pixbuf_with_range (GdkPixbuf *pixbuf,
                                      GwyField *field,
                                      GwyGradient *gradient,
                                      gdouble minimum,
                                      gdouble maximum);

Renders a data field to a pixbuf with an explicit colour gradient range.

`minimum` and all smaller values are mapped to start of `gradient` , `maximum` and all greater values to its end, values between are mapped linearly to `gradient` .

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
field | A data field to draw. | [transfer none]
gradient | A colour gradient to draw with. | [transfer none]
minimum | The value corresponding to gradient start. |
maximum | The value corresponding to gradient end. |

### gwy_draw_field_pixbuf_adaptive()

    void
    gwy_draw_field_pixbuf_adaptive (GdkPixbuf *pixbuf,
                                    GwyField *field,
                                    GwyGradient *gradient);

Renders a data field to a pixbuf with a colour gradient adaptively.

The mapping from data field (minimum, maximum) range to gradient is nonlinear, deformed using inverse function to height density cummulative distribution.

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
field | A data field to draw. | [transfer none]
gradient | A colour gradient to draw with. | [transfer none]

### gwy_map_field_adaptive()

    void
    gwy_map_field_adaptive (GwyField *field,
                            const gdouble *z,
                            gdouble *mapped,
                            guint n);

Maps ordinate values to interval [0,1] as `gwy_draw_field_pixbuf_adaptive()` would do.

This is useful to find out which positions in the false colour gradient correspond to specific values.

#### Parameters

field | A data field to draw. | [transfer none]
z | Array of `n` data values to map. |
mapped | Output array of size `n` where mapped `z` values are to be stored. |
n | Number of elements in `z` and `mapped` . |

### gwy_draw_field_pixbuf()

    void
    gwy_draw_field_pixbuf (GdkPixbuf *pixbuf,
                           GwyField *field,
                           GwyGradient *gradient,
                           GwyColorMappingType mapping,
                           gdouble *minimum,
                           gdouble *maximum);

Renders a data field to a pixbuf in specified mapping mode.

The `minimum` and `maximum` arguments input values are used only in `GWY_COLOR_MAPPING_FIXED` mode. They must not be `NULL` in such case.

In all modes, the actual mapping start and end will be returned in `minimum` and `maximum` if they are not `NULL`. In `GWY_COLOR_MAPPING_FIXED` mode the range is simply preserved.

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
field | A data field to draw. | [transfer none]
gradient | A colour gradient to draw with. | [transfer none]
mapping | False colour mapping type. |
minimum | The value corresponding to gradient start. | [inout]
maximum | The value corresponding to gradient end. | [inout]

### gwy_draw_field_pixbuf_mask()

    void
    gwy_draw_field_pixbuf_mask (GdkPixbuf *pixbuf,
                                GwyField *field,
                                const GwyRGBA *color);

Renders a data field to a pixbuf as a single-colour mask with varying opacity.

Values equal or smaller to 0.0 are drawn as fully transparent, values greater or equal to 1.0 as fully opaque, values between are linearly mapped to pixel opacity.

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
field | A data field to draw. | [transfer none]
color | A colour to use. |

### gwy_draw_nield_pixbuf_mask()

    void
    gwy_draw_nield_pixbuf_mask (GdkPixbuf *pixbuf,
                                GwyNield *nield,
                                const GwyRGBA *color);

Renders a data nield to a pixbuf as a single-colour mask with varying opacity.

Values equal or smaller to 0.0 are drawn as fully transparent, values greater or equal to 1.0 as fully opaque, values between are linearly mapped to pixel opacity.

#### Parameters

pixbuf | A Gdk pixbuf to draw to. | [transfer none]
nield | A data nield to draw. | [transfer none]
color | A colour to use. |

## Types and Values

### enum GwyColorMappingType

Types of false colour gradient mapping in GwyDataView.

#### Members

GWY_COLOR_MAPPING_FULL | Colour gradient is uniformly mapped to range from data minimum to maximum. |
GWY_COLOR_MAPPING_FIXED | Colour gradient is uniformly mapped to a fixed range, independent on data. |
GWY_COLOR_MAPPING_AUTO | Colour gradient is uniformly mapped to a range inside which most of data points lie, that is height distribution tails are cut off. |
GWY_COLOR_MAPPING_ADAPT | Colour gradient is mapped nonuniformly, see `gwy_draw_field_pixbuf_adaptive()`. |