plot/core
src/plot/core.tur
defstruct
BBox
(defstruct BBox :copy [x-min : float x-max : float y-min : float y-max : float])
an axis-aligned data-space bounding box: what a renderer's
defn
bbox-empty?
(bbox-empty? [bb : BBox] :)
true when a BBox carries no finite extent (x-min is NaN).
defn
bbox-from-raw
(bbox-from-raw [b ptr<void>] :)
pack the raw { x0,x1,y0,y1; valid } carrier (as produced
defn
bbox-empty-box
(bbox-empty-box :)
the identity element for `bbox-union`: an empty BBox
defn
bbox-union
(bbox-union [a : BBox b : BBox] :)
the smallest box covering both inputs; an empty box is the
defn
point-bbox
(point-bbox [x : float y : float] :)
the degenerate box of one data point; empty when either
defn
hint-bbox
(hint-bbox [x0 : float x1 : float y0 : float y1 : float] :)
the box spanned by the corners (x0, y0) and (x1, y1) of an
defopaque
DrawCtx
(DrawCtx)
one plot's draw context: the canvas, the resolved data bounds,
defstruct
FrameMarks
(defstruct FrameMarks :copy [x-axis : bool y-axis : bool x-grid : bool y-grid : bool])
the axis lines and tick grids a renderer asks the frame for.
defn
no-frame-marks
(no-frame-marks :)
FrameMarks asking for nothing; what most renderers want.
defn
frame-marks-union
(frame-marks-union [a : FrameMarks b : FrameMarks] :)
the marks either side asks for.
defmacro
any-renderer
(any-renderer [x])
box a value whose type has a `Renderer` instance as an
Parameters
| x | a renderer struct (LinesR, FunctionR, ...) |
Returns
The value boxed with its `Renderer` instance, as an AnyRenderer.
Example
(any-renderer (make-struct LinesR pts (default-line-style) ""))
defn
renderer-bbox
(renderer-bbox [r : AnyRenderer] :)
the data-space bounding box of one renderer.
Parameters
| r | any renderer, as a constructor returns it |
Returns
Its `bounds`; an empty box (`bbox-empty?`) when it constrains nothing.
Example
(renderer-bbox (lines pts (default-line-style) ""))
defn
renderers-bbox
(renderers-bbox [rs : (Vec AnyRenderer)] :)
the data-space bounding box of a renderer Vec: the
Parameters
| rs | the renderers |
Returns
The union of their bounds; empty when none constrains the extent.
Example
(renderers-bbox (vec-of (axes) (lines pts (default-line-style) "")))
defn
plot-anyrenderers
(plot-anyrenderers [rs : (Vec AnyRenderer) opts : PlotOpts] :)
deprecated: `plot` takes a (Vec AnyRenderer) itself
defn
plot-into-canvas
(plot-into-canvas [canvas : int renderers : (Vec AnyRenderer) opts : PlotOpts px : int py : int pw : int ph : int] :)
render renderers into an existing canvas and viewport.
Parameters
| canvas | the plutovg canvas to draw into | |
| renderers | the renderers, as the constructors return them | |
| opts | the plot's PlotOpts | |
| px py -- the viewport's top-left corner, in canvas pixels | ||
| pw ph -- the viewport's size, in canvas pixels |
Returns
ok 0, or err 1 when the viewport is too small to hold a plot.
Example
(plot-into-canvas canvas (vec-of (axes) (lines pts ls "")) opts 0 0 600 450)
defstruct
CanvasBackend
(defstruct CanvasBackend [canvas : int px : int py : int pw : int ph : int])
defstruct
SurfaceBackend
(defstruct SurfaceBackend [width : int height : int])
defstruct
PngBackend
(defstruct PngBackend [path : cstr])
defn
render
(render [^Backend B b : B renderers : (Vec AnyRenderer) opts : PlotOpts] :)
draw `renderers` to any Backend, generic over the sink.
Example
(render (make-struct PngBackend "out.png") rs opts) (render (make-struct SurfaceBackend 0 0) rs opts)
defn
plot
(plot [renderers : (Vec AnyRenderer) opts : PlotOpts] :)
render renderers to a new surface and return it.
defn
plot-write-png
(plot-write-png [renderers : (Vec AnyRenderer) opts : PlotOpts path : cstr] :)
render renderers and write them to a PNG file.
Internal definitions
__ok-- create an ok result wrapping integer value v.__err-- create an err result wrapping integer error value e.__ok?-- predicate for the local :ptr<void> result envelope.__ok-val-- extract the ok payload from the local :ptr<void> result envelope.__err-val-- extract the err payload from the local :ptr<void> result envelope.__surface-create-- allocate a new plutovg surface.__surface-destroy-- destroy a plutovg surface.__surface-write-png-- write a plutovg surface to a PNG file.__canvas-create-- allocate a canvas for an existing surface.__canvas-destroy-- destroy a plutovg canvas.__surface-width-- width of a plutovg surface in pixels.__surface-height-- height of a plutovg surface in pixels.__surface-pixel-byte-- read a single byte from the surface's raw pixel buffer.__count-non-background-- count pixels in [x0, x1) x [y0, y1) that are not background.__pixel-is-background?-- true when a pixel is near pure white (>=250 in all RGB channels and full alpha).__store-f64-- internal: write a double through a C out-pointer.data->viewport-- map data coordinates to viewport coordinates.viewport->data-- map viewport coordinates back to data coordinates.__rbb-valid?__rbb-get__rbb-free__rbb-nan__error-bars-bbox-- bounding box of a cons-list of (x . (y . h)) error__arrows-bbox-- bounding box of a cons-list of (x1 . (y1 . (x2 . y2)))__rects-bbox-- bounding box of a cons-list of (x0 . (x1 . (y0 . y1)))__discrete-hist-bbox-- bounding box of a cons-list of (label . height)__stacked-hist-bbox-- bounding box of a cons-list of (label . values)__bbox-of-points-- the box of a (Vec Point), NaN points skipped.__bbox-of-error-bars-- the box spanning every bar's y +/- err (x +/- err__bbox-of-arrows-- the box spanning both ends of every arrow.__bbox-of-rects-- the box spanning every rectangle.__bbox-of-bars-- the box of a discrete histogram's category slots.__bbox-of-groups-- the box of a stacked histogram's category slots.__nonempty?-- is `s` a non-empty string?__one-label-- a fresh Vec holding `label`, or empty for "".__bbox-fold-- union the `bounds` of rs[i..n) into acc.__marks-fold-- union the `frame-marks` of rs[i..n) into acc.__first-categorical-- the index of the first `categorical?` renderer of__draw-fold-- `draw` each of rs[i..n), in order, telling the DrawCtx__legend-rows-- renderer i's legend rows for labels[k..m); `row` is__legend-fold-- the legend rows of rs[i..n), each renderer's__null-ptr?-- is this a null pointer?__surfaces-equal?-- true when two plutovg surfaces have identical__plot-frame-- lay out and paint one plot's frame: background, border,__ctx-track-renderers-- give the DrawCtx legend swatches for each of__ctx-drawing-- say which renderer (its index in the plot's Vec) is about__ctx-clip-begin-- clip drawing to the viewport, as the renderers draw.__ctx-clip-end-- lift the viewport clip.__legend-begin-- select the legend font, when there is a legend to draw.__ctx-text-width-- the advance width of `text` in the legend's font, inLegendSize-- how many legend rows a plot has, and its widest label.__legend-size-rows-- `acc` grown by the non-empty labels[k..m).__legend-size-- the legend rows of rs[i..n) and their widest label,__legend-box-- lay the legend out for `rows` rows whose widest label is__legend-row-- draw legend row `row`: the swatch of renderer `index`'s__ctx-finish-- hand the canvas back in the state the frame found itBackend[CanvasBackend]Backend[SurfaceBackend]Backend[PngBackend]