DESCRIPTION
The
kplot library plots 2d data and functions on Cairo drawing contexts. The library usually works as follows.
-
Allocate plot data sources with kdata_array_alloc(3), kdata_bucket_alloc(3), kdata_buffer_alloc(3), kdata_hist_alloc(3), kdata_mean_alloc(3), kdata_stddev_alloc(3), and kdata_vector_alloc(3). Arrays and buckets have integral pair positions, differing in that buckets linearly translate position requests into internal storage. Histograms map from a range of floating-point pair positions into internal storage. Buffers cannot be directly modified, and are instead copied from other sources. Mean and standard deviation sources attach to other sources and compute the mean and standard deviation as their values change.
-
Modify using data source's individual functions or the generic kdata_get(3).
-
Allocate plots with kplot_alloc(3).
-
Associated each plot data source with one or more plot using kplot_attach_data(3) kplot_attach_datas(3), or kplot_attach_smooth(3). Plot data sources are added by reference; thus, they may be referenced by multiple plots.
-
Draw plots to Cairo contexts with kplot_draw(3).
-
Free plots with kplot_free(3) and data sources with kdata_destroy(3).
Domain and Range
Each plot domain and range is extended to fit all of its data sources at the moment
kplot_draw(3) is invoked.
Styles
Styles are applied to plots and when a plot data source is added to a plot. Thus, if one has a data source referenced by two separate plots, they may be styled in different ways.
Numerical Precision
All values in
kplot are double-precision floating-point, though some (such as
kdata_mean_alloc(3)) will use the
size_t integral type for internal counters. If a plot is handed non-normal numbers (infinite, subnormal, NaN), the entire coordinate pair is discarded from range/domain calculation and plotting.
Drawing Model
There are two main components to the drawing model: the plot area and the buffer zone.
The plot area consists of the plotted curves and overlapping borders and axis tics. Each border centre is drawn at the graph edge, so half the border width will extend into the plot. (This is how Cairo draws its lines.) Moreover, tics, if facing inward, will also (and obviously) be part of the plot area.
The buffer zone consists of the other half of borders, outward-facing tics, tic labels, axis labels, and the margin. The vertical (left and right) margins define the space between the left-most (or right-most) vertical axis label point and the image edge, or if labels have been specified, the same for those labels. Similarly, the horizontal margins define the space beyond the top-most (or bottom-most) horizontal axis label point.
The space around the plot area for labels takes into account horizontal labels flowing into the vertical label space and vice versa.
Borders and tics are not considered when measuring the buffer zone. Thus, a margin of zero will directly abut the plot area.
Memory Model
kplot uses the usual libc memory functions for allocation. However, plot data sources are reference-counted to make sharing between plots easier. Thus, calling
kdata_destroy(3) will dereference, only freeing when nobody references the source.