README
¶
Go Graphics
gg
is a library for rendering 2D graphics in pure Go.
Installation
go get -u github.com/fogleman/gg
Alternatively, you may use gopkg.in to grab a specific major-version:
go get -u gopkg.in/fogleman/gg.v1
Documentation
- godoc: https://godoc.org/github.com/fogleman/gg
- pkg.go.dev: https://pkg.go.dev/github.com/fogleman/gg?tab=doc
Hello, Circle!
Look how easy!
package main
import "github.com/fogleman/gg"
func main() {
dc := gg.NewContext(1000, 1000)
dc.DrawCircle(500, 500, 400)
dc.SetRGB(0, 0, 0)
dc.Fill()
dc.SavePNG("out.png")
}
Examples
There are lots of examples included. They're mostly for testing the code, but they're good for learning, too.
Creating Contexts
There are a few ways of creating a context.
NewContext(width, height int) *Context
NewContextForImage(im image.Image) *Context
NewContextForRGBA(im *image.RGBA) *Context
Drawing Functions
Ever used a graphics library that didn't have functions for drawing rectangles or circles? What a pain!
DrawPoint(x, y, r float64)
DrawLine(x1, y1, x2, y2 float64)
DrawRectangle(x, y, w, h float64)
DrawRoundedRectangle(x, y, w, h, r float64)
DrawCircle(x, y, r float64)
DrawArc(x, y, r, angle1, angle2 float64)
DrawEllipse(x, y, rx, ry float64)
DrawEllipticalArc(x, y, rx, ry, angle1, angle2 float64)
DrawRegularPolygon(n int, x, y, r, rotation float64)
DrawImage(im image.Image, x, y int)
DrawImageAnchored(im image.Image, x, y int, ax, ay float64)
SetPixel(x, y int)
MoveTo(x, y float64)
LineTo(x, y float64)
QuadraticTo(x1, y1, x2, y2 float64)
CubicTo(x1, y1, x2, y2, x3, y3 float64)
ClosePath()
ClearPath()
NewSubPath()
Clear()
Stroke()
Fill()
StrokePreserve()
FillPreserve()
It is often desired to center an image at a point. Use DrawImageAnchored
with ax
and ay
set to 0.5 to do this. Use 0 to left or top align. Use 1 to right or bottom align. DrawStringAnchored
does the same for text, so you don't need to call MeasureString
yourself.
Text Functions
It will even do word wrap for you!
DrawString(s string, x, y float64)
DrawStringAnchored(s string, x, y, ax, ay float64)
DrawStringWrapped(s string, x, y, ax, ay, width, lineSpacing float64, align Align)
MeasureString(s string) (w, h float64)
MeasureMultilineString(s string, lineSpacing float64) (w, h float64)
WordWrap(s string, w float64) []string
SetFontFace(fontFace font.Face)
LoadFontFace(path string, points float64) error
Color Functions
Colors can be set in several different ways for your convenience.
SetRGB(r, g, b float64)
SetRGBA(r, g, b, a float64)
SetRGB255(r, g, b int)
SetRGBA255(r, g, b, a int)
SetColor(c color.Color)
SetHexColor(x string)
Stroke & Fill Options
SetLineWidth(lineWidth float64)
SetLineCap(lineCap LineCap)
SetLineJoin(lineJoin LineJoin)
SetDash(dashes ...float64)
SetDashOffset(offset float64)
SetFillRule(fillRule FillRule)
Gradients & Patterns
gg
supports linear, radial and conic gradients and surface patterns. You can also implement your own patterns.
SetFillStyle(pattern Pattern)
SetStrokeStyle(pattern Pattern)
NewSolidPattern(color color.Color)
NewLinearGradient(x0, y0, x1, y1 float64)
NewRadialGradient(x0, y0, r0, x1, y1, r1 float64)
NewConicGradient(cx, cy, deg float64)
NewSurfacePattern(im image.Image, op RepeatOp)
Transformation Functions
Identity()
Translate(x, y float64)
Scale(x, y float64)
Rotate(angle float64)
Shear(x, y float64)
ScaleAbout(sx, sy, x, y float64)
RotateAbout(angle, x, y float64)
ShearAbout(sx, sy, x, y float64)
TransformPoint(x, y float64) (tx, ty float64)
InvertY()
It is often desired to rotate or scale about a point that is not the origin. The functions RotateAbout
, ScaleAbout
, ShearAbout
are provided as a convenience.
InvertY
is provided in case Y should increase from bottom to top vs. the default top to bottom.
Stack Functions
Save and restore the state of the context. These can be nested.
Push()
Pop()
Clipping Functions
Use clipping regions to restrict drawing operations to an area that you defined using paths.
Clip()
ClipPreserve()
ResetClip()
AsMask() *image.Alpha
SetMask(mask *image.Alpha)
InvertMask()
Helper Functions
Sometimes you just don't want to write these yourself.
Radians(degrees float64) float64
Degrees(radians float64) float64
LoadImage(path string) (image.Image, error)
LoadPNG(path string) (image.Image, error)
SavePNG(path string, im image.Image) error
Another Example
See the output of this example below.
package main
import "github.com/fogleman/gg"
func main() {
const S = 1024
dc := gg.NewContext(S, S)
dc.SetRGBA(0, 0, 0, 0.1)
for i := 0; i < 360; i += 15 {
dc.Push()
dc.RotateAbout(gg.Radians(float64(i)), S/2, S/2)
dc.DrawEllipse(S/2, S/2, S*7/16, S/8)
dc.Fill()
dc.Pop()
}
dc.SavePNG("out.png")
}
Documentation
¶
Overview ¶
Package gg provides a simple API for rendering 2D graphics in pure Go.
Index ¶
- func Degrees(radians float64) float64
- func LoadFontFace(path string, points float64) (font.Face, error)
- func LoadImage(path string) (image.Image, error)
- func LoadJPG(path string) (image.Image, error)
- func LoadPNG(path string) (image.Image, error)
- func Radians(degrees float64) float64
- func SaveJPG(path string, im image.Image, quality int) error
- func SavePNG(path string, im image.Image) error
- type Align
- type Context
- func (dc *Context) AsMask() *image.Alpha
- func (dc *Context) Clear()
- func (dc *Context) ClearPath()
- func (dc *Context) Clip()
- func (dc *Context) ClipPreserve()
- func (dc *Context) ClosePath()
- func (dc *Context) CubicTo(x1, y1, x2, y2, x3, y3 float64)
- func (dc *Context) DrawArc(x, y, r, angle1, angle2 float64)
- func (dc *Context) DrawCircle(x, y, r float64)
- func (dc *Context) DrawEllipse(x, y, rx, ry float64)
- func (dc *Context) DrawEllipticalArc(x, y, rx, ry, angle1, angle2 float64)
- func (dc *Context) DrawImage(im image.Image, x, y int)
- func (dc *Context) DrawImageAnchored(im image.Image, x, y int, ax, ay float64)
- func (dc *Context) DrawLine(x1, y1, x2, y2 float64)
- func (dc *Context) DrawPoint(x, y, r float64)
- func (dc *Context) DrawRectangle(x, y, w, h float64)
- func (dc *Context) DrawRegularPolygon(n int, x, y, r, rotation float64)
- func (dc *Context) DrawRoundedRectangle(x, y, w, h, r float64)
- func (dc *Context) DrawString(s string, x, y float64)
- func (dc *Context) DrawStringAnchored(s string, x, y, ax, ay float64)
- func (dc *Context) DrawStringWrapped(s string, x, y, ax, ay, width, lineSpacing float64, align Align)
- func (dc *Context) EncodeJPG(w io.Writer, o *jpeg.Options) error
- func (dc *Context) EncodePNG(w io.Writer) error
- func (dc *Context) Fill()
- func (dc *Context) FillPreserve()
- func (dc *Context) FontHeight() float64
- func (dc *Context) GetCurrentPoint() (Point, bool)
- func (dc *Context) Height() int
- func (dc *Context) Identity()
- func (dc *Context) Image() image.Image
- func (dc *Context) InvertMask()
- func (dc *Context) InvertY()
- func (dc *Context) LineTo(x, y float64)
- func (dc *Context) LoadFontFace(path string, points float64) error
- func (dc *Context) MeasureMultilineString(s string, lineSpacing float64) (width, height float64)
- func (dc *Context) MeasureString(s string) (w, h float64)
- func (dc *Context) MoveTo(x, y float64)
- func (dc *Context) NewSubPath()
- func (dc *Context) Pop()
- func (dc *Context) Push()
- func (dc *Context) QuadraticTo(x1, y1, x2, y2 float64)
- func (dc *Context) ResetClip()
- func (dc *Context) Rotate(angle float64)
- func (dc *Context) RotateAbout(angle, x, y float64)
- func (dc *Context) SaveJPG(path string, quality int) error
- func (dc *Context) SavePNG(path string) error
- func (dc *Context) Scale(x, y float64)
- func (dc *Context) ScaleAbout(sx, sy, x, y float64)
- func (dc *Context) SetColor(c color.Color)
- func (dc *Context) SetDash(dashes ...float64)
- func (dc *Context) SetDashOffset(offset float64)
- func (dc *Context) SetFillRule(fillRule FillRule)
- func (dc *Context) SetFillRuleEvenOdd()
- func (dc *Context) SetFillRuleWinding()
- func (dc *Context) SetFillStyle(pattern Pattern)
- func (dc *Context) SetFontFace(fontFace font.Face)
- func (dc *Context) SetHexColor(x string)
- func (dc *Context) SetLineCap(lineCap LineCap)
- func (dc *Context) SetLineCapButt()
- func (dc *Context) SetLineCapRound()
- func (dc *Context) SetLineCapSquare()
- func (dc *Context) SetLineJoin(lineJoin LineJoin)
- func (dc *Context) SetLineJoinBevel()
- func (dc *Context) SetLineJoinRound()
- func (dc *Context) SetLineWidth(lineWidth float64)
- func (dc *Context) SetMask(mask *image.Alpha) error
- func (dc *Context) SetPixel(x, y int)
- func (dc *Context) SetRGB(r, g, b float64)
- func (dc *Context) SetRGB255(r, g, b int)
- func (dc *Context) SetRGBA(r, g, b, a float64)
- func (dc *Context) SetRGBA255(r, g, b, a int)
- func (dc *Context) SetStrokeStyle(pattern Pattern)
- func (dc *Context) Shear(x, y float64)
- func (dc *Context) ShearAbout(sx, sy, x, y float64)
- func (dc *Context) Stroke()
- func (dc *Context) StrokePreserve()
- func (dc *Context) TransformPoint(x, y float64) (tx, ty float64)
- func (dc *Context) Translate(x, y float64)
- func (dc *Context) Width() int
- func (dc *Context) WordWrap(s string, w float64) []string
- type FillRule
- type Gradient
- type LineCap
- type LineJoin
- type Matrix
- func (a Matrix) Multiply(b Matrix) Matrix
- func (a Matrix) Rotate(angle float64) Matrix
- func (a Matrix) Scale(x, y float64) Matrix
- func (a Matrix) Shear(x, y float64) Matrix
- func (a Matrix) TransformPoint(x, y float64) (tx, ty float64)
- func (a Matrix) TransformVector(x, y float64) (tx, ty float64)
- func (a Matrix) Translate(x, y float64) Matrix
- type Pattern
- type Point
- type RepeatOp
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadFontFace ¶
LoadFontFace is a helper function to load the specified font file with the specified point size. Note that the returned `font.Face` objects are not thread safe and cannot be used in parallel across goroutines. You can usually just use the Context.LoadFontFace function instead of this package-level function.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
func NewContext ¶
NewContext creates a new image.RGBA with the specified width and height and prepares a context for rendering onto that image.
func NewContextForImage ¶
NewContextForImage copies the specified image into a new image.RGBA and prepares a context for rendering onto that image.
func NewContextForRGBA ¶
NewContextForRGBA prepares a context for rendering onto the specified image. No copy is made.
func (*Context) AsMask ¶
AsMask returns an *image.Alpha representing the alpha channel of this context. This can be useful for advanced clipping operations where you first render the mask geometry and then use it as a mask.
func (*Context) Clear ¶
func (dc *Context) Clear()
Clear fills the entire image with the current color.
func (*Context) ClearPath ¶
func (dc *Context) ClearPath()
ClearPath clears the current path. There is no current point after this operation.
func (*Context) Clip ¶
func (dc *Context) Clip()
Clip updates the clipping region by intersecting the current clipping region with the current path as it would be filled by dc.Fill(). The path is cleared after this operation.
func (*Context) ClipPreserve ¶
func (dc *Context) ClipPreserve()
ClipPreserve updates the clipping region by intersecting the current clipping region with the current path as it would be filled by dc.Fill(). The path is preserved after this operation.
func (*Context) ClosePath ¶
func (dc *Context) ClosePath()
ClosePath adds a line segment from the current point to the beginning of the current subpath. If there is no current point, this is a no-op.
func (*Context) CubicTo ¶
CubicTo adds a cubic bezier curve to the current path starting at the current point. If there is no current point, it first performs MoveTo(x1, y1). Because freetype/raster does not support cubic beziers, this is emulated with many small line segments.
func (*Context) DrawCircle ¶
func (*Context) DrawEllipse ¶
func (*Context) DrawEllipticalArc ¶
func (*Context) DrawImageAnchored ¶
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 (*Context) DrawPoint ¶
DrawPoint is like DrawCircle but ensures that a circle of the specified size is drawn regardless of the current transformation matrix. The position is still transformed, but not the shape of the point.
func (*Context) DrawRectangle ¶
func (*Context) DrawRegularPolygon ¶
func (*Context) DrawRoundedRectangle ¶
func (*Context) DrawString ¶
DrawString draws the specified text at the specified point.
func (*Context) DrawStringAnchored ¶
DrawStringAnchored draws the specified text at the specified anchor point. The anchor point is x - w * ax, y - h * ay, where w, h is the size of the text. Use ax=0.5, ay=0.5 to center the text at the specified point.
func (*Context) DrawStringWrapped ¶
func (dc *Context) DrawStringWrapped(s string, x, y, ax, ay, width, lineSpacing float64, align Align)
DrawStringWrapped word-wraps the specified string to the given max width and then draws it at the specified anchor point using the given line spacing and text alignment.
func (*Context) EncodeJPG ¶
EncodeJPG encodes the image as a JPG and writes it to the provided io.Writer in JPEG 4:2:0 baseline format with the given options. Default parameters are used if a nil *jpeg.Options is passed.
func (*Context) EncodePNG ¶
EncodePNG encodes the image as a PNG and writes it to the provided io.Writer.
func (*Context) Fill ¶
func (dc *Context) Fill()
Fill fills the current path with the current color. Open subpaths are implicity closed. The path is cleared after this operation.
func (*Context) FillPreserve ¶
func (dc *Context) FillPreserve()
FillPreserve fills the current path with the current color. Open subpaths are implicity closed. The path is preserved after this operation.
func (*Context) FontHeight ¶
func (*Context) GetCurrentPoint ¶
GetCurrentPoint will return the current point and if there is a current point. The point will have been transformed by the context's transformation matrix.
func (*Context) Identity ¶
func (dc *Context) Identity()
Identity resets the current transformation matrix to the identity matrix. This results in no translating, scaling, rotating, or shearing.
func (*Context) InvertMask ¶
func (dc *Context) InvertMask()
InvertMask inverts the alpha values in the current clipping mask such that a fully transparent region becomes fully opaque and vice versa.
func (*Context) InvertY ¶
func (dc *Context) InvertY()
InvertY flips the Y axis so that Y grows from bottom to top and Y=0 is at the bottom of the image.
func (*Context) LineTo ¶
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 (*Context) MeasureMultilineString ¶
func (*Context) MeasureString ¶
MeasureString returns the rendered width and height of the specified text given the current font face.
func (*Context) MoveTo ¶
MoveTo starts a new subpath within the current path starting at the specified point.
func (*Context) NewSubPath ¶
func (dc *Context) NewSubPath()
NewSubPath starts a new subpath within the current path. There is no current point after this operation.
func (*Context) Pop ¶
func (dc *Context) Pop()
Pop restores the last saved context state from the stack.
func (*Context) Push ¶
func (dc *Context) Push()
Push saves the current state of the context for later retrieval. These can be nested.
func (*Context) QuadraticTo ¶
QuadraticTo adds a quadratic bezier curve to the current path starting at the current point. If there is no current point, it first performs MoveTo(x1, y1)
func (*Context) Rotate ¶
Rotate updates the current matrix with a anticlockwise rotation. Rotation occurs about the origin. Angle is specified in radians.
func (*Context) RotateAbout ¶
RotateAbout updates the current matrix with a anticlockwise rotation. Rotation occurs about the specified point. Angle is specified in radians.
func (*Context) Scale ¶
Scale updates the current matrix with a scaling factor. Scaling occurs about the origin.
func (*Context) ScaleAbout ¶
ScaleAbout updates the current matrix with a scaling factor. Scaling occurs about the specified point.
func (*Context) SetDash ¶
SetDash sets the current dash pattern to use. Call with zero arguments to disable dashes. The values specify the lengths of each dash, with alternating on and off lengths.
func (*Context) SetDashOffset ¶
SetDashOffset sets the initial offset into the dash pattern to use when stroking dashed paths.
func (*Context) SetFillRule ¶
func (*Context) SetFillRuleEvenOdd ¶
func (dc *Context) SetFillRuleEvenOdd()
func (*Context) SetFillRuleWinding ¶
func (dc *Context) SetFillRuleWinding()
func (*Context) SetFillStyle ¶
SetFillStyle sets current fill style
func (*Context) SetFontFace ¶
func (*Context) SetHexColor ¶
SetHexColor sets the current color using a hex string. The leading pound sign (#) is optional. Both 3- and 6-digit variations are supported. 8 digits may be provided to set the alpha value as well.
func (*Context) SetLineCap ¶
func (*Context) SetLineCapButt ¶
func (dc *Context) SetLineCapButt()
func (*Context) SetLineCapRound ¶
func (dc *Context) SetLineCapRound()
func (*Context) SetLineCapSquare ¶
func (dc *Context) SetLineCapSquare()
func (*Context) SetLineJoin ¶
func (*Context) SetLineJoinBevel ¶
func (dc *Context) SetLineJoinBevel()
func (*Context) SetLineJoinRound ¶
func (dc *Context) SetLineJoinRound()
func (*Context) SetLineWidth ¶
func (*Context) SetMask ¶
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 (*Context) SetRGB ¶
SetRGB sets the current color. r, g, b values should be between 0 and 1, inclusive. Alpha will be set to 1 (fully opaque).
func (*Context) SetRGB255 ¶
SetRGB255 sets the current color. r, g, b values should be between 0 and 255, inclusive. Alpha will be set to 255 (fully opaque).
func (*Context) SetRGBA ¶
SetRGBA sets the current color. r, g, b, a values should be between 0 and 1, inclusive.
func (*Context) SetRGBA255 ¶
SetRGBA255 sets the current color. r, g, b, a values should be between 0 and 255, inclusive.
func (*Context) SetStrokeStyle ¶
SetStrokeStyle sets current stroke style
func (*Context) Shear ¶
Shear updates the current matrix with a shearing angle. Shearing occurs about the origin.
func (*Context) ShearAbout ¶
ShearAbout updates the current matrix with a shearing angle. Shearing occurs about the specified point.
func (*Context) Stroke ¶
func (dc *Context) Stroke()
Stroke strokes the current path with the current color, line width, line cap, line join and dash settings. The path is cleared after this operation.
func (*Context) StrokePreserve ¶
func (dc *Context) StrokePreserve()
StrokePreserve strokes the current path with the current color, line width, line cap, line join and dash settings. The path is preserved after this operation.
func (*Context) TransformPoint ¶
TransformPoint multiplies the specified point by the current matrix, returning a transformed position.
type Matrix ¶
type Matrix struct {
XX, YX, XY, YY, X0, Y0 float64
}