gg: Instructions file for Codex

AGENTS.md — gg

Pure Go 2D graphics library. Smart rasterizer, GPU acceleration, text rendering, SVG paths.

What is gg

gg is a 2D graphics library for Go — draw shapes, text, images, paths with anti-aliasing. Features a smart 6-algorithm rasterizer that auto-selects the best algorithm per path (NoAA, Analytic, SparseStrips, TileCompute, SDF, Vello PTCL). GPU acceleration via blank import.

Part of the GoGPU ecosystem — think Flutter or Qt, but Pure Go with zero CGO.

When to use gg

• Draw 2D shapes (circles, rectangles, paths) → gg.Context
• Render text with font shaping → cc.DrawString()
• Generate images programmatically → gg.NewContext(w, h)
• GPU-accelerated 2D in a gogpu window → ggcanvas.New() + import _ "github.com/gogpu/gg/gpu"

Quick Start

Standalone (CPU, no window)

import "github.com/gogpu/gg"

dc := gg.NewContext(800, 600)
dc.SetRGB(1, 0, 0)
dc.DrawCircle(400, 300, 100)
dc.Fill()
dc.SavePNG("circle.png")

With gogpu window (GPU-accelerated)

import (
    "github.com/gogpu/gg"
    "github.com/gogpu/gg/integration/ggcanvas"
    _ "github.com/gogpu/gg/gpu" // GPU SDF acceleration
)

var canvas *ggcanvas.Canvas

app.OnDraw(func(dc *gogpu.Context) {
    if canvas == nil {
        canvas, _ = ggcanvas.New(dc.GPUContextProvider(), 800, 600)
    }
    canvas.Draw(func(cc *gg.Context) {
        cc.SetRGB(1, 0, 0)
        cc.DrawCircle(400, 300, 100)
        cc.Fill()
    })
    canvas.Render(dc.RenderTarget())
})

Important: Always add _ "github.com/gogpu/gg/gpu" blank import for GPU acceleration. Without it, gg uses CPU-only rasterization.

Key Packages

Package	Purpose
gg (root)	Drawing context, shapes, text, images
gg/gpu	GPU acceleration registration (blank import)
gg/integration/ggcanvas	GPU canvas for gogpu integration
gg/scene	Scene graph for retained-mode rendering

Build & Test

go build ./...
go test ./...
golangci-lint run --timeout=5m