gg

package module
Version: v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 20, 2019 License: MIT Imports: 21 Imported by: 450

README

Go Graphics

gg is a library for rendering 2D graphics in pure Go.

Stars

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

https://godoc.org/github.com/fogleman/gg

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.

Examples

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 and radial 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)
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

Separator

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")
}

Ellipses

Documentation

Overview

Package gg provides a simple API for rendering 2D graphics in pure Go.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Degrees

func Degrees(radians float64) float64

func LoadFontFace

func LoadFontFace(path string, points float64) (font.Face, error)

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.

func LoadImage

func LoadImage(path string) (image.Image, error)

func LoadJPG added in v1.3.0

func LoadJPG(path string) (image.Image, error)

func LoadPNG

func LoadPNG(path string) (image.Image, error)

func Radians

func Radians(degrees float64) float64

func SaveJPG added in v1.3.0

func SaveJPG(path string, im image.Image, quality int) error

func SavePNG

func SavePNG(path string, im image.Image) error

Types

type Align

type Align int
const (
	AlignLeft Align = iota
	AlignCenter
	AlignRight
)

type Context

type Context struct {
	// contains filtered or unexported fields
}

func NewContext

func NewContext(width, height int) *Context

NewContext creates a new image.RGBA with the specified width and height and prepares a context for rendering onto that image.

func NewContextForImage

func NewContextForImage(im image.Image) *Context

NewContextForImage copies the specified image into a new image.RGBA and prepares a context for rendering onto that image.

func NewContextForRGBA

func NewContextForRGBA(im *image.RGBA) *Context

NewContextForRGBA prepares a context for rendering onto the specified image. No copy is made.

func (*Context) AsMask added in v1.1.0

func (dc *Context) AsMask() *image.Alpha

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

func (dc *Context) CubicTo(x1, y1, x2, y2, x3, y3 float64)

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) DrawArc

func (dc *Context) DrawArc(x, y, r, angle1, angle2 float64)

func (*Context) DrawCircle

func (dc *Context) DrawCircle(x, y, r float64)

func (*Context) DrawEllipse

func (dc *Context) DrawEllipse(x, y, rx, ry float64)

func (*Context) DrawEllipticalArc

func (dc *Context) DrawEllipticalArc(x, y, rx, ry, angle1, angle2 float64)

func (*Context) DrawImage

func (dc *Context) DrawImage(im image.Image, x, y int)

DrawImage draws the specified image at the specified point.

func (*Context) DrawImageAnchored

func (dc *Context) DrawImageAnchored(im image.Image, x, y int, ax, ay float64)

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) DrawLine

func (dc *Context) DrawLine(x1, y1, x2, y2 float64)

func (*Context) DrawPoint

func (dc *Context) DrawPoint(x, y, r float64)

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 (dc *Context) DrawRectangle(x, y, w, h float64)

func (*Context) DrawRegularPolygon

func (dc *Context) DrawRegularPolygon(n int, x, y, r, rotation float64)

func (*Context) DrawRoundedRectangle

func (dc *Context) DrawRoundedRectangle(x, y, w, h, r float64)

func (*Context) DrawString

func (dc *Context) DrawString(s string, x, y float64)

DrawString draws the specified text at the specified point.

func (*Context) DrawStringAnchored

func (dc *Context) DrawStringAnchored(s string, x, y, ax, ay float64)

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) EncodePNG

func (dc *Context) EncodePNG(w io.Writer) error

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 added in v1.1.0

func (dc *Context) FontHeight() float64

func (*Context) GetCurrentPoint added in v1.3.0

func (dc *Context) GetCurrentPoint() (Point, bool)

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) Height

func (dc *Context) Height() int

Height returns the height of the image in pixels.

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) Image

func (dc *Context) Image() image.Image

Image returns the image that has been drawn by this context.

func (*Context) InvertMask added in v1.2.0

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

func (dc *Context) LineTo(x, y float64)

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) LoadFontFace

func (dc *Context) LoadFontFace(path string, points float64) error

func (*Context) MeasureMultilineString added in v1.2.0

func (dc *Context) MeasureMultilineString(s string, lineSpacing float64) (width, height float64)

func (*Context) MeasureString

func (dc *Context) MeasureString(s string) (w, h float64)

MeasureString returns the rendered width and height of the specified text given the current font face.

func (*Context) MoveTo

func (dc *Context) MoveTo(x, y float64)

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

func (dc *Context) QuadraticTo(x1, y1, x2, y2 float64)

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) ResetClip

func (dc *Context) ResetClip()

ResetClip clears the clipping region.

func (*Context) Rotate

func (dc *Context) Rotate(angle float64)

Rotate updates the current matrix with a clockwise rotation. Rotation occurs about the origin. Angle is specified in radians.

func (*Context) RotateAbout

func (dc *Context) RotateAbout(angle, x, y float64)

RotateAbout updates the current matrix with a clockwise rotation. Rotation occurs about the specified point. Angle is specified in radians.

func (*Context) SavePNG

func (dc *Context) SavePNG(path string) error

SavePNG encodes the image as a PNG and writes it to disk.

func (*Context) Scale

func (dc *Context) Scale(x, y float64)

Scale updates the current matrix with a scaling factor. Scaling occurs about the origin.

func (*Context) ScaleAbout

func (dc *Context) ScaleAbout(sx, sy, x, y float64)

ScaleAbout updates the current matrix with a scaling factor. Scaling occurs about the specified point.

func (*Context) SetColor

func (dc *Context) SetColor(c color.Color)

SetColor sets the current color(for both fill and stroke).

func (*Context) SetDash

func (dc *Context) SetDash(dashes ...float64)

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 added in v1.3.0

func (dc *Context) SetDashOffset(offset float64)

SetDashOffset sets the initial offset into the dash pattern to use when stroking dashed paths.

func (*Context) SetFillRule

func (dc *Context) SetFillRule(fillRule FillRule)

func (*Context) SetFillRuleEvenOdd

func (dc *Context) SetFillRuleEvenOdd()

func (*Context) SetFillRuleWinding

func (dc *Context) SetFillRuleWinding()

func (*Context) SetFillStyle

func (dc *Context) SetFillStyle(pattern Pattern)

SetFillStyle sets current fill style

func (*Context) SetFontFace

func (dc *Context) SetFontFace(fontFace font.Face)

func (*Context) SetHexColor

func (dc *Context) SetHexColor(x string)

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 (dc *Context) SetLineCap(lineCap LineCap)

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 (dc *Context) SetLineJoin(lineJoin LineJoin)

func (*Context) SetLineJoinBevel

func (dc *Context) SetLineJoinBevel()

func (*Context) SetLineJoinRound

func (dc *Context) SetLineJoinRound()

func (*Context) SetLineWidth

func (dc *Context) SetLineWidth(lineWidth float64)

func (*Context) SetMask added in v1.1.0

func (dc *Context) 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 (*Context) SetPixel

func (dc *Context) SetPixel(x, y int)

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

func (*Context) SetRGB

func (dc *Context) SetRGB(r, g, b float64)

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

func (dc *Context) SetRGB255(r, g, b int)

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

func (dc *Context) SetRGBA(r, g, b, a float64)

SetRGBA sets the current color. r, g, b, a values should be between 0 and 1, inclusive.

func (*Context) SetRGBA255

func (dc *Context) SetRGBA255(r, g, b, a int)

SetRGBA255 sets the current color. r, g, b, a values should be between 0 and 255, inclusive.

func (*Context) SetStrokeStyle

func (dc *Context) SetStrokeStyle(pattern Pattern)

SetStrokeStyle sets current stroke style

func (*Context) Shear

func (dc *Context) Shear(x, y float64)

Shear updates the current matrix with a shearing angle. Shearing occurs about the origin.

func (*Context) ShearAbout

func (dc *Context) ShearAbout(sx, sy, x, y float64)

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

func (dc *Context) TransformPoint(x, y float64) (tx, ty float64)

TransformPoint multiplies the specified point by the current matrix, returning a transformed position.

func (*Context) Translate

func (dc *Context) Translate(x, y float64)

Translate updates the current matrix with a translation.

func (*Context) Width

func (dc *Context) Width() int

Width returns the width of the image in pixels.

func (*Context) WordWrap

func (dc *Context) WordWrap(s string, w float64) []string

WordWrap wraps the specified string to the given max width and current font face.

type FillRule

type FillRule int
const (
	FillRuleWinding FillRule = iota
	FillRuleEvenOdd
)

type Gradient

type Gradient interface {
	Pattern
	AddColorStop(offset float64, color color.Color)
}

func NewLinearGradient

func NewLinearGradient(x0, y0, x1, y1 float64) Gradient

func NewRadialGradient

func NewRadialGradient(x0, y0, r0, x1, y1, r1 float64) Gradient

type LineCap

type LineCap int
const (
	LineCapRound LineCap = iota
	LineCapButt
	LineCapSquare
)

type LineJoin

type LineJoin int
const (
	LineJoinRound LineJoin = iota
	LineJoinBevel
)

type Matrix

type Matrix struct {
	XX, YX, XY, YY, X0, Y0 float64
}

func Identity

func Identity() Matrix

func Rotate

func Rotate(angle float64) Matrix

func Scale

func Scale(x, y float64) Matrix

func Shear

func Shear(x, y float64) Matrix

func Translate

func Translate(x, y float64) Matrix

func (Matrix) Multiply

func (a Matrix) Multiply(b Matrix) Matrix

func (Matrix) Rotate

func (a Matrix) Rotate(angle float64) Matrix

func (Matrix) Scale

func (a Matrix) Scale(x, y float64) Matrix

func (Matrix) Shear

func (a Matrix) Shear(x, y float64) Matrix

func (Matrix) TransformPoint

func (a Matrix) TransformPoint(x, y float64) (tx, ty float64)

func (Matrix) TransformVector

func (a Matrix) TransformVector(x, y float64) (tx, ty float64)

func (Matrix) Translate

func (a Matrix) Translate(x, y float64) Matrix

type Pattern

type Pattern interface {
	ColorAt(x, y int) color.Color
}

func NewSolidPattern

func NewSolidPattern(color color.Color) Pattern

func NewSurfacePattern

func NewSurfacePattern(im image.Image, op RepeatOp) Pattern

type Point

type Point struct {
	X, Y float64
}

func CubicBezier

func CubicBezier(x0, y0, x1, y1, x2, y2, x3, y3 float64) []Point

func QuadraticBezier

func QuadraticBezier(x0, y0, x1, y1, x2, y2 float64) []Point

func (Point) Distance

func (a Point) Distance(b Point) float64

func (Point) Fixed

func (a Point) Fixed() fixed.Point26_6

func (Point) Interpolate

func (a Point) Interpolate(b Point, t float64) Point

type RepeatOp

type RepeatOp int
const (
	RepeatBoth RepeatOp = iota
	RepeatX
	RepeatY
	RepeatNone
)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL