gg

Overview

Key Features

Installation

go get github.com/gogpu/gg

Quick Start

package main
import (
 "github.com/gogpu/gg"
 "github.com/gogpu/gg/text"
)
func main() {
 // Create drawing context
 dc := gg.NewContext(512, 512)
 defer dc.Close()
 dc.ClearWithColor(gg.White)
 // Draw shapes
 dc.SetHexColor("#3498db")
 dc.DrawCircle(256, 256, 100)
 dc.Fill()
 // Render text
 source, _ := text.NewFontSourceFromFile("arial.ttf")
 defer source.Close()
 dc.SetFont(source.Face(32))
 dc.SetColor(gg.Black)
 dc.DrawString("Hello, GoGPU!", 180, 260)
 dc.SavePNG("output.png")
}

Rendering

Software Rendering (Default)

dc := gg.NewContext(800, 600)
defer dc.Close()
// Auto-selection (default) — optimal algorithm per-path
dc.DrawCircle(400, 300, 100)
dc.Fill()
// Force specific algorithm for benchmarking
dc.SetRasterizerMode(gg.RasterizerSparseStrips)

Pixel-Perfect Mode (No Anti-Aliasing)

dc.SetAntiAlias(false) // binary coverage: inside=opaque, outside=transparent
dc.DrawRectangle(10, 10, 100, 50)
dc.Fill() // no gray edge pixels
dc.SetAntiAlias(true) // back to smooth AA

Text Stroke & Outline

dc.SetLineWidth(3)
dc.SetRGB(0, 0, 0)
dc.StrokeString("Hello", x, y) // black outline
dc.SetRGB(1, 1, 1)
dc.DrawString("Hello", x, y) // white fill on top
// Or get text as a Path for custom operations:
path := dc.TextPath("Hello", x, y)

Aliased Text

dc.SetTextMode(gg.TextModeAliased) // no gray edge pixels on text
dc.DrawString("Pixel Perfect", x, y)
dc.SavePNG("aliased.png") // works standalone, no import _ "gg/gpu" needed

GPU Acceleration (Optional)

import (
 "github.com/gogpu/gg"
 _ "github.com/gogpu/gg/gpu" // opt-in GPU acceleration
)
func main() {
 // GPU automatically used when available, falls back to CPU
 dc := gg.NewContext(800, 600)
 defer dc.Close()
 dc.DrawCircle(400, 300, 100)
 dc.Fill() // tries GPU first, falls back to CPU transparently
}

Custom Pixmap

// Use existing pixmap
pm := gg.NewPixmap(800, 600)
dc := gg.NewContext(800, 600, gg.WithPixmap(pm))

Architecture

 gg (Public API)
 │
 ┌───────────────────┼───────────────────┐
 │ │ │
 Immediate Mode Retained Mode Resources
 (Context API) (Scene Graph) (Images, Fonts)
 │ │ │
 │ TagText (ADR-022) │
 │ shape once → glyph refs │
 └───────────────────┼───────────────────┘
 │
 ┌──────────────┴──────────────┐
 │ │
 CPU Raster GPUAccelerator
 (always available) (opt-in via gg/gpu)
 │ │
 internal/raster ┌──────────┼──────────┐
 │ │ │
 Render Pass MSDF Text Compute
 (Tiers 1-4,6) (Tier 4,6) (Tier 5)

Rendering Structure

Core APIs

Immediate Mode (Context)

dc := gg.NewContext(800, 600)
defer dc.Close()
// Transforms
dc.Push()
dc.Translate(400, 300)
dc.Rotate(math.Pi / 4)
dc.DrawRectangle(-50, -50, 100, 100)
dc.SetRGB(0.2, 0.5, 0.8)
dc.Fill()
dc.Pop()
// Bezier paths
dc.MoveTo(100, 100)
dc.QuadraticTo(200, 50, 300, 100)
dc.CubicTo(350, 150, 350, 250, 300, 300)
dc.SetLineWidth(3)
dc.Stroke()

Fluent Path Builder

path := gg.BuildPath().
 MoveTo(100, 100).
 LineTo(200, 100).
 QuadTo(250, 150, 200, 200).
 CubicTo(150, 250, 100, 250, 50, 200).
 Close().
 Circle(300, 150, 50).
 Star(400, 150, 40, 20, 5).
 Build()
dc.SetPath(path)
dc.Fill()

Retained Mode (Scene Graph)

import (
 "github.com/gogpu/gg"
 "github.com/gogpu/gg/scene"
 "github.com/gogpu/gg/text"
)
s := scene.NewScene()
// Shapes — encoded as compact binary commands
s.Fill(scene.FillNonZero, scene.IdentityAffine(),
 scene.SolidBrush(gg.RGBA{R: 1, A: 0.8}),
 scene.NewCircleShape(150, 200, 100))
// Text — stored as glyph references (10 bytes/glyph, not vector paths)
source, _ := text.NewFontSourceFromFile("Roboto.ttf")
face := source.Face(16)
s.DrawText("Hello Scene", face, 50, 50, scene.SolidBrush(gg.White))
// Render through GPU scene renderer (Tier 6/4 text, SDF shapes)
gpuR := scene.NewGPUSceneRenderer(dc)
gpuR.RenderScene(s)

Text Rendering

// Font composition
mainFont, _ := text.NewFontSourceFromFile("Roboto.ttf")
emojiFont, _ := text.NewFontSourceFromFile("NotoEmoji.ttf")
defer mainFont.Close()
defer emojiFont.Close()
multiFace, _ := text.NewMultiFace(
 mainFont.Face(24),
 text.NewFilteredFace(emojiFont.Face(24), text.RangeEmoji),
)
dc.SetFont(multiFace)
dc.DrawString("Hello World! Nice day!", 50, 100)
// Built-in GSUB/GPOS shaping (ligatures, kerning) is enabled by default.
// No additional setup needed — OwnShaper handles liga, kern features automatically.
// Text layout with wrapping
opts := text.LayoutOptions{
 MaxWidth: 400,
 WrapMode: text.WrapWordChar,
 Alignment: text.AlignCenter,
}
layout := text.LayoutText("Long text...", face, opts)

Transform-Aware Text

dc.SetFont(source.Face(24))
dc.SetRGB(0, 0, 0)
// Scaled text — rendered at device resolution (no pixelation)
dc.Push()
dc.Scale(2, 2)
dc.DrawString("2x Scale", 50, 50)
dc.Pop()
// Rotated text — glyph outlines converted to vector paths
dc.Push()
dc.Translate(200, 200)
dc.Rotate(math.Pi / 6) // 30 degrees
dc.DrawString("Rotated", 0, 0)
dc.Pop()

Color Emoji

// Extract color emoji from font
extractor, _ := emoji.NewCBDTExtractor(cbdtData, cblcData)
glyph, _ := extractor.GetGlyph(glyphID, ppem)
img, _ := png.Decode(bytes.NewReader(glyph.Data))
// Parse COLR/CPAL vector layers
parser, _ := emoji.NewCOLRParser(colrData, cpalData)
glyph, _ := parser.GetGlyph(glyphID, paletteIndex)
for _, layer := range glyph.Layers {
 // Render each layer with layer.Color
}

Layer Compositing

dc.PushLayer(gg.BlendOverlay, 0.7)
dc.SetRGB(1, 0, 0)
dc.DrawCircle(150, 200, 100)
dc.Fill()
dc.SetRGB(0, 0, 1)
dc.DrawCircle(250, 200, 100)
dc.Fill()
dc.PopLayer()

Alpha Masks

// Create a circular mask
dc.DrawCircle(200, 200, 100)
mask := dc.AsMask() // capture path as mask (before Fill!)
dc.ClearPath()
// Apply mask: only the circle area is visible
dc.SetMask(mask)
dc.SetRGB(0, 0, 1)
dc.DrawRectangle(0, 0, 400, 400)
dc.Fill() // blue only inside the circle

mask := gg.NewMask(400, 400)
// ... fill mask with desired shape ...
dc.PushMaskLayer(mask)
dc.DrawCircle(100, 100, 50)
dc.Fill()
dc.DrawRectangle(200, 200, 80, 80)
dc.Fill()
dc.PopLayer() // entire layer masked, then composited

Recording & Vector Export

import (
 "github.com/gogpu/gg/recording"
 _ "github.com/gogpu/gg-pdf" // Register PDF backend
 _ "github.com/gogpu/gg-svg" // Register SVG backend
)
// Create recorder
rec := recording.NewRecorder(800, 600)
// Draw using familiar API
rec.SetColor(gg.Blue)
rec.DrawCircle(400, 300, 100)
rec.Fill()
// Finish recording and play back to a raster backend
r := rec.FinishRecording()
backend := raster.NewBackend()
r.Playback(backend)
backend.SaveToFile("output.png")

Why "Context" Instead of "Canvas"?

dc := gg.NewContext(512, 512) // dc = drawing context

Performance

Debugging

Damage Overlay

GOGPU_DEBUG_DAMAGE=1 go run ./examples/gogpu_integration

Environment Variables

Ecosystem

Documentation

Articles

Contributing

License