Documentation
¶
Overview ¶
Package raster is a two dimensional graphics engine: paths, curve flattening, an anti-aliased cell rasterizer with both fill rules, a stroker and a dasher, clip masks, pixmaps of one to four color components with an optional alpha channel, and the span pipeline over them.
It knows nothing about PDF. A color space reaches it as Model, which is three methods: how many components, and how to get to and from RGB.
Index ¶
- Constants
- Variables
- func Blur(p *Pixmap, sigmaX, sigmaY float32)
- type BlendMode
- type Blitter
- type Cap
- type FillRule
- type Flattener
- type GlyphCache
- type GlyphKey
- type Gradient
- type GradientSpec
- type Join
- type Matrix
- type Model
- type Paint
- type Path
- func (p *Path) Append(q *Path)
- func (p *Path) AsRect(m Matrix) (Rect, bool)
- func (p *Path) Bounds(m Matrix) Rect
- func (p *Path) Clone() *Path
- func (p *Path) Close()
- func (p *Path) Current() Point
- func (p *Path) CurveTo(x1, y1, x2, y2, x3, y3 float32)
- func (p *Path) CurveToV(x2, y2, x3, y3 float32)
- func (p *Path) CurveToY(x1, y1, x3, y3 float32)
- func (p *Path) Flatten(m Matrix, tol float32, f Flattener)
- func (p *Path) IsEmpty() bool
- func (p *Path) LineTo(x, y float32)
- func (p *Path) MoveTo(x, y float32)
- func (p *Path) Rect(x, y, w, h float32)
- func (p *Path) Reset()
- func (p *Path) Start() Point
- func (p *Path) StrokeBounds(s *Stroke, m Matrix) Rect
- func (p *Path) Transform(m Matrix) *Path
- func (p *Path) Walk(w Walker)
- type Pixmap
- func (p *Pixmap) BlendOver(src *Pixmap, alpha uint8, mode BlendMode)
- func (p *Pixmap) Blitter(paint Paint) Blitter
- func (p *Pixmap) Bounds() Rect
- func (p *Pixmap) Clear()
- func (p *Pixmap) ClearWhite()
- func (p *Pixmap) Comps() int
- func (p *Pixmap) Coverage() *Pixmap
- func (p *Pixmap) DrawMask(mask *Pixmap, paint Paint)
- func (p *Pixmap) FillRect(x0, y0, x1, y1 int, paint Paint)
- func (p *Pixmap) FillTriangle(v0, v1, v2 Vertex)
- func (p *Pixmap) KnockoutOver(src *Pixmap, alpha uint8)
- func (p *Pixmap) Mask(luminosity bool, table *[256]uint8) *Pixmap
- func (p *Pixmap) MaskBlitter() Blitter
- func (p *Pixmap) MulImage(src *Pixmap, inv Matrix)
- func (p *Pixmap) MulMask(m *Pixmap)
- func (p *Pixmap) Row(y int) []uint8
- func (p *Pixmap) Subsample(n int) *Pixmap
- type Point
- type Rasterizer
- func (r *Rasterizer) AddPath(p *Path, m Matrix)
- func (r *Rasterizer) Bounds() (x0, y0, x1, y1 int)
- func (r *Rasterizer) Close()
- func (r *Rasterizer) Fill(dst *Pixmap, rule FillRule, paint Paint)
- func (r *Rasterizer) FillImage(dst, src *Pixmap, inv Matrix, paint Paint, smooth bool)
- func (r *Rasterizer) FillShader(dst *Pixmap, rule FillRule, sh Shader, paint Paint)
- func (r *Rasterizer) LineTo(x, y float32)
- func (r *Rasterizer) MoveTo(x, y float32)
- func (r *Rasterizer) Reset()
- func (r *Rasterizer) SetClip(box Rect)
- func (r *Rasterizer) SetFlatness(tol float32)
- func (r *Rasterizer) SetSize(w, h int)
- func (r *Rasterizer) Sweep(rule FillRule, b Blitter)
- type Rect
- type RowShader
- type Shader
- type Shrinker
- type Stroke
- type Vertex
- type Walker
Constants ¶
const DefaultFlatness = 0.25
DefaultFlatness is how far a flattened curve may stray from the true one, in the units the path is flattened into.
const StrokeSubPixels = 32
StrokeSubPixels is SubPixels for a stroked glyph, whose two edges lie close enough together that a quarter pixel moves more coverage than under a fill.
const SubPixels = 4
SubPixels is how many phases of the glyph origin are kept apart. Snapping a glyph to whole pixels is visible as uneven spacing.
Variables ¶
var EmptyRect = Rect{1e20, 1e20, -1e20, -1e20}
EmptyRect contains nothing. Union with it is the identity.
var Identity = Matrix{1, 0, 0, 1, 0, 0}
Identity leaves a point where it is.
var InfiniteRect = Rect{-1e20, -1e20, 1e20, 1e20}
InfiniteRect is the rectangle that contains everything, used where a scissor is required but nothing is clipped.
Functions ¶
Types ¶
type BlendMode ¶
type BlendMode int
BlendMode is one of the sixteen blend functions of ISO 32000-1 11.3.5, the same set SVG and CSS use. The first twelve are separable and run one component at a time; the last four take a color as a whole, through RGB.
const ( BlendNormal BlendMode = iota BlendMultiply BlendScreen BlendOverlay BlendDarken BlendLighten BlendColorDodge BlendColorBurn BlendHardLight BlendSoftLight BlendDifference BlendExclusion BlendHue BlendSaturation BlendColor BlendLuminosity )
The separable blend modes, then the four non-separable ones.
type Blitter ¶
Blitter consumes the coverage a Rasterizer produces, one run at a time. The cover slice passed to BlitCover is reused and must not be retained.
type FillRule ¶
type FillRule int
FillRule decides which parts of a self intersecting path are inside.
type GlyphCache ¶
type GlyphCache struct {
// contains filtered or unexported fields
}
GlyphCache holds rendered glyph masks, bounded by their total size, and drops the least recently used when it is full.
func NewGlyphCache ¶
func NewGlyphCache(max int) *GlyphCache
NewGlyphCache returns a cache holding at most max bytes of masks.
func (*GlyphCache) Get ¶
func (c *GlyphCache) Get(k GlyphKey) *Pixmap
Get returns a cached mask, nil when there is none.
func (*GlyphCache) Put ¶
func (c *GlyphCache) Put(k GlyphKey, mask *Pixmap)
Put adds a mask, which the cache then owns. A nil mask records that the glyph draws nothing, which is worth remembering too.
type GlyphKey ¶
type GlyphKey struct {
Font any
GID int32
A, B, C, D float32
SubX, SubY uint8
// Stroked and the pen below it identify the outline of a glyph that is
// stroked rather than filled.
Stroked bool
Width, MiterLimit float32
StartCap, DashCap Cap
EndCap Cap
Join Join
}
GlyphKey identifies a rendered glyph mask: the font it came from, the glyph in it, the transform with the translation taken out, and the subpixel phase of the origin in quarter pixels.
type Gradient ¶
type Gradient struct {
// contains filtered or unexported fields
}
Gradient is a Shader over one of those: what a PDF type 2 or type 3 shading and an SVG linearGradient or radialGradient all evaluate to.
func NewGradient ¶
func NewGradient(s GradientSpec) *Gradient
NewGradient prepares a gradient for drawing, nil if it degenerates: an axial gradient of no length, or a transform that does not invert.
type GradientSpec ¶
type GradientSpec struct {
Matrix Matrix
LUT []uint8
// A is one opacity per entry of the table, and nil for a gradient that
// is opaque throughout. LUT is premultiplied by it.
A []uint8
N int
C0, C1 Point
R0, R1 float32
Radial bool
Ext0, Ext1 bool
}
GradientSpec describes an axial or radial gradient: the two circles it runs between (an axial one ignores the radii and runs between the points), the table of 256 colors of N components it takes its color from, the transform from its own space to the device, and whether it paints on past each end.
type Matrix ¶
type Matrix struct{ A, B, C, D, E, F float32 }
Matrix is an affine transform in PDF order: the six numbers of the cm operator, applied to a row vector, so x' = a*x + c*y + e.
func (Matrix) Expansion ¶
Expansion is the square root of the absolute determinant: how much a transform scales lengths on average, and what line width and flatness use.
func (Matrix) Invert ¶
Invert returns the inverse transform. A matrix whose inverse a float32 cannot hold inverts to the identity, which keeps a degenerate CTM from taking coordinates to infinity.
func (Matrix) MaxExpansion ¶
MaxExpansion is the largest factor any direction is scaled by.
func (Matrix) UnapplyRect ¶
UnapplyRect maps r back through the transform. The arithmetic is float64 because the answer is a difference of two products of the inverse, and under a transform that scales by a millionth those two are equal to seven figures: in float32 the whole answer is lost to the cancellation.
type Model ¶
Model is what raster needs to know about a color space: how many components it has, and how to get to and from RGB when something has to be shown or blended non separably.
type Paint ¶
type Paint struct {
// Color has the destination's N components, straight, not premultiplied.
Color []uint8
// Alpha is the constant alpha of the operation, 255 for opaque.
Alpha uint8
// Clip multiplies the coverage. It is an alpha only pixmap positioned by
// its X and Y, and nil when nothing clips.
Clip *Pixmap
}
Paint is the source color of a drawing operation and what modulates it.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path is a sequence of subpaths built from lines and cubic curves. The commands and the points are kept in two slices, which is compact and lets a path be reused across fills without reallocating.
func (*Path) AsRect ¶
AsRect reports whether the path is one subpath that maps to an axis aligned rectangle under m, and returns it. Clipping to a rectangle is exact and costs nothing, so the caller wants to know.
func (*Path) Bounds ¶
Bounds returns the bounding box of the path under m. Control points are included rather than the curve solved: the result is conservative, which is what every caller of a bounding box wants.
func (*Path) Close ¶
func (p *Path) Close()
Close closes the current subpath. Closing an already closed subpath, or one that has not begun, does nothing.
func (*Path) CurveTo ¶
CurveTo adds a cubic Bezier segment. A cubic whose control points sit on its ends is a straight line and is added as one; one that collapses onto a single point is nothing at all.
func (*Path) CurveToV ¶
CurveToV is the PDF v operator, whose first control point is the current one.
func (*Path) CurveToY ¶
CurveToY is the PDF y operator, whose second control point is its end point.
func (*Path) Flatten ¶
Flatten walks the path under m, replacing every curve by line segments that stay within tol of it. A tol of zero means DefaultFlatness.
func (*Path) LineTo ¶
LineTo adds a straight segment. A path that begins with a line has an implicit move to its first point. A line to the point the path is already at is dropped unless a move put it there, where it is a subpath of its own that a round or a square cap paints as a dot.
func (*Path) Reset ¶
func (p *Path) Reset()
Reset empties the path, keeping the memory for the next one.
func (*Path) StrokeBounds ¶
StrokeBounds returns the bounding box of the path when stroked, padded by the line width and enough for a miter join.
type Pixmap ¶
Pixmap is an interleaved 8 bit image of N color components and an optional alpha channel, premultiplied when there is one. X and Y are where its top left sample sits, and everything that composites into it works in those coordinates rather than in the pixmap's own, so that a group covering part of a page needs no transform of its own.
func (*Pixmap) BlendOver ¶
BlendOver composites src onto p. src is premultiplied, carries an alpha channel and is positioned by its own X and Y; alpha scales it, and mode is the blend function against what p already holds.
func (*Pixmap) Blitter ¶
Blitter returns a blitter that composites the paint into the pixmap under the coverage a Rasterizer produces.
func (*Pixmap) Clear ¶
func (p *Pixmap) Clear()
Clear sets every sample to zero, which is transparent when there is an alpha channel and black when there is not.
func (*Pixmap) ClearWhite ¶
func (p *Pixmap) ClearWhite()
ClearWhite sets the pixmap to opaque white, the background of a page.
func (*Pixmap) Comps ¶
Comps is how many bytes one pixel takes, which is the color components and the alpha channel when there is one.
func (*Pixmap) Coverage ¶
Coverage returns the first component of every pixel as an alpha only pixmap. A pixmap that already has one component is returned as it is.
func (*Pixmap) DrawMask ¶
DrawMask composites the paint through an alpha mask, which its own X and Y place in the destination's coordinates. This is how a glyph is stamped.
func (*Pixmap) FillRect ¶
FillRect composites a paint over a rectangle, in the coordinates the pixmap's own X and Y place it in.
func (*Pixmap) FillTriangle ¶
FillTriangle fills a triangle, interpolating color linearly between its corners, and leaves the pixels it covers opaque. It does not anti-alias, because two triangles that share an edge have to meet without a seam; a mesh is anti-aliased at its own boundary instead, when it is composited.
func (*Pixmap) KnockoutOver ¶
KnockoutOver composites src onto p the way an element of a knockout group does: where src covers a pixel it replaces what is there rather than layering over it, however little alpha it carries. alpha is the constant alpha the element was drawn with, which scales what it contributes but not how much of the backdrop it takes away.
func (*Pixmap) Mask ¶
Mask turns what a soft mask group drew into the alpha only pixmap a clip takes: the luminosity of each pixel, or the pixel's own alpha. table, when it is not nil, is a transfer function the result is read through.
func (*Pixmap) MaskBlitter ¶
MaskBlitter returns a blitter that writes coverage into an alpha only pixmap, replacing what is there. It writes in the pixmap's own coordinates, because what fills a mask has already been moved into them.
func (*Pixmap) MulImage ¶
MulImage multiplies an alpha only pixmap by the alpha of src through inv, which maps a pixel of p to one of src, and is how a stencil mask clips.
type Point ¶
type Point struct{ X, Y float32 }
Point is a position in whatever space the surrounding code is working in.
type Rasterizer ¶
type Rasterizer struct {
// contains filtered or unexported fields
}
Rasterizer turns paths into per pixel coverage. It is reused across paths: Reset, add geometry, Sweep.
func NewRasterizer ¶
func NewRasterizer(w, h int) *Rasterizer
NewRasterizer returns a rasterizer for a w by h pixel target.
func (*Rasterizer) AddPath ¶
func (r *Rasterizer) AddPath(p *Path, m Matrix)
AddPath flattens the path under m and adds it.
func (*Rasterizer) Bounds ¶
func (r *Rasterizer) Bounds() (x0, y0, x1, y1 int)
Bounds returns the pixel rectangle the accumulated geometry touches, clamped to the target. It is conservative: an edge landing exactly on a pixel boundary counts.
func (*Rasterizer) Close ¶
func (r *Rasterizer) Close()
Close closes the current subpath. Sweep closes it anyway; an explicit close only matters when more geometry follows.
func (*Rasterizer) Fill ¶
func (r *Rasterizer) Fill(dst *Pixmap, rule FillRule, paint Paint)
Fill sweeps what the rasterizer has into a pixmap under the paint. It is Sweep with the blitter Blitter returns, through one the rasterizer keeps, so that filling many paths allocates nothing.
func (*Rasterizer) FillImage ¶
func (r *Rasterizer) FillImage(dst, src *Pixmap, inv Matrix, paint Paint, smooth bool)
FillImage sweeps what the rasterizer has, reading color from src rather than from the paint. inv maps a destination pixel to a source pixel, and smooth chooses bilinear sampling over nearest.
A src with no color components is a stencil: the paint's color is painted through its alpha, which is how a one bit image mask draws.
func (*Rasterizer) FillShader ¶
func (r *Rasterizer) FillShader(dst *Pixmap, rule FillRule, sh Shader, paint Paint)
FillShader sweeps what the rasterizer has into a pixmap, taking color from sh and everything else from the paint.
func (*Rasterizer) LineTo ¶
func (r *Rasterizer) LineTo(x, y float32)
LineTo adds a segment to a device space point.
func (*Rasterizer) MoveTo ¶
func (r *Rasterizer) MoveTo(x, y float32)
MoveTo begins a subpath at a device space point.
func (*Rasterizer) Reset ¶
func (r *Rasterizer) Reset()
Reset drops the accumulated geometry, keeping the memory.
func (*Rasterizer) SetClip ¶
func (r *Rasterizer) SetClip(box Rect)
SetClip restricts rasterization to the intersection of the target and box. It is not a clip mask: geometry outside is projected onto the boundary, which is what a bounding box clip means for coverage inside it.
func (*Rasterizer) SetFlatness ¶
func (r *Rasterizer) SetFlatness(tol float32)
SetFlatness sets how far a flattened curve may stray from the true one, in pixels. Zero restores the default.
func (*Rasterizer) SetSize ¶
func (r *Rasterizer) SetSize(w, h int)
SetSize sets the target size and clears any clip box.
func (*Rasterizer) Sweep ¶
func (r *Rasterizer) Sweep(rule FillRule, b Blitter)
Sweep applies the fill rule and hands the coverage to b, scanline by scanline, top to bottom.
type Rect ¶
type Rect struct{ X0, Y0, X1, Y1 float32 }
Rect is an axis aligned rectangle. X0,Y0 is the lower left corner in PDF user space and the upper left in device space; nothing here cares which.
func (Rect) AddPoint ¶
AddPoint returns the smallest rectangle containing r and p. It is min and max with no emptiness test, so that accumulating from EmptyRect works and a rectangle that has collapsed to a line or a point still grows correctly.
func (Rect) IsInfinite ¶
IsInfinite reports whether r is the everything rectangle.
func (Rect) Normalized ¶
Normalized returns r with its corners in the expected order.
type RowShader ¶
A RowShader can write its color straight into a destination row, leaving the pixels it does not cover as they were, which a shader whose coverage is all or nothing can do instead of filling a span to be copied out of.
type Shader ¶
type Shader interface {
// Shade writes the color of w pixels starting at x, y into span: the
// destination's color components and then one alpha for each pixel,
// premultiplied by that alpha.
Shade(x, y, w int, span []uint8)
}
Shader is a source of color for the pixels a Rasterizer covers, in place of the single color a Paint carries.
type Shrinker ¶
type Shrinker struct {
// contains filtered or unexported fields
}
A Shrinker halves rows as they arrive and cascades them through as many levels as Subsample would have used, so that an image may be reduced to the size it will be drawn at without the full size pixmap ever existing. What it returns is what Subsample would have built from that pixmap, byte for byte.
The caller fills the slice Row returns and calls Commit, once per row of the source, then takes the result from Pixmap.
func NewMaskShrinker ¶
NewMaskShrinker is NewShrinker for the one byte coverage NewMask returns.
func NewShrinker ¶
NewShrinker reduces a w by h image of the model's components n times.
type Stroke ¶
type Stroke struct {
Width float32
MiterLimit float32
StartCap Cap
DashCap Cap
EndCap Cap
Join Join
DashPhase float32
Dash []float32
}
Stroke is the state the w, J, j, M and d operators set.
func DefaultStroke ¶
func DefaultStroke() Stroke
DefaultStroke is the state a content stream starts with, ISO 32000-1 table 52.
func (*Stroke) Outline ¶
Outline returns the path whose non-zero fill is the stroke of p. The path is stroked in its own space, so the caller transforms the result; scale is how much that transform magnifies lengths, and sets the flattening tolerance, the number of segments in an arc, and the width of a hairline.
func (*Stroke) OutlineInto ¶
OutlineInto is Outline writing into dst, which it empties first, so that a caller stroking many paths can keep the memory.