home | help 
KPLOT_ALLOC(3)		     Library Functions Manual		  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 la-
	     bels (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 cor-
	     rectly 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)

FreeBSD ports 15.quarterly	January 26, 2015		  KPLOT_ALLOC(3)
home | help