NAME

kplot_attach_data — assign plot data to plotting context

LIBRARY

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)