paint

Documentation

Overview

Package paint is the rendering package for Cogent Core.

The Painter provides the rendering state, styling parameters, and methods for painting. It accumulates all painting actions in a render.Render list, which should be obtained by a call to the [Painter.RenderDone] method when done painting (resets list to start fresh). Pass this render.Render list to one or more render.Renderers to actually generate the resulting output. Renderers are independent of the Painter and the render.Render state is entirely self-contained, so rendering can be done in a separate goroutine etc.

You must import _ "cogentcore.org/core/paint/renderers" to get the default renderers if using this outside of core which already does this for you. This sets the New*Renderer functions to point to default implementations.

Index

• Variables
• func ClampBorderRadius(r sides.Floats, w, h float32) sides.Floats
• func EdgeBlurFactors(sigma, radiusFactor float32) []float32
• func RenderToImage(pc *Painter) image.Image
• func RenderToPDF(pc *Painter) []byte
• func RenderToSVG(pc *Painter) []byte
• type Painter
  • func NewPainter(size math32.Vector2) *Painter
  • func (pc *Painter) ArcTo(rx, ry, rot float32, large, sweep bool, x, y float32)
  • func (pc *Painter) BeveledRectangle(x, y, w, h, r float32)
  • func (pc *Painter) BlitBox(pos, size math32.Vector2, img image.Image)
  • func (pc *Painter) BlurBox(pos, size math32.Vector2, blurRadius float32)
  • func (pc *Painter) Border(x, y, w, h float32, bs styles.Border)
  • func (pc *Painter) BoundingBox(minX, minY, maxX, maxY float32) image.Rectangle
  • func (pc *Painter) BoundingBoxFromPoints(points []math32.Vector2) image.Rectangle
  • func (pc *Painter) Circle(cx, cy, r float32)
  • func (pc *Painter) CircularArc(x, y, r, theta0, theta1 float32)
  • func (pc *Painter) Clear()
  • func (pc *Painter) Close()
  • func (pc *Painter) CubeTo(cp1x, cp1y, cp2x, cp2y, x, y float32)
  • func (pc *Painter) Cumulative() math32.Matrix2
  • func (pc *Painter) Draw()
  • func (pc *Painter) DrawBox(pos, size math32.Vector2, img image.Image, op draw.Op)
  • func (pc *Painter) DrawImage(src image.Image, rect image.Rectangle, srcStart image.Point, op draw.Op) *pimage.Params
  • func (pc *Painter) DrawImageAnchored(src image.Image, x, y, ax, ay float32) *pimage.Params
  • func (pc *Painter) DrawImageScaled(src image.Image, x, y, w, h float32) *pimage.Params
  • func (pc *Painter) DrawText(tx *shaped.Lines, pos math32.Vector2)
  • func (pc *Painter) Ellipse(cx, cy, rx, ry float32)
  • func (pc *Painter) EllipticalArc(x, y, rx, ry, rot, theta0, theta1 float32)
  • func (pc *Painter) FillBox(pos, size math32.Vector2, img image.Image)
  • func (pc *Painter) Grid(x, y, w, h float32, nx, ny int, r float32)
  • func (pc *Painter) Line(x1, y1, x2, y2 float32)
  • func (pc *Painter) LineTo(x, y float32)
  • func (pc *Painter) MoveTo(x, y float32)
  • func (pc *Painter) Polygon(points ...math32.Vector2)
  • func (pc *Painter) PolygonPx(points ...math32.Vector2)
  • func (pc *Painter) Polyline(points ...math32.Vector2)
  • func (pc *Painter) PolylinePx(points ...math32.Vector2)
  • func (pc *Painter) QuadTo(cpx, cpy, x, y float32)
  • func (pc *Painter) Rectangle(x, y, w, h float32)
  • func (pc *Painter) RegularPolygon(x, y float32, n int, r float32, up bool)
  • func (pc *Painter) RegularStarPolygon(x, y float32, n, d int, r float32, up bool)
  • func (pc *Painter) RoundedRectangle(x, y, w, h, r float32)
  • func (pc *Painter) RoundedRectangleSides(x, y, w, h float32, r sides.Floats)
  • func (pc *Painter) RoundedShadowBlur(blurSigma, radiusFactor, x, y, w, h float32, r sides.Floats)
  • func (pc *Painter) SetMask(mask *image.Alpha) error
  • func (pc *Painter) SetPixel(x, y int)
  • func (pc *Painter) StandardBox(st *styles.Style, pos math32.Vector2, size math32.Vector2, pabg image.Image)
  • func (pc *Painter) StarPolygon(x, y float32, n int, R, r float32, up bool)
  • func (pc *Painter) Triangle(x, y, r float32)
• type State
  • func (rs *State) Context() *render.Context
  • func (rs *State) Init(sty *styles.Paint, size math32.Vector2)
  • func (rs *State) PopContext()
  • func (rs *State) PushContext(sty *styles.Paint, bounds *render.Bounds) *render.Context
  • func (rs *State) RenderDone() render.Render

Variables

var (
	// NewSourceRenderer returns the [composer.Source] renderer
	// for [Painter] rendering, for the current platform.
	NewSourceRenderer func(size math32.Vector2) render.Renderer

	// NewImageRenderer returns a painter renderer for generating
	// images locally in Go regardless of platform.
	NewImageRenderer func(size math32.Vector2) render.Renderer

	// NewSVGRenderer returns a structured SVG renderer that can
	// generate an SVG vector graphics document from painter content.
	NewSVGRenderer func(size math32.Vector2) render.Renderer

	// NewPDFRenderer returns a PDF renderer that can
	// generate a PDF document from painter content.
	NewPDFRenderer func(size math32.Vector2, un *units.Context) render.Renderer
)

Functions

func ClampBorderRadius

func ClampBorderRadius(r sides.Floats, w, h float32) sides.Floats

ClampBorderRadius returns the given border radius clamped to fit based on the given width and height of the object.

func EdgeBlurFactors

func EdgeBlurFactors(sigma, radiusFactor float32) []float32

EdgeBlurFactors returns multiplicative factors that replicate the effect of a Gaussian kernel applied to a sharp edge transition in the middle of a line segment, with a given Gaussian sigma, and radius = sigma * radiusFactor. The returned line factors go from -radius to +radius. For low-contrast (opacity) cases, radiusFactor = 1 works well, because values beyond 1 sigma are effectively invisible, but 2 looks better for greater contrast cases.

func RenderToImage

func RenderToImage(pc *Painter) image.Image

RenderToImage is a convenience function that renders the current accumulated painter actions to an image using a NewImageRenderer, and returns the Image() call from that renderer. The image is wrapped by imagex.WrapJS so that it is ready to be used efficiently for subsequent rendering actions on the JS (web) platform.

func RenderToPDF

func RenderToPDF(pc *Painter) []byte

RenderToPDF is a convenience function that renders the current accumulated painter actions to a PDF document using a NewPDFRenderer

func RenderToSVG

func RenderToSVG(pc *Painter) []byte

RenderToSVG is a convenience function that renders the current accumulated painter actions to an SVG document using a NewSVGRenderer

Types

type Painter

type Painter struct {
	*State
	*styles.Paint
}

Painter provides the rendering state, styling parameters, and methods for painting. It accumulates all painting actions in a render.Render list, which should be obtained by a call to the [Painter.RenderDone] method when done painting (resets list to start fresh).

Pass this render.Render list to one or more render.Renderers to actually generate the resulting output. Renderers are independent of the Painter and the render.Render state is entirely self-contained, so rendering can be done in a separate goroutine etc.

You must import _ "cogentcore.org/core/paint/renderers" to get the default renderers if using this outside of core which already does this for you. This sets the New*Renderer functions to point to default implementations.

func NewPainter

func NewPainter(size math32.Vector2) *Painter

NewPainter returns a new Painter with default styles and given size.

func (*Painter) ArcTo

func (pc *Painter) ArcTo(rx, ry, rot float32, large, sweep bool, x, y float32)

ArcTo adds an arc with radii rx and ry, with rot the counter clockwise rotation with respect to the coordinate system in radians, large and sweep booleans (see https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths#Arcs), and (x,y) the end position of the pen. The start position of the pen was given by a previous command's end point.

func (*Painter) BeveledRectangle

func (pc *Painter) BeveledRectangle(x, y, w, h, r float32)

BeveledRectangle adds a rectangle of width w and height h with beveled corners at distance r from the corner.

func (*Painter) BlitBox

func (pc *Painter) BlitBox(pos, size math32.Vector2, img image.Image)

BlitBox performs an optimized overwriting fill (blit) of the given rectangular region with the given image. It is equivalent to Painter.DrawBox with draw.Src.

func (*Painter) BlurBox

func (pc *Painter) BlurBox(pos, size math32.Vector2, blurRadius float32)

BlurBox blurs the given already drawn region with the given blur radius. The blur radius passed to this function is the actual Gaussian standard deviation (σ). This means that you need to divide a CSS-standard blur radius value by two before passing it this function (see https://stackoverflow.com/questions/65454183/how-does-blur-radius-value-in-box-shadow-property-affect-the-resulting-blur).

func (*Painter) Border

func (pc *Painter) Border(x, y, w, h float32, bs styles.Border)

Border is a higher-level function that draws, strokes, and fills an potentially rounded border box with the given position, size, and border styles.

func (*Painter) BoundingBox

func (pc *Painter) BoundingBox(minX, minY, maxX, maxY float32) image.Rectangle

BoundingBox computes the bounding box for an element in pixel int coordinates, applying current transform

func (*Painter) BoundingBoxFromPoints

func (pc *Painter) BoundingBoxFromPoints(points []math32.Vector2) image.Rectangle

BoundingBoxFromPoints computes the bounding box for a slice of points

func (*Painter) Circle

func (pc *Painter) Circle(cx, cy, r float32)

Circle adds a circle at given center coordinates of radius r.

func (*Painter) CircularArc

func (pc *Painter) CircularArc(x, y, r, theta0, theta1 float32)

CircularArc adds a circular arc centered at given coordinates with radius r and theta0 and theta1 as the angles in degrees of the ellipse (before rot is applied) between which the arc will run. If theta0 < theta1, the arc will run in a CCW direction. If the difference between theta0 and theta1 is bigger than 360 degrees, one full circle will be drawn and the remaining part of diff % 360, e.g. a difference of 810 degrees will draw one full circle and an arc over 90 degrees.

func (*Painter) Clear

func (pc *Painter) Clear()

Clear fills the entire image with the current fill color.

func (*Painter) Close

func (pc *Painter) Close()

Close closes a (sub)path with a LineTo to the start of the path (the most recent MoveTo command). It also signals the path closes as opposed to being just a LineTo command, which can be significant for stroking purposes for example.

func (*Painter) CubeTo

func (pc *Painter) CubeTo(cp1x, cp1y, cp2x, cp2y, x, y float32)

CubeTo adds a cubic Bézier path with control points (cpx1,cpy1) and (cpx2,cpy2) and end point (x,y).

func (*Painter) Cumulative

func (pc *Painter) Cumulative() math32.Matrix2

Cumulative returns the current cumulative transform function, including the current transform.

func (*Painter) Draw

func (pc *Painter) Draw()

Draw puts the current path on the render stack, capturing the style settings present at this point, which will be used to render the path, and creates a new current path.

func (*Painter) DrawBox

func (pc *Painter) DrawBox(pos, size math32.Vector2, img image.Image, op draw.Op)

DrawBox performs an optimized fill/blit of the given rectangular region with the given image, using the given draw operation. If the image is nil, a new transparent color is used.

func (*Painter) DrawImage

func (pc *Painter) DrawImage(src image.Image, rect image.Rectangle, srcStart image.Point, op draw.Op) *pimage.Params

DrawImage draws the given image at the specified starting point, using the bounds of the source image in rectangle rect, using the given draw operration: Over = overlay (alpha blend with destination) Src = copy source directly, overwriting destination pixels.

func (*Painter) DrawImageAnchored

func (pc *Painter) DrawImageAnchored(src image.Image, x, y, ax, ay float32) *pimage.Params

DrawImageAnchored draws the specified image at the specified anchor point. The anchor point is x - w * ax, y - h * ay, where w, h is the size of the image. Use ax=0.5, ay=0.5 to center the image at the specified point.

func (*Painter) DrawImageScaled

func (pc *Painter) DrawImageScaled(src image.Image, x, y, w, h float32) *pimage.Params

DrawImageScaled draws the specified image starting at given upper-left point, such that the size of the image is rendered as specified by w, h parameters (an additional scaling is applied to the transform matrix used in rendering)

func (*Painter) DrawText

func (pc *Painter) DrawText(tx *shaped.Lines, pos math32.Vector2)

DrawText adds given shaped text lines to the rendering list, at given position. Note that all rendering is subject to the current active transform, including the position: e.g., use math32.Rotate2DAround to just rotate the text at a given absolute position offset.

func (*Painter) Ellipse

func (pc *Painter) Ellipse(cx, cy, rx, ry float32)

Ellipse adds an ellipse at given center coordinates of radii rx and ry.

func (*Painter) EllipticalArc

func (pc *Painter) EllipticalArc(x, y, rx, ry, rot, theta0, theta1 float32)

EllipticalArc adds an elliptical arc centered at given coordinates with radii rx and ry, with rot the counter clockwise rotation in degrees, and theta0 and theta1 the angles in degrees of the ellipse (before rot is applied) between which the arc will run. If theta0 < theta1, the arc will run in a CCW direction. If the difference between theta0 and theta1 is bigger than 360 degrees, one full circle will be drawn and the remaining part of diff % 360, e.g. a difference of 810 degrees will draw one full circle and an arc over 90 degrees.

func (*Painter) FillBox

func (pc *Painter) FillBox(pos, size math32.Vector2, img image.Image)

FillBox performs an optimized fill of the given rectangular region with the given image. It is equivalent to Painter.DrawBox with draw.Over.

func (*Painter) Grid

func (pc *Painter) Grid(x, y, w, h float32, nx, ny int, r float32)

Grid returns a stroked grid of width w and height h, with grid line thickness r, and the number of cells horizontally and vertically as nx and ny respectively.

func (*Painter) Line

func (pc *Painter) Line(x1, y1, x2, y2 float32)

Line adds a separate line (MoveTo, LineTo).

func (*Painter) LineTo

func (pc *Painter) LineTo(x, y float32)

LineTo adds a line segment to the current path starting at the current point. If there is no current point, it is equivalent to MoveTo(x, y)

func (*Painter) MoveTo

func (pc *Painter) MoveTo(x, y float32)

MoveTo starts a new subpath within the current path starting at the specified point.

func (*Painter) Polygon

func (pc *Painter) Polygon(points ...math32.Vector2)

Polygon adds multiple connected lines with a final Close.

func (*Painter) PolygonPx

func (pc *Painter) PolygonPx(points ...math32.Vector2)

Polygon adds multiple connected lines with a final Close, with coordinates in Px units.

func (*Painter) Polyline

func (pc *Painter) Polyline(points ...math32.Vector2)

Polyline adds multiple connected lines, with no final Close.

func (*Painter) PolylinePx

func (pc *Painter) PolylinePx(points ...math32.Vector2)

Polyline adds multiple connected lines, with no final Close, with coordinates in Px units.

func (*Painter) QuadTo

func (pc *Painter) QuadTo(cpx, cpy, x, y float32)

QuadTo adds a quadratic Bézier path with control point (cpx,cpy) and end point (x,y).

func (*Painter) Rectangle

func (pc *Painter) Rectangle(x, y, w, h float32)

Rectangle adds a rectangle of width w and height h at position x,y.

func (*Painter) RegularPolygon

func (pc *Painter) RegularPolygon(x, y float32, n int, r float32, up bool)

RegularPolygon adds a regular polygon with radius r. It uses n vertices/edges, so when n approaches infinity this will return a path that approximates a circle. n must be 3 or more. The up boolean defines whether the first point will point upwards or downwards.

func (*Painter) RegularStarPolygon

func (pc *Painter) RegularStarPolygon(x, y float32, n, d int, r float32, up bool)

RegularStarPolygon adds a regular star polygon with radius r. It uses n vertices of density d. This will result in a self-intersection star in counter clockwise direction. If n/2 < d the star will be clockwise and if n and d are not coprime a regular polygon will be obtained, possible with multiple windings. n must be 3 or more and d 2 or more. The up boolean defines whether the first point will point upwards or downwards.

func (*Painter) RoundedRectangle

func (pc *Painter) RoundedRectangle(x, y, w, h, r float32)

RoundedRectangle adds a rectangle of width w and height h with rounded corners of radius r at postion x,y. A negative radius will cast the corners inwards (i.e. concave).

func (*Painter) RoundedRectangleSides

func (pc *Painter) RoundedRectangleSides(x, y, w, h float32, r sides.Floats)

RoundedRectangleSides adds a standard rounded rectangle with a consistent border and with the given x and y position, width and height, and border radius for each corner.

func (*Painter) RoundedShadowBlur

func (pc *Painter) RoundedShadowBlur(blurSigma, radiusFactor, x, y, w, h float32, r sides.Floats)

RoundedShadowBlur draws a standard rounded rectangle with a consistent border and with the given x and y position, width and height, and border radius for each corner. The blurSigma and radiusFactor args add a blurred shadow with an effective Gaussian sigma = blurSigma, and radius = radiusFactor * sigma. This shadow is rendered around the given box size up to given radius. See EdgeBlurFactors for underlying blur factor code. Using radiusFactor = 1 works well for weak shadows, where the fringe beyond 1 sigma is essentially invisible. To match the CSS standard, you then pass blurSigma = blur / 2, radiusFactor = 1. For darker shadows, use blurSigma = blur / 2, radiusFactor = 2, and reserve extra space for the full shadow. The effective blurRadius is clamped to be <= w-2 and h-2.

func (*Painter) SetMask

func (pc *Painter) SetMask(mask *image.Alpha) error

SetMask allows you to directly set the *image.Alpha to be used as a clipping mask. It must be the same size as the context, else an error is returned and the mask is unchanged.

func (*Painter) SetPixel

func (pc *Painter) SetPixel(x, y int)

SetPixel sets the color of the specified pixel using the current stroke color.

func (*Painter) StandardBox

func (pc *Painter) StandardBox(st *styles.Style, pos math32.Vector2, size math32.Vector2, pabg image.Image)

StandardBox draws the CSS standard box model using the given styling information, position, size, and parent actual background. This is used for rendering widgets such as buttons, text fields, etc in a GUI.

func (*Painter) StarPolygon

func (pc *Painter) StarPolygon(x, y float32, n int, R, r float32, up bool)

StarPolygon returns a star polygon of n points with alternating radius R and r. The up boolean defines whether the first point will be point upwards or downwards.

func (*Painter) Triangle

func (pc *Painter) Triangle(x, y, r float32)

Triangle adds a triangle of radius r pointing upwards.

type State

type State struct {
	// Size in dots (true pixels) as specified during Init.
	Size math32.Vector2

	// Stack provides the SVG "stacking context" as a stack of [Context]s.
	// There is always an initial base-level Context element for the overall
	// rendering context.
	Stack []*render.Context

	// Render holds the current [render.PaintRender] state that we are building.
	// and has the list of [render.Renderer]s that we render to.
	Render render.Render

	// Path is the current path state we are adding to.
	Path ppath.Path
}

The State holds all the current rendering state information used while painting. The [Paint] embeds a pointer to this.

func (*State) Context

func (rs *State) Context() *render.Context

Context() returns the currently active render.Context state (top of Stack).

func (*State) Init

func (rs *State) Init(sty *styles.Paint, size math32.Vector2)

Init initializes the rendering state, creating a new Stack with an initial baseline context using given size and styles. Size is used to set the bounds for clipping rendering, assuming units are image dots (true pixels), which is typical. This should be called whenever the size changes.

func (*State) PopContext

func (rs *State) PopContext()

PopContext pops the current Context off of the Stack.

func (*State) PushContext

func (rs *State) PushContext(sty *styles.Paint, bounds *render.Bounds) *render.Context

PushContext pushes a new render.Context onto the stack using given styles and bounds. The transform from the style will be applied to all elements rendered within this group, along with the other group properties. This adds the Context to the current Render state as well, so renderers that track grouping will track this. Must protect within render mutex lock (see Lock version).

func (*State) RenderDone

func (rs *State) RenderDone() render.Render

RenderDone should be called when the full set of rendering for this painter is done. It returns a self-contained render.Render representing the entire rendering state, suitable for rendering by passing to a render.Renderer. It resets the current painter state so that it is ready for new rendering.