Documentation
¶
Overview ¶
Package canvas holds the render primitives — stage three of the pipeline. A canvas knows nothing about versions, hashes or parameters; a renderer knows nothing about output formats. Everything a renderer can draw is in the Canvas interface, and every output format implements exactly that.
Index ¶
- Constants
- func AnnularSector(c Canvas, cx, cy, r0, r1, a0, a1 float64)
- func Arc(c Canvas, cx, cy, r, a0, a1 float64)
- func ClosedCurve(c Canvas, pts []Point)
- func DrawGlyph(dst *image.RGBA, x, y int, r rune, col color.Color, scale int)
- func DrawString(dst *image.RGBA, x, y int, s string, col color.Color, scale int)
- func ReverseInPlace(pts []Point)
- func StringWidth(s string, scale int) int
- func StrokeOutline(lines [][]Point, width float64) [][]Point
- type ANSI
- func (a *ANSI) Background(col color.Color)
- func (a *ANSI) Cell(col, row int, r rune, fg, bg color.Color)
- func (a *ANSI) Close()
- func (a *ANSI) CubicTo(x1, y1, x2, y2, x, y float64)
- func (a *ANSI) Fill(col color.Color)
- func (a *ANSI) LineTo(x, y float64)
- func (a *ANSI) MoveTo(x, y float64)
- func (a *ANSI) SetGrid(cols, rows int)
- func (a *ANSI) Size() (float64, float64)
- func (a *ANSI) String() string
- func (a *ANSI) Stroke(col color.Color, width float64)
- type Canvas
- type Path
- type Point
- type Raster
- func (r *Raster) Background(col color.Color)
- func (r *Raster) Cell(col, row int, ch rune, fg, bg color.Color)
- func (r *Raster) Close()
- func (r *Raster) CubicTo(x1, y1, x2, y2, x, y float64)
- func (r *Raster) Fill(col color.Color)
- func (r *Raster) Image() *image.RGBA
- func (r *Raster) LineTo(x, y float64)
- func (r *Raster) MoveTo(x, y float64)
- func (r *Raster) SetGrid(cols, rows int)
- func (r *Raster) Size() (float64, float64)
- func (r *Raster) Stroke(col color.Color, width float64)
- type SVG
- func (s *SVG) Background(col color.Color)
- func (s *SVG) Bytes() []byte
- func (s *SVG) Cell(col, row int, r rune, fg, bg color.Color)
- func (s *SVG) Close()
- func (s *SVG) CubicTo(x1, y1, x2, y2, x, y float64)
- func (s *SVG) Fill(col color.Color)
- func (s *SVG) LineTo(x, y float64)
- func (s *SVG) MoveTo(x, y float64)
- func (s *SVG) SetGrid(cols, rows int)
- func (s *SVG) Size() (float64, float64)
- func (s *SVG) Stroke(col color.Color, width float64)
Constants ¶
const ( // GlyphW and GlyphH are the cell size of one glyph, in pixels, before // scaling. GlyphW = 5 GlyphH = 7 // GlyphAdvance is the horizontal step from one glyph to the next, // including the gap. GlyphAdvance = GlyphW + 1 )
A 5×7 bitmap font covering printable ASCII.
It is here so that the module has no dependencies. The only text this library draws is version strings on contact sheets and the character grid of the randomart renderer, so a full font stack would be a large dependency bought for a very small need — and a dependency whose glyphs could change would move the pixels of a committed gallery for no reason anyone could see.
Glyphs are written out as pictures rather than as hex, because a wrong bit in a hex table is invisible and a wrong dot here is not. A test checks that every glyph is exactly seven rows of five.
const DefaultSupersample = 3
DefaultSupersample is the oversampling factor used by NewRaster.
Variables ¶
This section is empty.
Functions ¶
func AnnularSector ¶
AnnularSector appends a closed wedge between two radii and two angles. It is the cell shape of the polar renderer, and the reason the canvas needs an arc primitive at all.
func Arc ¶
Arc appends a circular arc from angle a0 to a1, in radians, measured clockwise from the positive x axis in the canvas's y-down coordinate system. The caller must have positioned the path at the arc's start point.
The arc is split into segments of at most a quarter turn, because the cubic approximation of a circular arc only stays within a fraction of a pixel over spans that short.
func ClosedCurve ¶
ClosedCurve emits a smooth closed contour through pts using a Catmull-Rom spline converted to cubic Béziers. The caller supplies the sample points; this turns them into a curve that stays smooth at every sample rather than showing the facets of a polyline.
func DrawGlyph ¶ added in v0.2.0
DrawGlyph draws one character with its top-left corner at (x,y), scaled by an integer factor. Pixels are set opaque; there is no anti-aliasing, because a bitmap font scaled by whole pixels does not need any.
func DrawString ¶ added in v0.2.0
DrawString draws text with its top-left corner at (x,y).
func ReverseInPlace ¶
func ReverseInPlace(pts []Point)
ReverseInPlace flips a point slice. A contour drawn in reverse winds the other way, which is how a renderer punches a hole under the non-zero fill rule.
func StringWidth ¶ added in v0.2.0
StringWidth reports how wide a string will be drawn.
func StrokeOutline ¶
StrokeOutline converts polylines into fillable polygons approximating a stroke with round caps and joins.
Each segment becomes a quad and each vertex a disc, all wound in the same direction. Under the non-zero rule, overlapping same-winding polygons union, so the pieces merge into one solid stroke without any explicit join geometry. That is why the raster back end needs no real stroker.
Types ¶
type ANSI ¶
type ANSI struct {
// contains filtered or unexported fields
}
ANSI renders to a block of terminal text.
Vector drawing is supported by rasterising into a buffer twice as tall as the character grid and emitting the upper half-block character ▀ per cell: the glyph's foreground paints the top pixel and its background the bottom one, so a character cell carries two square pixels rather than one oblong one. That is what makes a terminal mark look like a mark instead of like ASCII art.
Character output from Cell is kept separately and wins over the raster, so a renderer that draws glyphs — the randomart field, for instance — gets what it asked for.
func NewANSI ¶
NewANSI returns a canvas of cols×rows character cells. When trueColor is false the output falls back to a monochrome ASCII ramp, for terminals that do not accept 24-bit colour or for NO_COLOR environments.
func (*ANSI) SetGrid ¶
SetGrid implements Canvas. The character grid is fixed at construction, so this only checks that a renderer is not asking for a different one.
type Canvas ¶
type Canvas interface {
// Size reports the drawing area in user units. The origin is top left.
Size() (w, h float64)
// Background paints the whole area. A fully transparent colour is a no-op.
Background(col color.Color)
MoveTo(x, y float64)
LineTo(x, y float64)
CubicTo(x1, y1, x2, y2, x, y float64)
// Close joins the current subpath back to its start point.
Close()
// Fill paints the accumulated path and resets it.
Fill(col color.Color)
// Stroke outlines the accumulated path and resets it.
Stroke(col color.Color, width float64)
// SetGrid declares a character grid. Renderers that draw with Cell must
// call it before their first Cell; vector back ends use it to derive cell
// metrics, and character back ends to size their buffer.
SetGrid(cols, rows int)
// Cell writes a single character. Canvases that cannot draw text may
// ignore it, but all back ends here honour it.
Cell(col, row int, r rune, fg, bg color.Color)
}
Canvas is a drawing target. Paths are built with MoveTo/LineTo/CubicTo and consumed by Fill or Stroke, which reset the path.
Filling always uses the non-zero winding rule. A renderer that wants a hole emits the inner contour with the opposite orientation to the outer one; no even-odd mode exists, because the raster back end has no efficient way to provide one and the winding trick covers every case the renderers need.
Strokes always use round caps and round joins. Every renderer here draws organic curves or arcs where that is the right choice, so it is fixed rather than configurable.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path accumulates geometry for both back ends. It is exported so that other packages in the module can build geometry once and hand it to any canvas.
func (*Path) Flatten ¶
Flatten converts the path to polylines. Closed subpaths repeat their start point as the final point, so a consumer can treat every polyline uniformly.
type Point ¶
type Point struct{ X, Y float64 }
Point is a coordinate pair.
func Simplify ¶
Simplify reduces a polyline with the Ramer–Douglas–Peucker algorithm, keeping every point that lies further than tol from the retained chord.
Renderers that sample an analytic curve need a dense sample to catch its sharp features, but emitting every sample would make the SVG an order of magnitude larger than it needs to be. Simplifying afterwards keeps the detail where the curve actually bends and throws away the rest.
type Raster ¶
type Raster struct {
// contains filtered or unexported fields
}
Raster is a pixel canvas backed by an anti-aliased scanline rasteriser. It shares the Path model with SVG, so a renderer draws once and both back ends agree on the geometry.
Supersampling is applied because the rasteriser anti-aliases coverage but not the thin, densely packed strokes the flow-field renderer produces; at 1:1 those alias into moiré.
func NewRasterSS ¶
NewRasterSS returns a canvas of w×h pixels rendered at ss× internally and box-filtered down by Image.
func (*Raster) Background ¶
Background implements Canvas.
func (*Raster) Cell ¶
Cell implements Canvas using the built-in bitmap font. It exists so that the character renderers still produce an image for the gallery, not because anyone should prefer a PNG of a terminal mark over the terminal itself.
func (*Raster) Image ¶
Image returns the finished image, box-filtered down from the supersampled buffer.
type SVG ¶
type SVG struct {
// contains filtered or unexported fields
}
SVG is a vector canvas. It builds markup directly with no dependencies, and formats every coordinate to a fixed number of decimals so that the same input always yields byte-identical output.
Source Files