KPLOT_ATTACH_DATA(3)

NAME
kplot_attach_data - assign plot data to plotting context

LIBRARY
libkplot

SYNOPSIS
#include <cairo.h>
#include <kplot.h>
int
kplot_attach_data(const struct kplot *p, struct kdata *d, enum kplottype t, const struct kdatacfg *cfg);

DESCRIPTION
The kplot_attach_data function assigns a data source d to a plotting context p, reference-counting the data source in the process. The plot style assigned to the plot is t. The style may be one of the following:

KPLOT_POINTS
    Points (really circles of a given radius).

KPLOT_MARKS
    Marks in the form of x's of a given width.

KPLOT_LINES
    Smooth lines.

KPLOT_LINESPOINTS
    A combination of KPLOT_LINES and KPLOT_POINTS.

KPLOT_LINESMARKS
    A combination of KPLOT_LINES and KPLOT_MARKS.

The options provided via the cfg object are as follows:

point
    The configuration for KPLOT_POINTS, KPLOT_MARKS, KPLOT_LINESMARKS, and KPLOT_LINESPOINTS plots.

line
    The configuration for KPLOT_LINES KPLOT_LINESMARKS and KPLOT_LINESPOINTS types.

The struct kplotline structure is arranged as follows:

sz  The diameter of the line in pixels as defined by Cairo's cairo_set_line_width(). By default, this is 1.0.

dashes
    A dash configuration as described by Cairo's cairo_set_dash() function. By default, solid lines are used.

dashesz
    See dashes.

dashoff
    See dashoff.

join
    The line join as defined by Cairo's cairo_set_line_join(). By default, use CAIRO_LINE_JOIN_ROUND.

clr The colour configuration. By default, use KPLOTCTYPE_DEFAULT.

The struct kplotpoint structure is arranged as follows:

sz  The diameter of the point line in pixels as defined by Cairo's cairo_set_line_width(). By default, this is 1.0.

radius
    The circle radius defaulting to 3.0. It is also used for the mark width.

dashes
    A dash configuration as described by Cairo's cairo_set_dash() function. By default, solid lines are used.

dashesz
    See dashes.

dashoff
    See dashoff.

clr The colour configuration. By default, use KPLOTCTYPE_DEFAULT.

Line-drawing colours are dictated by struct kplotccfg, which is defined as follows:

type
    The type of colour. If set to KPLOTCTYPE_DEFAULT (the default), the KPLOTCTYPE_RGBA option will be set during kplot_draw(3) to the index of the line in the set of lines. If KPLOTCTYPE_PALETTE, palette is used as an index into the colour palette matrix. This is clamped (modulo) to the palette size. The KPLOTCTYPE_PATTERN will have use pattern, which may not be NULL. The pattern is referenced when attached and dereferenced when the data source is removed from the plot. Lastly, KPLOTCTYPE_RGBA will use the RGBA entries (in the unit interval) of rgba to set colours. This is the preferred method, as it does not involve any dynamic memory allocation overhead.

pattern
    The pattern used with KPLOTCTYPE_PATTERN.

rgba
    The RGBA (in the unit interval) used with KPLOTCTYPE_RGBA.

palette
    The palette index used for KPLOTCTYPE_PALETTE.

If NULL is passed as a configuration, the defaults will be used.

RETURN VALUES
kplot_attach_data returns 0 if allocation of internal structures fails due to memory exhaustion. In this case, all allocations and references will be dropped.

SEE ALSO
kplot(3), kplot_attach_datas(3), kplot_attach_smooth(3)