KPLOT_ALLOC(3)

NAME
kplot_alloc - allocate plotting context

LIBRARY
libkplot

SYNOPSIS
#include <cairo.h>
#include <kplot.h>
struct kplot *
kplot_alloc(const struct kplotcfg *cfg);

DESCRIPTION
The kplot_alloc function allocates a plotting context for later use by kplot_attach_data(3), kplot_draw(3), and so on. It must be freed with kplot_free(3). The only argument, cfg, is copied: all allocated members (e.g., clrs and Cairo pattern) are re-allocated or referenced, as the case may be, so the caller can free all memory in the meantime. The options provided via the cfg object are as follows:

extrema
    A bit-field allowing arbitrary assignment of xy-ranges: EXTREMA_XMIN, EXTREMA_XMAX, EXTREMA_YMIN, and/or EXTREMA_YMAX. This fixates the ranges unconditionally (i.e., no auto-scaling will occur and points or lines drawn outside will be clipped).

extrema_xmin
    If EXTREMA_XMIN is set, this value will be used instead of a value computed from the data.

extrema_xmax
    See extrema_xmin.

extrema_ymin
    See extrema_xmin.

extrema_ymax
    See extrema_xmin.

margin
    Bitfield of which margins to draw: MARGIN_LEFT, MARGIN_RIGHT, MARGIN_TOP, MARGIN_BOTTOM, or MARGIN_ALL.

marginsz
    The width of the margin in user-space Cairo coordinates. These are clamped to be non-negative. The margin is the space between the image boundary and the longest (or tallest) label edge, or if no label is specified on any face, the plot area.

ticlabel
    Bitfield of which labels to draw: TICLABEL_LEFT, TICLABEL_RIGHT, TICLABEL_TOP, or TICLABEL_BOTTOM.

ticlabelfont
    All font characteristics of the tic labels.

xticlabelpad
    Space between horizontal (x-axis) tic labels and the plot area. Specifically, between the edge of the longest label along any face and the plot area.

yticlabelpad
    See xticlabelpad.

xticlabelrot
    Rotation of horizontal (x-axis) labels (in radians) clamped to 90 degrees. Rotation is clockwise. Note that if this is nonzero, the tic label is aligned under the tic-mark at the top-left part of the field, instead of the middle as is the usual case.

xticlabelfmt
    This function may be user-defined for formatting the horizontal x-axis label as a UTF-8 string limited to 128 bytes (including nil terminator). It accepts three arguments: the value to format, the string buffer in which to format, and the size of the buffer. The default is to use snprintf(3) with the %g format string.

yticlabelfmt
    See xticlabelfmt.

border
    Bitfield of which borders to draw: BORDER_LEFT, BORDER_RIGHT, BORDER_TOP, BORDER_BOTTOM, or BORDER_ALL.

borderline
    The configuration of the border line. See kplot_attach_data(3) for an explanation of the line structure.

clrs
    Array of colour configurations for the colour palette. If no colours are specified, which is the default, a default palette will be installed. See kplot_attach_data(3) for a description of the colour structure.

clrsz
    The number of colours in clrs. Colour indices index into the clrs array modulo this value.

xtics
    The number of tics (and thus labels) to draw along the horizontal x-axis. The border condition (one tic) is drawn in the centre.

ytics
    See xtics.

tic Bitfield of which tics to draw: TIC_LEFT_IN, TIC_RIGHT_IN, TIC_TOP_IN, TIC_BOTTOM_IN, TIC_LEFT_OUT, TIC_RIGHT_OUT, TIC_TOP_OUT, or TIC_BOTTOM_OUT.

ticline
    The configuration of the tic line. See kplot_attach_data(3) for an explanation of the line structure.

xaxislabel
    The label for the x-axis, shown below the bottom x-axis tic labels (if specified).

x2axislabel
    The label for the second x-axis, shown above the top x-axis tic labels (if specified).

yaxislabel
    See xaxislabel.

y2axislabel
    See xaxislabel.

xaxislabelrot
    The clockwise rotation of the x-axis label. Note that this will turn around its centre, so no matter the rotation, it will be correctly buffered on both sides.

yaxislabelrot
    See xaxislabelrot.

xaxislabelpad
    The padding between the top of the x-axis label and the bottom of the x-axis tics (if specified).

yaxislabelpad
    See xaxislabelpad.

axislabelfont
    All font characteristics for the xaxislabel and yaxislabel.

grid
    Bitfield of which grid lines to draw: GRID_X, GRID_Y, or GRID_ALL.

gridline
    The configuration of grid lines.

If NULL is passed as a configuration, reasonable defaults are used.

RETURN VALUES
kplot_alloc returns NULL on memory allocation failure.

SEE ALSO
kplot(3), kplot_free(3)