Documentation
¶
Overview ¶
Package gg provides a simple 2D graphics library for Go.
Overview ¶
gg is a Pure Go 2D graphics library inspired by fogleman/gg and designed to integrate with the GoGPU ecosystem. It provides an immediate-mode drawing API similar to HTML Canvas, with both software and GPU rendering backends.
Quick Start ¶
import "github.com/gogpu/gg"
// Create a context
ctx := gg.NewContext(512, 512)
// Draw shapes
ctx.SetRGB(1, 0, 0)
ctx.DrawCircle(256, 256, 100)
ctx.Fill()
// Save to PNG
ctx.SavePNG("output.png")
API Compatibility ¶
The API is designed to be compatible with fogleman/gg for easy migration. Most fogleman/gg code should work with minimal changes.
Renderers ¶
v0.1.0 includes a software rasterizer for immediate usability. Future versions will add GPU-accelerated rendering via gogpu/wgpu.
Architecture ¶
The library is organized into:
- Public API: Context, Path, Paint, Matrix, Point
- Internal: raster (scanline), path (tessellation), blend (compositing)
- Renderers: software (v0.1), gpu (v0.3+)
Coordinate System ¶
Uses standard computer graphics coordinates:
- Origin (0,0) at top-left
- X increases right
- Y increases down
- Angles in radians, 0 is right, increases counter-clockwise
Performance ¶
The software renderer is optimized for correctness over speed. For performance-critical applications, use the GPU renderer (v0.3+).
Index ¶
- Constants
- Variables
- type Close
- type Context
- func (c *Context) Clear()
- func (c *Context) ClearPath()
- func (c *Context) ClearWithColor(col RGBA)
- func (c *Context) ClosePath()
- func (c *Context) CubicTo(c1x, c1y, c2x, c2y, x, y float64)
- func (c *Context) DrawArc(x, y, r, angle1, angle2 float64)
- func (c *Context) DrawCircle(x, y, r float64)
- func (c *Context) DrawEllipse(x, y, rx, ry float64)
- func (c *Context) DrawEllipticalArc(x, y, rx, ry, angle1, angle2 float64)
- func (c *Context) DrawLine(x1, y1, x2, y2 float64)
- func (c *Context) DrawPoint(x, y, r float64)
- func (c *Context) DrawRectangle(x, y, w, h float64)
- func (c *Context) DrawRegularPolygon(n int, x, y, r, rotation float64)
- func (c *Context) DrawRoundedRectangle(x, y, w, h, r float64)
- func (c *Context) DrawString(s string, x, y float64)
- func (c *Context) DrawStringAnchored(s string, x, y, ax, ay float64)
- func (c *Context) Fill()
- func (c *Context) FillPreserve()
- func (c *Context) Font() text.Face
- func (c *Context) Height() int
- func (c *Context) Identity()
- func (c *Context) Image() image.Image
- func (c *Context) InvertY()
- func (c *Context) LineTo(x, y float64)
- func (c *Context) LoadFontFace(path string, points float64) errordeprecated
- func (c *Context) MeasureString(s string) (w, h float64)
- func (c *Context) MoveTo(x, y float64)
- func (c *Context) NewSubPath()
- func (c *Context) Pop()
- func (c *Context) Push()
- func (c *Context) QuadraticTo(cx, cy, x, y float64)
- func (c *Context) Rotate(angle float64)
- func (c *Context) RotateAbout(angle, x, y float64)
- func (c *Context) SavePNG(path string) error
- func (c *Context) Scale(x, y float64)
- func (c *Context) SetColor(col color.Color)
- func (c *Context) SetFillRule(rule FillRule)
- func (c *Context) SetFont(face text.Face)
- func (c *Context) SetHexColor(hex string)
- func (c *Context) SetLineCap(lineCap LineCap)
- func (c *Context) SetLineJoin(join LineJoin)
- func (c *Context) SetLineWidth(width float64)
- func (c *Context) SetPixel(x, y int, col RGBA)
- func (c *Context) SetRGB(r, g, b float64)
- func (c *Context) SetRGBA(r, g, b, a float64)
- func (c *Context) Shear(x, y float64)
- func (c *Context) Stroke()
- func (c *Context) StrokePreserve()
- func (c *Context) TransformPoint(x, y float64) (float64, float64)
- func (c *Context) Translate(x, y float64)
- func (c *Context) Width() int
- type CubicTo
- type FillRule
- type LineCap
- type LineJoin
- type LineTo
- type Matrix
- type MoveTo
- type Paint
- type Path
- func (p *Path) Arc(cx, cy, r, angle1, angle2 float64)
- func (p *Path) Circle(cx, cy, r float64)
- func (p *Path) Clear()
- func (p *Path) Close()
- func (p *Path) CubicTo(c1x, c1y, c2x, c2y, x, y float64)
- func (p *Path) CurrentPoint() Point
- func (p *Path) Elements() []PathElement
- func (p *Path) Ellipse(cx, cy, rx, ry float64)
- func (p *Path) LineTo(x, y float64)
- func (p *Path) MoveTo(x, y float64)
- func (p *Path) QuadraticTo(cx, cy, x, y float64)
- func (p *Path) Rectangle(x, y, w, h float64)
- func (p *Path) RoundedRectangle(x, y, w, h, r float64)
- func (p *Path) Transform(m Matrix) *Path
- type PathElement
- type Pattern
- type Pixmap
- func (p *Pixmap) At(x, y int) color.Color
- func (p *Pixmap) Bounds() image.Rectangle
- func (p *Pixmap) Clear(c RGBA)
- func (p *Pixmap) ColorModel() color.Model
- func (p *Pixmap) Data() []uint8
- func (p *Pixmap) GetPixel(x, y int) RGBA
- func (p *Pixmap) Height() int
- func (p *Pixmap) SavePNG(path string) error
- func (p *Pixmap) SetPixel(x, y int, c RGBA)
- func (p *Pixmap) ToImage() *image.RGBA
- func (p *Pixmap) Width() int
- type Point
- func (p Point) Add(q Point) Point
- func (p Point) Cross(q Point) float64
- func (p Point) Distance(q Point) float64
- func (p Point) Div(s float64) Point
- func (p Point) Dot(q Point) float64
- func (p Point) Length() float64
- func (p Point) LengthSquared() float64
- func (p Point) Lerp(q Point, t float64) Point
- func (p Point) Mul(s float64) Point
- func (p Point) Normalize() Point
- func (p Point) Rotate(angle float64) Point
- func (p Point) Sub(q Point) Point
- type QuadTo
- type RGBA
- type Renderer
- type SoftwareRenderer
- type SolidPattern
Constants ¶
const ( // Version is the current version of the library Version = "0.1.0-alpha.1" // VersionMajor is the major version VersionMajor = 0 // VersionMinor is the minor version VersionMinor = 1 // VersionPatch is the patch version VersionPatch = 0 // VersionPrerelease is the prerelease identifier VersionPrerelease = "alpha.1" )
Version information
Variables ¶
var ( Black = RGB(0, 0, 0) White = RGB(1, 1, 1) Red = RGB(1, 0, 0) Green = RGB(0, 1, 0) Blue = RGB(0, 0, 1) Yellow = RGB(1, 1, 0) Cyan = RGB(0, 1, 1) Magenta = RGB(1, 0, 1) Transparent = RGBA2(0, 0, 0, 0) )
Common colors
Functions ¶
This section is empty.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is the main drawing context. It maintains a pixmap, current path, paint state, and transformation stack.
func NewContext ¶
NewContext creates a new drawing context with the given dimensions.
func NewContextForImage ¶
NewContextForImage creates a context for drawing on an existing image.
func (*Context) ClearWithColor ¶
ClearWithColor fills the entire context with a specific color.
func (*Context) DrawCircle ¶
DrawCircle draws a circle.
func (*Context) DrawEllipse ¶
DrawEllipse draws an ellipse.
func (*Context) DrawEllipticalArc ¶
DrawEllipticalArc draws an elliptical arc (advanced).
func (*Context) DrawRectangle ¶
DrawRectangle draws a rectangle.
func (*Context) DrawRegularPolygon ¶
DrawRegularPolygon draws a regular polygon with n sides.
func (*Context) DrawRoundedRectangle ¶
DrawRoundedRectangle draws a rectangle with rounded corners.
func (*Context) DrawString ¶
DrawString draws text at position (x, y) where y is the baseline. If no font has been set with SetFont, this function does nothing.
The baseline is the line on which most letters sit. Characters with descenders (like 'g', 'j', 'p', 'q', 'y') extend below the baseline.
func (*Context) DrawStringAnchored ¶
DrawStringAnchored draws text with an anchor point. The anchor point is specified by ax and ay, which are in the range [0, 1].
(0, 0) = top-left (0.5, 0.5) = center (1, 1) = bottom-right
The text is positioned so that the anchor point is at (x, y).
func (*Context) FillPreserve ¶
func (c *Context) FillPreserve()
FillPreserve fills the current path and preserves it for additional operations.
func (*Context) Font ¶ added in v0.2.0
Font returns the current font face. Returns nil if no font has been set.
func (*Context) Identity ¶
func (c *Context) Identity()
Identity resets the transformation matrix to identity.
func (*Context) InvertY ¶
func (c *Context) InvertY()
InvertY inverts the Y axis (useful for coordinate system changes).
func (*Context) LoadFontFace
deprecated
LoadFontFace loads a font from a file and sets it as the current font. The size is specified in points.
Deprecated: Use text.NewFontSourceFromFile and SetFont instead. This method is provided for convenience and backward compatibility.
Example (new way):
source, err := text.NewFontSourceFromFile("font.ttf")
if err != nil {
return err
}
face := source.Face(12.0)
ctx.SetFont(face)
func (*Context) MeasureString ¶
MeasureString returns the dimensions of text in pixels. Returns (width, height) where:
- width is the horizontal advance of the text
- height is the line height (ascent + descent + line gap)
If no font has been set, returns (0, 0).
func (*Context) NewSubPath ¶
func (c *Context) NewSubPath()
NewSubPath starts a new subpath without closing the previous one.
func (*Context) QuadraticTo ¶
QuadraticTo adds a quadratic Bezier curve to the current path.
func (*Context) RotateAbout ¶
RotateAbout rotates around a specific point.
func (*Context) SetFillRule ¶
SetFillRule sets the fill rule.
func (*Context) SetFont ¶ added in v0.2.0
SetFont sets the current font face for text drawing. The face should be created from a FontSource.
Example:
source, _ := text.NewFontSourceFromFile("font.ttf")
face := source.Face(12.0)
ctx.SetFont(face)
func (*Context) SetHexColor ¶
SetHexColor sets the current color using a hex string.
func (*Context) SetLineCap ¶
SetLineCap sets the line cap style.
func (*Context) SetLineJoin ¶
SetLineJoin sets the line join style.
func (*Context) SetLineWidth ¶
SetLineWidth sets the line width for stroking.
func (*Context) StrokePreserve ¶
func (c *Context) StrokePreserve()
StrokePreserve strokes the current path and preserves it.
func (*Context) TransformPoint ¶
TransformPoint transforms a point by the current matrix.
type FillRule ¶
type FillRule int
FillRule specifies how to determine which areas are inside a path.
type Matrix ¶
Matrix represents a 2D affine transformation matrix. It uses a 2x3 matrix in row-major order:
| a b c | | d e f |
This represents the transformation:
x' = a*x + b*y + c y' = d*x + e*y + f
func (Matrix) Invert ¶
Invert returns the inverse matrix. Returns the identity matrix if the matrix is not invertible.
func (Matrix) IsIdentity ¶
IsIdentity returns true if the matrix is the identity matrix.
func (Matrix) IsTranslation ¶
IsTranslation returns true if the matrix is only a translation.
func (Matrix) TransformPoint ¶
TransformPoint applies the transformation to a point.
func (Matrix) TransformVector ¶
TransformVector applies the transformation to a vector (no translation).
type Paint ¶
type Paint struct {
// Pattern is the fill or stroke pattern
Pattern Pattern
// LineWidth is the width of strokes
LineWidth float64
// LineCap is the shape of line endpoints
LineCap LineCap
// LineJoin is the shape of line joins
LineJoin LineJoin
// MiterLimit is the miter limit for sharp joins
MiterLimit float64
// FillRule is the fill rule for paths
FillRule FillRule
// Antialias enables anti-aliasing
Antialias bool
}
Paint represents the styling information for drawing.
type Path ¶
type Path struct {
// contains filtered or unexported fields
}
Path represents a vector path.
func (*Path) Arc ¶
Arc adds a circular arc to the path. The arc is drawn from angle1 to angle2 (in radians) around center (cx, cy).
func (*Path) Close ¶
func (p *Path) Close()
Close closes the current subpath by drawing a line to the start point.
func (*Path) CurrentPoint ¶
CurrentPoint returns the current point.
func (*Path) QuadraticTo ¶
QuadraticTo draws a quadratic Bezier curve.
func (*Path) RoundedRectangle ¶
RoundedRectangle adds a rectangle with rounded corners.
type PathElement ¶
type PathElement interface {
// contains filtered or unexported methods
}
PathElement represents a single element in a path.
type Pattern ¶
type Pattern interface {
// ColorAt returns the color at the given point.
ColorAt(x, y float64) RGBA
}
Pattern represents a fill or stroke pattern.
type Pixmap ¶
type Pixmap struct {
// contains filtered or unexported fields
}
Pixmap represents a rectangular pixel buffer.
func (*Pixmap) ColorModel ¶
ColorModel implements the image.Image interface.
type Point ¶
type Point struct {
X, Y float64
}
Point represents a 2D point or vector.
func (Point) LengthSquared ¶
LengthSquared returns the squared length of the vector.
func (Point) Lerp ¶
Lerp performs linear interpolation between two points. t=0 returns p, t=1 returns q, intermediate values interpolate.
type RGBA ¶
type RGBA struct {
R, G, B, A float64
}
RGBA represents a color with red, green, blue, and alpha components. Each component is in the range [0, 1].
func HSL ¶
HSL creates a color from HSL values. h is hue [0, 360), s is saturation [0, 1], l is lightness [0, 1].
func Hex ¶
Hex creates a color from a hex string. Supports formats: "RGB", "RGBA", "RRGGBB", "RRGGBBAA".
func (RGBA) Premultiply ¶
Premultiply returns a premultiplied color.
func (RGBA) Unpremultiply ¶
Unpremultiply returns an unpremultiplied color.
type Renderer ¶
type Renderer interface {
// Fill fills a path with the given paint.
Fill(pixmap *Pixmap, path *Path, paint *Paint)
// Stroke strokes a path with the given paint.
Stroke(pixmap *Pixmap, path *Path, paint *Paint)
}
Renderer is the interface for rendering paths to a pixmap.
type SoftwareRenderer ¶
type SoftwareRenderer struct {
// contains filtered or unexported fields
}
SoftwareRenderer is a CPU-based scanline rasterizer.
func NewSoftwareRenderer ¶
func NewSoftwareRenderer(width, height int) *SoftwareRenderer
NewSoftwareRenderer creates a new software renderer.
type SolidPattern ¶
type SolidPattern struct {
Color RGBA
}
SolidPattern represents a solid color pattern.
func NewSolidPattern ¶
func NewSolidPattern(color RGBA) *SolidPattern
NewSolidPattern creates a solid color pattern.
func (*SolidPattern) ColorAt ¶
func (p *SolidPattern) ColorAt(x, y float64) RGBA
ColorAt implements Pattern.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
ggdemo
command
Command ggdemo demonstrates the gg 2D graphics library.
|
Command ggdemo demonstrates the gg 2D graphics library. |
|
examples
|
|
|
basic
command
|
|
|
shapes
command
|
|
|
text
command
|
|
|
text_fallback
command
|
|
|
gogpu_integration
module
|
|
|
internal
|
|
|
blend
Package blend provides color blending operations.
|
Package blend provides color blending operations. |
|
path
Package path provides internal path processing utilities.
|
Package path provides internal path processing utilities. |
|
raster
Package raster provides scanline rasterization for 2D paths.
|
Package raster provides scanline rasterization for 2D paths. |
|
Package text provides text rendering for gg.
|
Package text provides text rendering for gg. |