wgpu

package
v0.14.0 Latest Latest
Warning

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

 Go to latest Published: Dec 24, 2025 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package wgpu provides a GPU-accelerated rendering backend using gogpu/wgpu.

This backend leverages WebGPU for hardware-accelerated 2D graphics rendering. It uses the gogpu/wgpu Pure Go WebGPU implementation, which supports Vulkan, Metal, and DX12 backends depending on the platform.

Architecture Overview

The wgpu backend implements a complete GPU rendering pipeline: 

Scene Commands -> Decoder -> Tessellator -> Strip Buffer -> GPU -> Composite

Key components:

  • WGPUBackend: Main entry point implementing backend.RenderBackend
  • GPUSceneRenderer: Scene-to-GPU pipeline with tessellation and compositing
  • MemoryManager: GPU texture memory with LRU eviction (configurable budget)
  • TextureAtlas: Shelf-packing for efficient GPU memory usage
  • Tessellator: Path-to-strips using Active Edge Table algorithm
  • PipelineCache: Pre-compiled GPU pipelines for all 29 blend modes
  • ShaderModules: WGSL shaders for strip rasterization and blending

Sparse Strips Algorithm

Scene rendering uses the Sparse Strips algorithm optimized for GPU execution:

  1. Paths are tessellated into horizontal coverage strips (one per scanline)
  2. Each strip stores anti-aliased coverage values (0-255) for a contiguous range
  3. Adjacent strips on the same row are merged for efficiency
  4. GPU compute shaders rasterize strips to textures in parallel
  5. Layer compositing uses fragment shaders with blend modes

Example strip data for a circle: 

Y=10, X=45, Width=10, Coverage=[32, 128, 255, 255, 255, 255, 255, 128, 32, 8]
Y=11, X=43, Width=14, Coverage=[64, 192, 255, ... ]
... (one strip per visible scanline)

Blend Modes

All 29 standard blend modes are supported via WGSL shaders:

Standard modes:

  • Normal, Multiply, Screen, Overlay
  • Darken, Lighten, ColorDodge, ColorBurn
  • HardLight, SoftLight, Difference, Exclusion

HSL modes:

  • Hue, Saturation, Color, Luminosity

Porter-Duff compositing:

  • Clear, Copy, Destination
  • SourceOver, DestinationOver
  • SourceIn, DestinationIn
  • SourceOut, DestinationOut
  • SourceAtop, DestinationAtop
  • Xor, Plus

Registration and Selection

The wgpu backend is automatically registered when this package is imported: 

import _ "github.com/gogpu/gg/backend/wgpu"

The backend will be preferred over the software backend when available. If GPU initialization fails, the system will fall back to software rendering.

Basic Usage

Automatic backend selection (recommended): 

b := backend.Default()  // Returns wgpu if available, otherwise software
if err := b.Init(); err != nil {
    log.Fatal(err)
}
defer b.Close()

Explicit wgpu backend selection: 

b := backend.Get(backend.BackendWGPU)
if b == nil {
    log.Fatal("wgpu backend not available")
}
if err := b.Init(); err != nil {
    log.Fatal(err)
}
defer b.Close()

Rendering Scenes

Build and render a scene: 

// Create scene using SceneBuilder
builder := scene.NewSceneBuilder()
builder.FillRect(0, 0, 800, 600, scene.SolidBrush(gg.White))
builder.FillCircle(400, 300, 100, scene.SolidBrush(gg.Red))

// Add a blended layer
builder.Layer(scene.BlendMultiply, 0.8, nil, func(lb *scene.SceneBuilder) {
    lb.FillRect(300, 200, 200, 200, scene.SolidBrush(gg.Blue))
})

s := builder.Build()

// Render to pixmap
pm := gg.NewPixmap(800, 600)
if err := b.RenderScene(pm, s); err != nil {
    log.Printf("Render error: %v", err)
}

// Save result
pm.SavePNG("output.png")

Direct Scene Construction

Lower-level scene construction: 

s := scene.NewScene()
rect := scene.NewRectShape(10, 10, 80, 80)
s.Fill(scene.FillNonZero, scene.IdentityAffine(), scene.SolidBrush(gg.Red), rect)

circle := scene.NewCircleShape(50, 50, 30)
s.Fill(scene.FillNonZero, scene.TranslateAffine(100, 0), scene.SolidBrush(gg.Blue), circle)

pm := gg.NewPixmap(200, 100)
b.RenderScene(pm, s)

Performance Characteristics

The GPU backend excels at:

  • Large canvases (1080p and above)
  • Many shapes with the same blend mode
  • Complex layer compositing
  • Parallel processing of independent draws

Software backend may be faster for:

  • Small canvases (< 256x256)
  • Single shape renders
  • Frequent GPU-CPU data transfers

Memory Management

The backend uses an LRU-based memory manager with configurable budget: 

// Configure via GPUSceneRendererConfig
config := GPUSceneRendererConfig{
    Width:          1920,
    Height:         1080,
    MaxLayers:      16,     // Maximum layer stack depth
    MemoryBudgetMB: 256,    // GPU texture memory budget
}

When memory budget is exceeded, least-recently-used textures are evicted.

Current Status (v0.9.0)

The GPU pipeline implementation is complete. The following components are fully implemented and tested:

  • Path tessellation to sparse strips
  • Strip buffer packing for GPU upload
  • Active Edge Table scanline conversion
  • Fill rule support (NonZero, EvenOdd)
  • Anti-aliased coverage calculation
  • Pipeline cache for all blend modes
  • WGSL shader generation
  • Memory management with LRU eviction
  • Layer stack management
  • Clip region support

GPU operations currently run as stubs that prepare all data but don't execute actual GPU commands. This will be enabled when gogpu/wgpu implements the remaining core functionality:

  • Texture readback (for downloading GPU results to CPU)
  • Buffer mapping (for uploading vertex/uniform data)
  • Command buffer execution

All data flow through the pipeline is correct and tested.

Requirements

  • Go 1.25+ (for generic features)
  • gogpu/wgpu module (github.com/gogpu/wgpu)
  • A GPU that supports Vulkan, Metal, or DX12 (for actual GPU rendering)

Thread Safety

WGPUBackend and GPUSceneRenderer are safe for concurrent use from multiple goroutines. Internal synchronization is handled via mutexes.

Error Handling

Common errors returned by this package:

  • ErrNotInitialized: Backend must be initialized before use
  • ErrNoGPU: No compatible GPU found
  • ErrDeviceLost: GPU device was lost (requires re-initialization)
  • ErrNilTarget: Target pixmap is nil
  • ErrNilScene: Scene is nil
  • ErrRendererClosed: Renderer has been closed
  • ErrEmptyScene: Scene contains no draw commands

Benchmarking

Run benchmarks to compare GPU vs Software performance: 

go test -bench=. ./backend/wgpu/...

Key benchmarks:

  • BenchmarkTessellation: Path to strips conversion
  • BenchmarkStripPacking: GPU data preparation
  • BenchmarkClear1080p: Full canvas clear comparison
  • BenchmarkRect100: 100 rectangles comparison
  • BenchmarkLayers4: Layer compositing comparison
  • github.com/gogpu/gg: Core 2D graphics library
  • github.com/gogpu/gg/scene: Scene graph and retained mode API
  • github.com/gogpu/gg/backend: Backend interface and registry
  • github.com/gogpu/wgpu: Pure Go WebGPU implementation

References

Package wgpu provides GPU-accelerated rendering backend using WebGPU.

Index

Constants

View Source 
const (
	// DefaultAtlasSize is the default atlas dimension (2048x2048).
	DefaultAtlasSize = 2048

	// MinAtlasSize is the minimum atlas dimension (256x256).
	MinAtlasSize = 256

	// DefaultShelfPadding is the padding between shelves.
	DefaultShelfPadding = 1
)

Default atlas settings.

View Source 
const (
	// DefaultMaxMemoryMB is the default maximum GPU memory budget (256 MB).
	DefaultMaxMemoryMB = 256

	// DefaultEvictionThreshold is when eviction starts (80% of budget).
	DefaultEvictionThreshold = 0.8

	// MinMemoryMB is the minimum allowed memory budget (16 MB).
	MinMemoryMB = 16
)

Default memory limits.

View Source 
const (
	// Standard blend modes (0-11)
	ShaderBlendNormal     uint32 = 0
	ShaderBlendMultiply   uint32 = 1
	ShaderBlendScreen     uint32 = 2
	ShaderBlendOverlay    uint32 = 3
	ShaderBlendDarken     uint32 = 4
	ShaderBlendLighten    uint32 = 5
	ShaderBlendColorDodge uint32 = 6
	ShaderBlendColorBurn  uint32 = 7
	ShaderBlendHardLight  uint32 = 8
	ShaderBlendSoftLight  uint32 = 9
	ShaderBlendDifference uint32 = 10
	ShaderBlendExclusion  uint32 = 11

	// HSL blend modes (12-15)
	ShaderBlendHue        uint32 = 12
	ShaderBlendSaturation uint32 = 13
	ShaderBlendColor      uint32 = 14
	ShaderBlendLuminosity uint32 = 15

	// Porter-Duff modes (16-28)
	ShaderBlendClear           uint32 = 16
	ShaderBlendCopy            uint32 = 17
	ShaderBlendDestination     uint32 = 18
	ShaderBlendSourceOver      uint32 = 19
	ShaderBlendDestinationOver uint32 = 20
	ShaderBlendSourceIn        uint32 = 21
	ShaderBlendDestinationIn   uint32 = 22
	ShaderBlendSourceOut       uint32 = 23
	ShaderBlendDestinationOut  uint32 = 24
	ShaderBlendSourceAtop      uint32 = 25
	ShaderBlendDestinationAtop uint32 = 26
	ShaderBlendXor             uint32 = 27
	ShaderBlendPlus            uint32 = 28
)

Blend mode constants matching scene.BlendMode values. These are used for GPU shader uniform values.

View Source 
const DefaultTextureUsage = types.TextureUsageCopySrc | types.TextureUsageCopyDst | types.TextureUsageTextureBinding

DefaultTextureUsage is the default usage for textures created without specific flags.

Variables

View Source 
var (
	// ErrAtlasFull is returned when the atlas cannot fit the requested region.
	ErrAtlasFull = errors.New("wgpu: texture atlas is full")

	// ErrAtlasClosed is returned when operating on a closed atlas.
	ErrAtlasClosed = errors.New("wgpu: texture atlas is closed")

	// ErrRegionOutOfBounds is returned when a region is outside atlas bounds.
	ErrRegionOutOfBounds = errors.New("wgpu: region is outside atlas bounds")
)

Atlas-related errors.

View Source 
var (
	// ErrNotInitialized is returned when operations are called before Init.
	ErrNotInitialized = errors.New("wgpu: backend not initialized")

	// ErrNoGPU is returned when no GPU adapter is available.
	ErrNoGPU = errors.New("wgpu: no GPU adapter available")

	// ErrDeviceLost is returned when the GPU device is lost.
	ErrDeviceLost = errors.New("wgpu: GPU device lost")

	// ErrNotImplemented is returned for stub operations not yet implemented.
	ErrNotImplemented = errors.New("wgpu: operation not implemented")

	// ErrInvalidDimensions is returned when width or height is invalid.
	ErrInvalidDimensions = errors.New("wgpu: invalid dimensions")

	// ErrNilTarget is returned when target pixmap is nil.
	ErrNilTarget = errors.New("wgpu: nil target pixmap")

	// ErrNilScene is returned when scene is nil.
	ErrNilScene = errors.New("wgpu: nil scene")
)

Package errors for wgpu backend.

View Source 
var (
	// ErrMemoryBudgetExceeded is returned when allocation would exceed budget.
	ErrMemoryBudgetExceeded = errors.New("wgpu: memory budget exceeded")

	// ErrMemoryManagerClosed is returned when operating on a closed manager.
	ErrMemoryManagerClosed = errors.New("wgpu: memory manager closed")

	// ErrTextureNotFound is returned when a texture is not found in the manager.
	ErrTextureNotFound = errors.New("wgpu: texture not found in manager")
)

Memory management errors.

View Source 
var (
	// ErrRendererClosed is returned when operating on a closed renderer.
	ErrRendererClosed = errors.New("wgpu: renderer closed")

	// ErrEmptyScene is returned when rendering an empty scene.
	ErrEmptyScene = errors.New("wgpu: empty scene")

	// ErrLayerStackUnderflow is returned when popping more layers than pushed.
	ErrLayerStackUnderflow = errors.New("wgpu: layer stack underflow")
)

Renderer-specific errors.

View Source 
var (
	// ErrNilTextPipeline is returned when operating on a nil pipeline.
	ErrNilTextPipeline = errors.New("wgpu: text pipeline is nil")

	// ErrTextPipelineNotInitialized is returned when pipeline is not initialized.
	ErrTextPipelineNotInitialized = errors.New("wgpu: text pipeline not initialized")

	// ErrNoQuadsToRender is returned when RenderText is called with empty quads.
	ErrNoQuadsToRender = errors.New("wgpu: no quads to render")

	// ErrQuadBufferOverflow is returned when too many quads are submitted.
	ErrQuadBufferOverflow = errors.New("wgpu: quad buffer overflow")

	// ErrInvalidAtlasIndex is returned when referencing invalid atlas.
	ErrInvalidAtlasIndex = errors.New("wgpu: invalid atlas index")
)

Text rendering errors.

View Source 
var (
	// ErrTextureReleased is returned when operating on a released texture.
	ErrTextureReleased = errors.New("wgpu: texture has been released")

	// ErrTextureSizeMismatch is returned when pixmap size doesn't match texture.
	ErrTextureSizeMismatch = errors.New("wgpu: pixmap size does not match texture")

	// ErrNilPixmap is returned when pixmap is nil.
	ErrNilPixmap = errors.New("wgpu: pixmap is nil")

	// ErrTextureReadbackNotSupported is returned when readback is not available.
	ErrTextureReadbackNotSupported = errors.New("wgpu: texture readback not supported (stub)")
)

Texture-related errors.

View Source 
var ErrNilBackend = errors.New("wgpu: backend is nil")

ErrNilBackend is returned when backend is nil.

Functions

func BlendModeToShader 

func BlendModeToShader(mode scene.BlendMode) uint32

BlendModeToShader converts a scene.BlendMode to the shader constant value. The values are designed to match directly, so this is primarily for type safety.

func CheckDeviceLimits 

func CheckDeviceLimits(deviceID core.DeviceID) error

CheckDeviceLimits verifies that the device meets minimum requirements. This can be used to validate GPU capabilities before rendering.

func GetBlendShaderSource 

func GetBlendShaderSource() string

GetBlendShaderSource returns the WGSL source for the blend shader.

func GetBlitShaderSource 

func GetBlitShaderSource() string

GetBlitShaderSource returns the WGSL source for the blit shader.

func GetCompositeShaderSource 

func GetCompositeShaderSource() string

GetCompositeShaderSource returns the WGSL source for the composite shader.

func GetMSDFTextShaderSource added in v0.11.0 

func GetMSDFTextShaderSource() string

GetMSDFTextShaderSource returns the WGSL source for the MSDF text shader.

func GetStripShaderSource 

func GetStripShaderSource() string

GetStripShaderSource returns the WGSL source for the strip shader.

func ShaderToBlendMode 

func ShaderToBlendMode(shaderMode uint32) scene.BlendMode

ShaderToBlendMode converts a shader blend mode constant to scene.BlendMode.

func ValidateBlendModeMapping 

func ValidateBlendModeMapping() error

ValidateBlendModeMapping verifies that shader constants match scene.BlendMode values. Returns an error if any mismatch is found.

Types

type ActiveEdge 

type ActiveEdge struct {
	Edge *Edge
	X    float32 // Current X position at current scanline
}

ActiveEdge holds an edge with its current X position.

type ActiveEdgeTable 

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

ActiveEdgeTable manages active edges during scanline conversion.

func NewActiveEdgeTable 

func NewActiveEdgeTable() *ActiveEdgeTable

NewActiveEdgeTable creates a new active edge table.

func (*ActiveEdgeTable) Active 

func (aet *ActiveEdgeTable) Active() []ActiveEdge

Active returns the list of active edges for iteration.

func (*ActiveEdgeTable) InsertEdge 

func (aet *ActiveEdgeTable) InsertEdge(e *Edge, y float32)

InsertEdge adds an edge to the active list.

func (*ActiveEdgeTable) Len 

func (aet *ActiveEdgeTable) Len() int

Len returns the number of active edges.

func (*ActiveEdgeTable) RemoveExpired 

func (aet *ActiveEdgeTable) RemoveExpired(y float32)

RemoveExpired removes edges that end at or before the given Y.

func (*ActiveEdgeTable) Reset 

func (aet *ActiveEdgeTable) Reset()

Reset clears the active edge table.

func (*ActiveEdgeTable) SortByX 

func (aet *ActiveEdgeTable) SortByX()

SortByX sorts active edges by their current X position.

func (*ActiveEdgeTable) UpdateX 

func (aet *ActiveEdgeTable) UpdateX(y float32)

UpdateX updates X positions for all active edges at the new Y.

type AtlasRegion 

type AtlasRegion struct {
	// X is the left edge of the region.
	X int
	// Y is the top edge of the region.
	Y int
	// Width is the region width.
	Width int
	// Height is the region height.
	Height int
}

AtlasRegion represents a rectangular region in a texture atlas.

func (AtlasRegion) Contains 

func (r AtlasRegion) Contains(x, y int) bool

Contains returns true if the point (x, y) is inside the region.

func (AtlasRegion) IsValid 

func (r AtlasRegion) IsValid() bool

IsValid returns true if the region has valid dimensions.

func (AtlasRegion) String 

func (r AtlasRegion) String() string

String returns a string representation of the region.

type BindGroupBuilder 

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

BindGroupBuilder helps construct bind groups for rendering.

func NewBindGroupBuilder 

func NewBindGroupBuilder(device core.DeviceID, layout StubBindGroupLayoutID) *BindGroupBuilder

NewBindGroupBuilder creates a new bind group builder.

func (*BindGroupBuilder) Build 

func (b *BindGroupBuilder) Build() StubBindGroupID

Build creates the bind group. Currently returns a stub.

type BlendParams 

type BlendParams struct {
	Mode    uint32  // Blend mode enum value
	Alpha   float32 // Layer opacity (0.0 - 1.0)
	Padding [2]float32
}

BlendParams represents the uniform buffer structure for blend shaders. This matches the BlendParams struct in blend.wgsl.

type CommandBuffer 

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

CommandBuffer represents a finished command buffer ready for submission.

func NewCommandBuffer 

func NewCommandBuffer(id StubCommandBufferID) *CommandBuffer

NewCommandBuffer wraps a command buffer ID.

func (*CommandBuffer) ID 

func (b *CommandBuffer) ID() StubCommandBufferID

ID returns the underlying command buffer ID.

type CommandEncoder 

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

CommandEncoder wraps GPU command encoding operations. It provides a high-level interface for building command buffers that can be submitted to the GPU queue.

CommandEncoder accumulates render passes and compute passes, then produces a command buffer when Finish is called.

func NewCommandEncoder 

func NewCommandEncoder(device core.DeviceID) *CommandEncoder

NewCommandEncoder creates a new command encoder for the given device.

func (*CommandEncoder) BeginComputePass 

func (e *CommandEncoder) BeginComputePass() *ComputePass

BeginComputePass begins a new compute pass.

func (*CommandEncoder) BeginRenderPass 

func (e *CommandEncoder) BeginRenderPass(target *GPUTexture, clearTarget bool) *RenderPass

BeginRenderPass begins a new render pass targeting the specified texture. If clearTarget is true, the texture is cleared to transparent before drawing.

func (*CommandEncoder) CopyTextureToBuffer 

func (e *CommandEncoder) CopyTextureToBuffer(src *GPUTexture, dst StubBufferID, bytesPerRow uint32)

CopyTextureToBuffer copies a texture to a buffer for readback.

func (*CommandEncoder) CopyTextureToTexture 

func (e *CommandEncoder) CopyTextureToTexture(src, dst *GPUTexture, width, height int)

CopyTextureToTexture copies a region from one texture to another.

func (*CommandEncoder) Finish 

func (e *CommandEncoder) Finish() StubCommandBufferID

Finish completes the command encoder and returns the command buffer. The encoder cannot be used after calling Finish.

func (*CommandEncoder) PassCount 

func (e *CommandEncoder) PassCount() int

PassCount returns the number of passes recorded.

type CompositeParams 

type CompositeParams struct {
	LayerCount uint32 // Number of layers to composite
	Width      uint32 // Output width
	Height     uint32 // Output height
	Padding    uint32 // Alignment padding
}

CompositeParams represents the uniform buffer structure for composite shaders. This matches the CompositeParams struct in composite.wgsl.

type ComputeCommandBuilder 

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

ComputeCommandBuilder provides a fluent API for building compute commands.

func NewComputeCommandBuilder 

func NewComputeCommandBuilder(device core.DeviceID) *ComputeCommandBuilder

NewComputeCommandBuilder creates a new compute command builder.

func (*ComputeCommandBuilder) Dispatch 

func (b *ComputeCommandBuilder) Dispatch(x, y, z uint32) *ComputeCommandBuilder

Dispatch dispatches workgroups.

func (*ComputeCommandBuilder) DispatchForSize 

func (b *ComputeCommandBuilder) DispatchForSize(size, groupSize uint32) *ComputeCommandBuilder

DispatchForSize calculates and dispatches for a work size.

func (*ComputeCommandBuilder) Finish 

func (b *ComputeCommandBuilder) Finish() StubCommandBufferID

Finish ends the pass and returns the command buffer.

func (*ComputeCommandBuilder) SetBindGroup 

func (b *ComputeCommandBuilder) SetBindGroup(index uint32, bindGroup StubBindGroupID) *ComputeCommandBuilder

SetBindGroup sets a bind group.

func (*ComputeCommandBuilder) SetPipeline 

func (b *ComputeCommandBuilder) SetPipeline(pipeline StubComputePipelineID) *ComputeCommandBuilder

SetPipeline sets the compute pipeline.

type ComputePass 

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

ComputePass represents an active compute pass for dispatch commands.

func (*ComputePass) DispatchWorkgroups 

func (p *ComputePass) DispatchWorkgroups(workgroupCountX, workgroupCountY, workgroupCountZ uint32)

DispatchWorkgroups dispatches compute work. workgroupCountX/Y/Z: number of workgroups in each dimension

func (*ComputePass) DispatchWorkgroupsForSize 

func (p *ComputePass) DispatchWorkgroupsForSize(workSize, workgroupSize uint32)

DispatchWorkgroupsForSize calculates and dispatches workgroups for a given work size. workSize: total number of work items workgroupSize: number of items per workgroup (typically 64 or 256)

func (*ComputePass) End 

func (p *ComputePass) End()

End finishes the compute pass.

func (*ComputePass) SetBindGroup 

func (p *ComputePass) SetBindGroup(index uint32, bindGroup StubBindGroupID)

SetBindGroup sets a bind group at the specified index.

func (*ComputePass) SetPipeline 

func (p *ComputePass) SetPipeline(pipeline StubComputePipelineID)

SetPipeline sets the compute pipeline for subsequent dispatch calls.

type Edge 

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

Edge represents a line segment for scanline conversion. Edges are derived from path segments (lines, curves flattened to lines) and used by the Active Edge Table algorithm.

func NewEdge 

func NewEdge(x0, y0, x1, y1 float32) *Edge

NewEdge creates a new edge from two points. Returns nil if the edge is horizontal (no Y extent).

func NewEdgeWithWinding 

func NewEdgeWithWinding(x0, y0, x1, y1 float32, winding int8) *Edge

NewEdgeWithWinding creates a new edge with explicit winding.

func (*Edge) ContainsY 

func (e *Edge) ContainsY(y float32) bool

ContainsY returns true if Y is within the edge's Y range (inclusive).

func (*Edge) Height 

func (e *Edge) Height() float32

Height returns the vertical extent of the edge.

func (*Edge) IsActiveAt 

func (e *Edge) IsActiveAt(y float32) bool

IsActiveAt returns true if the edge is active at the given Y coordinate. An edge is active when yMin <= y < yMax.

func (*Edge) XAtY 

func (e *Edge) XAtY(y float32) float32

XAtY calculates the X coordinate at a given Y value. This is the core calculation for scanline intersection.

type EdgeList 

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

EdgeList is a collection of edges with utility methods.

func NewEdgeList 

func NewEdgeList() *EdgeList

NewEdgeList creates a new empty edge list.

func (*EdgeList) Add 

func (el *EdgeList) Add(e *Edge)

Add adds an edge to the list.

func (*EdgeList) AddLine 

func (el *EdgeList) AddLine(x0, y0, x1, y1 float32)

AddLine adds a line segment as an edge.

func (*EdgeList) Bounds 

func (el *EdgeList) Bounds() (minX, minY, maxX, maxY float32)

Bounds returns the bounding rectangle of all edges.

func (*EdgeList) Edges 

func (el *EdgeList) Edges() []Edge

Edges returns the underlying slice.

func (*EdgeList) Len 

func (el *EdgeList) Len() int

Len returns the number of edges.

func (*EdgeList) Reset 

func (el *EdgeList) Reset()

Reset clears the edge list for reuse.

func (*EdgeList) SortByYMin 

func (el *EdgeList) SortByYMin()

SortByYMin sorts edges by their minimum Y coordinate.

type GPUInfo 

type GPUInfo struct {
	// Name is the GPU name (e.g., "NVIDIA GeForce RTX 3080").
	Name string
	// Vendor is the GPU vendor.
	Vendor string
	// DeviceType is the type of GPU (discrete, integrated, etc.).
	DeviceType types.DeviceType
	// Backend is the graphics API in use (Vulkan, Metal, DX12).
	Backend types.Backend
	// Driver is the driver version string.
	Driver string
}

GPUInfo contains information about the selected GPU.

func (*GPUInfo) String 

func (g *GPUInfo) String() string

String returns a human-readable description of the GPU.

type GPURenderer 

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

GPURenderer is a GPU-backed renderer for immediate mode drawing. It implements the gg.Renderer interface.

Note: This is a stub implementation. The actual GPU rendering will be implemented in TASK-110.

func (*GPURenderer) Close 

func (r *GPURenderer) Close()

Close releases renderer resources. Note: This is a stub implementation.

func (*GPURenderer) Fill 

func (r *GPURenderer) Fill(pixmap *gg.Pixmap, path *gg.Path, paint *gg.Paint)

Fill fills a path with the given paint. Note: This is a stub implementation.

func (*GPURenderer) Height 

func (r *GPURenderer) Height() int

Height returns the renderer height.

func (*GPURenderer) Stroke 

func (r *GPURenderer) Stroke(pixmap *gg.Pixmap, path *gg.Path, paint *gg.Paint)

Stroke strokes a path with the given paint. Note: This is a stub implementation.

func (*GPURenderer) Width 

func (r *GPURenderer) Width() int

Width returns the renderer width.

type GPUSceneRenderer 

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

GPUSceneRenderer renders scenes using GPU acceleration. It implements the full render pipeline: scene decoding, path tessellation, strip rasterization, and layer compositing.

GPUSceneRenderer is safe for concurrent use from multiple goroutines.

func NewGPUSceneRenderer 

func NewGPUSceneRenderer(backend *WGPUBackend, config GPUSceneRendererConfig) (*GPUSceneRenderer, error)

NewGPUSceneRenderer creates a new GPU scene renderer. The renderer is configured for the specified dimensions.

Returns an error if the backend is not initialized or configuration is invalid.

func (*GPUSceneRenderer) Close 

func (r *GPUSceneRenderer) Close()

Close releases all renderer resources.

func (*GPUSceneRenderer) Height 

func (r *GPUSceneRenderer) Height() int

Height returns the renderer height.

func (*GPUSceneRenderer) LayerDepth 

func (r *GPUSceneRenderer) LayerDepth() int

LayerDepth returns the current layer stack depth.

func (*GPUSceneRenderer) MemoryStats 

func (r *GPUSceneRenderer) MemoryStats() MemoryStats

MemoryStats returns GPU memory usage statistics.

func (*GPUSceneRenderer) RenderScene 

func (r *GPUSceneRenderer) RenderScene(s *scene.Scene) error

RenderScene renders a complete scene to the internal target texture. After rendering, use DownloadPixmap to retrieve the result.

For cancellable rendering, use RenderSceneWithContext.

func (*GPUSceneRenderer) RenderSceneWithContext added in v0.13.0 

func (r *GPUSceneRenderer) RenderSceneWithContext(ctx context.Context, s *scene.Scene) error

RenderSceneWithContext renders a complete scene to the internal target texture with cancellation support.

The context can be used to cancel long-running renders. When canceled, the function returns ctx.Err() and the texture may contain partial results.

func (*GPUSceneRenderer) RenderToPixmap 

func (r *GPUSceneRenderer) RenderToPixmap(target *gg.Pixmap, s *scene.Scene) error

RenderToPixmap renders a scene directly to a pixmap. This is a convenience method that renders and downloads in one call.

For cancellable rendering, use RenderToPixmapWithContext.

func (*GPUSceneRenderer) RenderToPixmapWithContext added in v0.13.0 

func (r *GPUSceneRenderer) RenderToPixmapWithContext(ctx context.Context, target *gg.Pixmap, s *scene.Scene) error

RenderToPixmapWithContext renders a scene directly to a pixmap with cancellation support. This is a convenience method that renders and downloads in one call.

The context can be used to cancel long-running renders. When canceled, the function returns ctx.Err() and the target may contain partial results.

func (*GPUSceneRenderer) Resize 

func (r *GPUSceneRenderer) Resize(width, height int) error

Resize resizes the renderer to new dimensions. All layer textures are released and the target texture is reallocated.

func (*GPUSceneRenderer) Width 

func (r *GPUSceneRenderer) Width() int

Width returns the renderer width.

type GPUSceneRendererConfig 

type GPUSceneRendererConfig struct {
	// Width is the render target width in pixels.
	Width int

	// Height is the render target height in pixels.
	Height int

	// MaxLayers is the maximum layer stack depth (default: 16).
	MaxLayers int

	// MemoryBudgetMB is the texture memory budget in MB (default: 128).
	MemoryBudgetMB int
}

GPUSceneRendererConfig holds configuration for creating a GPUSceneRenderer.

type GPUStripHeader 

type GPUStripHeader struct {
	Y      int32 // Row index
	X      int32 // Start X coordinate
	Width  int32 // Number of pixels
	Offset int32 // Offset into coverage array
}

GPUStripHeader is the header format for GPU strip data. Each strip has a 16-byte header for efficient GPU access.

type GPUTexture 

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

GPUTexture represents a GPU texture resource. It wraps the underlying wgpu texture and provides a high-level interface for texture operations including upload and download.

GPUTexture is safe for concurrent read access. Write operations (Upload, Close) should be synchronized externally.

func CreateTexture 

func CreateTexture(backend *WGPUBackend, config TextureConfig) (*GPUTexture, error)

CreateTexture creates a new GPU texture with the given configuration. The texture is uninitialized and should be filled with UploadPixmap.

Note: This is a stub implementation. The actual GPU texture creation will be implemented when wgpu texture support is complete.

func CreateTextureFromPixmap 

func CreateTextureFromPixmap(backend *WGPUBackend, pixmap *gg.Pixmap, label string) (*GPUTexture, error)

CreateTextureFromPixmap creates a GPU texture from a pixmap, uploading the pixel data immediately.

func (*GPUTexture) Close 

func (t *GPUTexture) Close()

Close releases the GPU texture resources. The texture should not be used after Close is called.

func (*GPUTexture) DownloadPixmap 

func (t *GPUTexture) DownloadPixmap() (*gg.Pixmap, error)

DownloadPixmap downloads pixel data from GPU to a new Pixmap. This operation requires the texture to have CopySrc usage.

Note: This is a stub implementation that returns an error. GPU readback requires staging buffers and synchronization.

func (*GPUTexture) Format 

func (t *GPUTexture) Format() TextureFormat

Format returns the texture format.

func (*GPUTexture) Height 

func (t *GPUTexture) Height() int

Height returns the texture height in pixels.

func (*GPUTexture) IsReleased 

func (t *GPUTexture) IsReleased() bool

IsReleased returns true if the texture has been released.

func (*GPUTexture) Label 

func (t *GPUTexture) Label() string

Label returns the debug label.

func (*GPUTexture) SetMemoryManager 

func (t *GPUTexture) SetMemoryManager(m *MemoryManager)

SetMemoryManager sets the memory manager for tracking. This is called internally when allocating through MemoryManager.

func (*GPUTexture) SizeBytes 

func (t *GPUTexture) SizeBytes() uint64

SizeBytes returns the texture size in bytes.

func (*GPUTexture) String 

func (t *GPUTexture) String() string

String returns a string representation of the texture.

func (*GPUTexture) TextureID 

func (t *GPUTexture) TextureID() core.TextureID

TextureID returns the underlying wgpu texture ID. Returns a zero ID for stub textures.

func (*GPUTexture) UploadPixmap 

func (t *GPUTexture) UploadPixmap(pixmap *gg.Pixmap) error

UploadPixmap uploads pixel data from a Pixmap to the GPU texture. The pixmap dimensions must match the texture dimensions.

Note: This is a stub implementation. The actual GPU upload will be implemented when wgpu queue.WriteTexture is available.

func (*GPUTexture) UploadRegion 

func (t *GPUTexture) UploadRegion(x, y int, pixmap *gg.Pixmap) error

UploadRegion uploads pixel data to a region of the texture. This is useful for texture atlas updates.

Note: This is a stub implementation.

func (*GPUTexture) ViewID 

func (t *GPUTexture) ViewID() core.TextureViewID

ViewID returns the texture view ID. Returns a zero ID for stub textures.

func (*GPUTexture) Width 

func (t *GPUTexture) Width() int

Width returns the texture width in pixels.

type IndexFormat 

type IndexFormat uint32

IndexFormat specifies the format of index buffer elements. 

const (
	// IndexFormatUint16 uses 16-bit unsigned integers.
	IndexFormatUint16 IndexFormat = 0

	// IndexFormatUint32 uses 32-bit unsigned integers.
	IndexFormatUint32 IndexFormat = 1
)

type LayerDescriptor 

type LayerDescriptor struct {
	TextureIdx uint32  // Index into layer textures
	BlendMode  uint32  // Blend mode for this layer
	Alpha      float32 // Layer opacity
	Padding    float32 // Alignment padding
}

LayerDescriptor represents a single layer for compositing. This matches the Layer struct in composite.wgsl.

type MemoryManager 

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

MemoryManager tracks GPU memory allocations and enforces budget limits. It provides LRU eviction when the memory budget is exceeded.

MemoryManager is safe for concurrent use.

func NewMemoryManager 

func NewMemoryManager(backend *WGPUBackend, config MemoryManagerConfig) *MemoryManager

NewMemoryManager creates a new memory manager for GPU memory tracking. The backend parameter is used for texture creation operations.

func (*MemoryManager) AllocTexture 

func (m *MemoryManager) AllocTexture(config TextureConfig) (*GPUTexture, error)

AllocTexture allocates a new texture with the given configuration. If the allocation would exceed the memory budget, LRU eviction is triggered. Returns an error if the allocation cannot be satisfied even after eviction.

func (*MemoryManager) Close 

func (m *MemoryManager) Close()

Close releases all managed textures and closes the memory manager. The manager should not be used after Close is called.

func (*MemoryManager) Contains 

func (m *MemoryManager) Contains(tex *GPUTexture) bool

Contains returns true if the texture is managed by this manager.

func (*MemoryManager) FreeTexture 

func (m *MemoryManager) FreeTexture(tex *GPUTexture) error

FreeTexture releases a texture and returns its memory to the pool. The texture is closed and should not be used after this call.

func (*MemoryManager) SetBudget 

func (m *MemoryManager) SetBudget(megabytes int) error

SetBudget updates the memory budget. If the new budget is lower than current usage, eviction may be triggered.

func (*MemoryManager) Stats 

func (m *MemoryManager) Stats() MemoryStats

Stats returns current memory usage statistics.

func (*MemoryManager) Textures 

func (m *MemoryManager) Textures() []*GPUTexture

Textures returns a slice of all managed textures. The returned slice is a copy and can be safely modified.

func (*MemoryManager) TouchTexture 

func (m *MemoryManager) TouchTexture(tex *GPUTexture)

TouchTexture updates the last-used time of a texture, moving it to the front of the LRU list. Call this when a texture is used for rendering.

type MemoryManagerConfig 

type MemoryManagerConfig struct {
	// MaxMemoryMB is the maximum memory budget in megabytes.
	// Defaults to DefaultMaxMemoryMB if <= 0.
	MaxMemoryMB int

	// EvictionThreshold is the usage fraction at which eviction starts.
	// Defaults to DefaultEvictionThreshold if <= 0.
	EvictionThreshold float64
}

MemoryManagerConfig holds configuration for creating a MemoryManager.

type MemoryStats 

type MemoryStats struct {
	// TotalBytes is the total memory budget in bytes.
	TotalBytes uint64

	// UsedBytes is the currently allocated memory in bytes.
	UsedBytes uint64

	// AvailableBytes is the remaining memory budget.
	AvailableBytes uint64

	// TextureCount is the number of allocated textures.
	TextureCount int

	// EvictionCount is the total number of textures evicted.
	EvictionCount uint64

	// Utilization is the percentage of budget used (0.0 to 1.0).
	Utilization float64
}

MemoryStats contains GPU memory usage statistics.

func (MemoryStats) String 

func (s MemoryStats) String() string

String returns a human-readable string of memory stats.

type PipelineCache 

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

PipelineCache caches compiled GPU pipelines for rendering operations. It manages bind group layouts and pipelines for blit, blend, strip rasterization, and compositing operations.

PipelineCache is safe for concurrent read access. Pipeline creation is synchronized internally.

func NewPipelineCache 

func NewPipelineCache(device core.DeviceID, shaders *ShaderModules) (*PipelineCache, error)

NewPipelineCache creates a new pipeline cache for the given device. It initializes all base pipelines using the provided shader modules.

Returns an error if pipeline creation fails.

func (*PipelineCache) BlendPipelineCount 

func (pc *PipelineCache) BlendPipelineCount() int

BlendPipelineCount returns the number of cached blend pipelines. Useful for debugging and monitoring.

func (*PipelineCache) Close 

func (pc *PipelineCache) Close()

Close releases all pipeline resources.

func (*PipelineCache) CreateBlendBindGroup 

func (pc *PipelineCache) CreateBlendBindGroup(tex *GPUTexture, params *BlendParams) StubBindGroupID

CreateBlendBindGroup creates a bind group for blend operations.

func (*PipelineCache) CreateBlitBindGroup 

func (pc *PipelineCache) CreateBlitBindGroup(tex *GPUTexture) StubBindGroupID

CreateBlitBindGroup creates a bind group for blit operations.

func (*PipelineCache) CreateStripBindGroup 

func (pc *PipelineCache) CreateStripBindGroup(
	headerBuffer StubBufferID,
	coverageBuffer StubBufferID,
	outputTex *GPUTexture,
	params *StripParams,
) StubBindGroupID

CreateStripBindGroup creates a bind group for strip compute operations.

func (*PipelineCache) GetBlendLayout 

func (pc *PipelineCache) GetBlendLayout() StubBindGroupLayoutID

GetBlendLayout returns the bind group layout for blend operations.

func (*PipelineCache) GetBlendPipeline 

func (pc *PipelineCache) GetBlendPipeline(mode scene.BlendMode) StubPipelineID

GetBlendPipeline returns the pipeline for the specified blend mode. Pipelines are created on demand and cached.

func (*PipelineCache) GetBlitLayout 

func (pc *PipelineCache) GetBlitLayout() StubBindGroupLayoutID

GetBlitLayout returns the bind group layout for blit operations.

func (*PipelineCache) GetBlitPipeline 

func (pc *PipelineCache) GetBlitPipeline() StubPipelineID

GetBlitPipeline returns the blit pipeline.

func (*PipelineCache) GetCompositePipeline 

func (pc *PipelineCache) GetCompositePipeline() StubPipelineID

GetCompositePipeline returns the compositing pipeline.

func (*PipelineCache) GetStripLayout 

func (pc *PipelineCache) GetStripLayout() StubBindGroupLayoutID

GetStripLayout returns the bind group layout for strip compute.

func (*PipelineCache) GetStripPipeline 

func (pc *PipelineCache) GetStripPipeline() StubComputePipelineID

GetStripPipeline returns the strip rasterization compute pipeline.

func (*PipelineCache) IsInitialized 

func (pc *PipelineCache) IsInitialized() bool

IsInitialized returns true if the cache has been initialized.

func (*PipelineCache) WarmupBlendPipelines 

func (pc *PipelineCache) WarmupBlendPipelines()

WarmupBlendPipelines pre-creates pipelines for commonly used blend modes. This avoids pipeline compilation stutter during first use.

type QueueSubmitter 

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

QueueSubmitter submits command buffers to a GPU queue.

func NewQueueSubmitter 

func NewQueueSubmitter(queue core.QueueID) *QueueSubmitter

NewQueueSubmitter creates a new queue submitter.

func (*QueueSubmitter) Submit 

func (s *QueueSubmitter) Submit(buffers ...*CommandBuffer)

Submit submits command buffers to the queue.

func (*QueueSubmitter) WriteBuffer 

func (s *QueueSubmitter) WriteBuffer(buffer StubBufferID, offset uint64, data []byte)

WriteBuffer writes data to a GPU buffer.

func (*QueueSubmitter) WriteTexture 

func (s *QueueSubmitter) WriteTexture(texture *GPUTexture, data []byte)

WriteTexture writes data to a GPU texture.

type RectAllocator 

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

RectAllocator implements a simple shelf-packing algorithm for allocating rectangular regions within a fixed-size area.

The shelf-packing algorithm works by dividing the atlas into horizontal "shelves". Each new rectangle is placed on the current shelf if it fits, or a new shelf is created below.

func NewRectAllocator 

func NewRectAllocator(width, height, padding int) *RectAllocator

NewRectAllocator creates a new rectangular region allocator.

func (*RectAllocator) AllocCount 

func (a *RectAllocator) AllocCount() int

AllocCount returns the number of successful allocations.

func (*RectAllocator) Allocate 

func (a *RectAllocator) Allocate(width, height int) AtlasRegion

Allocate finds space for a rectangle of the given size. Returns an invalid region if the rectangle cannot be allocated.

func (*RectAllocator) Reset 

func (a *RectAllocator) Reset()

Reset clears all allocations, making the entire area available again.

func (*RectAllocator) UsedArea 

func (a *RectAllocator) UsedArea() int

UsedArea returns the total area of allocated rectangles.

func (*RectAllocator) Utilization 

func (a *RectAllocator) Utilization() float64

Utilization returns the fraction of area used (0.0 to 1.0).

type RenderCommandBuilder 

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

RenderCommandBuilder provides a fluent API for building render commands.

func NewRenderCommandBuilder 

func NewRenderCommandBuilder(device core.DeviceID, target *GPUTexture, clearTarget bool) *RenderCommandBuilder

NewRenderCommandBuilder creates a new render command builder.

func (*RenderCommandBuilder) Draw 

func (b *RenderCommandBuilder) Draw(vertexCount, instanceCount uint32) *RenderCommandBuilder

Draw issues a draw call.

func (*RenderCommandBuilder) DrawFullScreen 

func (b *RenderCommandBuilder) DrawFullScreen() *RenderCommandBuilder

DrawFullScreen draws a full-screen triangle.

func (*RenderCommandBuilder) Finish 

func (b *RenderCommandBuilder) Finish() StubCommandBufferID

Finish ends the pass and returns the command buffer.

func (*RenderCommandBuilder) SetBindGroup 

func (b *RenderCommandBuilder) SetBindGroup(index uint32, bindGroup StubBindGroupID) *RenderCommandBuilder

SetBindGroup sets a bind group.

func (*RenderCommandBuilder) SetPipeline 

func (b *RenderCommandBuilder) SetPipeline(pipeline StubPipelineID) *RenderCommandBuilder

SetPipeline sets the render pipeline.

type RenderPass 

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

RenderPass represents an active render pass for draw commands. Draw commands can only be issued while a render pass is active.

func (*RenderPass) Draw 

func (p *RenderPass) Draw(vertexCount, instanceCount, firstVertex, firstInstance uint32)

Draw issues a non-indexed draw call. vertexCount: number of vertices to draw instanceCount: number of instances to draw firstVertex: offset into the vertex buffer firstInstance: instance ID offset

func (*RenderPass) DrawFullScreenTriangle 

func (p *RenderPass) DrawFullScreenTriangle()

DrawFullScreenTriangle is a convenience method for drawing a full-screen triangle. This is commonly used for post-processing effects and texture blits. Uses 3 vertices with no instance or offset.

func (*RenderPass) DrawIndexed 

func (p *RenderPass) DrawIndexed(indexCount, instanceCount, firstIndex uint32, baseVertex int32, firstInstance uint32)

DrawIndexed issues an indexed draw call.

func (*RenderPass) End 

func (p *RenderPass) End()

End finishes the render pass. No more draw calls can be issued after this.

func (*RenderPass) SetBindGroup 

func (p *RenderPass) SetBindGroup(index uint32, bindGroup StubBindGroupID)

SetBindGroup sets a bind group at the specified index.

func (*RenderPass) SetIndexBuffer 

func (p *RenderPass) SetIndexBuffer(buffer StubBufferID, format IndexFormat)

SetIndexBuffer sets the index buffer for indexed drawing.

func (*RenderPass) SetPipeline 

func (p *RenderPass) SetPipeline(pipeline StubPipelineID)

SetPipeline sets the render pipeline for subsequent draw calls.

func (*RenderPass) SetVertexBuffer 

func (p *RenderPass) SetVertexBuffer(slot uint32, buffer StubBufferID)

SetVertexBuffer sets a vertex buffer at the specified slot.

func (*RenderPass) Target 

func (p *RenderPass) Target() *GPUTexture

Target returns the render target texture.

type ShaderModuleID 

type ShaderModuleID uint64

ShaderModuleID represents a compiled shader module handle. This is a placeholder type that will be replaced with the actual wgpu core.ShaderModuleID once shader compilation is implemented. 

const InvalidShaderModule ShaderModuleID = 0

InvalidShaderModule represents an invalid/uninitialized shader module.

type ShaderModules 

type ShaderModules struct {
	// Blit is the simple texture copy shader
	Blit ShaderModuleID

	// Blend is the 29-mode blend shader
	Blend ShaderModuleID

	// Strip is the strip rasterization compute shader
	Strip ShaderModuleID

	// Composite is the final layer compositing shader
	Composite ShaderModuleID
}

ShaderModules holds compiled shader modules for all rendering operations.

func CompileShaders 

func CompileShaders(deviceID uint64) (*ShaderModules, error)

CompileShaders compiles all WGSL shaders and returns the shader modules. This function currently returns stub module IDs since gogpu/wgpu shader compilation is not yet fully implemented. The WGSL sources are validated for correct syntax.

Parameters:

  • deviceID: The GPU device ID to use for compilation (currently unused)

Returns:

  • *ShaderModules: Compiled shader module handles
  • error: Compilation error if shader sources are invalid

func (*ShaderModules) IsValid 

func (s *ShaderModules) IsValid() bool

IsValid returns true if all shader modules are initialized.

type Strip 

type Strip struct {
	// Y is the row index (scanline number)
	Y int32

	// X is the starting X coordinate of the strip
	X int32

	// Width is the number of pixels in this strip
	Width int32

	// Coverage holds anti-aliased coverage values (0-255) for each pixel
	Coverage []uint8
}

Strip represents one horizontal span of coverage. A strip stores the coverage values for a contiguous horizontal range of pixels at a specific row. Only non-zero coverage regions are stored (sparse).

func (*Strip) Clone 

func (s *Strip) Clone() Strip

Clone creates a deep copy of the strip.

func (*Strip) End 

func (s *Strip) End() int32

End returns the X coordinate of the pixel just past the strip.

type StripBuffer 

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

StripBuffer holds all strips for a tessellated path. It provides methods to accumulate strips during tessellation and pack them for GPU upload.

func NewStripBuffer 

func NewStripBuffer() *StripBuffer

NewStripBuffer creates a new empty strip buffer.

func (*StripBuffer) AddStrip 

func (sb *StripBuffer) AddStrip(y, x int, coverage []uint8)

AddStrip adds a strip to the buffer. The coverage slice is copied, so the caller can reuse it.

func (*StripBuffer) AddStripDirect 

func (sb *StripBuffer) AddStripDirect(y, x int32, coverage []uint8)

AddStripDirect adds a strip without copying the coverage slice. The caller must not modify the coverage slice after this call.

func (*StripBuffer) Bounds 

func (sb *StripBuffer) Bounds() scene.Rect

Bounds returns the bounding rectangle of all strips.

func (*StripBuffer) Clone 

func (sb *StripBuffer) Clone() *StripBuffer

Clone creates a deep copy of the strip buffer.

func (*StripBuffer) FillRule 

func (sb *StripBuffer) FillRule() scene.FillStyle

FillRule returns the current fill rule.

func (*StripBuffer) IsEmpty 

func (sb *StripBuffer) IsEmpty() bool

IsEmpty returns true if the buffer contains no strips.

func (*StripBuffer) MemorySize 

func (sb *StripBuffer) MemorySize() int

MemorySize returns the approximate memory usage in bytes.

func (*StripBuffer) MergeAdjacent 

func (sb *StripBuffer) MergeAdjacent()

MergeAdjacent merges horizontally adjacent strips on the same row. This reduces the number of strips and improves GPU efficiency.

func (*StripBuffer) PackForGPU 

func (sb *StripBuffer) PackForGPU() (headers []GPUStripHeader, coverage []uint8)

PackForGPU returns GPU-ready data: headers and packed coverage. The headers array contains one GPUStripHeader per strip. The coverage array contains all coverage values packed contiguously.

func (*StripBuffer) PackForGPUInto 

func (sb *StripBuffer) PackForGPUInto(headers []GPUStripHeader, coverage []uint8) int

PackForGPUInto packs GPU data into provided slices to avoid allocation. Returns the number of strips packed, or -1 if buffers are too small.

func (*StripBuffer) Reset 

func (sb *StripBuffer) Reset()

Reset clears the buffer for reuse without deallocating memory.

func (*StripBuffer) SetFillRule 

func (sb *StripBuffer) SetFillRule(rule scene.FillStyle)

SetFillRule sets the fill rule for coverage interpretation.

func (*StripBuffer) StripCount 

func (sb *StripBuffer) StripCount() int

StripCount returns the number of strips in the buffer.

func (*StripBuffer) Strips 

func (sb *StripBuffer) Strips() []Strip

Strips returns the slice of strips.

func (*StripBuffer) TotalCoverage 

func (sb *StripBuffer) TotalCoverage() int

TotalCoverage returns the total number of coverage values across all strips.

type StripParams 

type StripParams struct {
	Color        [4]float32 // Fill color (premultiplied RGBA)
	TargetWidth  int32      // Output texture width
	TargetHeight int32      // Output texture height
	StripCount   int32      // Number of strips to process
	Padding      int32      // Alignment padding
}

StripParams represents the uniform buffer structure for strip shaders. This matches the StripParams struct in strip.wgsl.

type StubBindGroupID 

type StubBindGroupID uint64

StubBindGroupID is a placeholder for actual wgpu BindGroupID.

type StubBindGroupLayoutID 

type StubBindGroupLayoutID uint64

StubBindGroupLayoutID is a placeholder for actual wgpu BindGroupLayoutID.

type StubBufferID 

type StubBufferID uint64

StubBufferID is a placeholder for actual wgpu BufferID.

type StubCommandBufferID 

type StubCommandBufferID uint64

StubCommandBufferID is a placeholder for actual wgpu CommandBufferID.

type StubCommandEncoderID 

type StubCommandEncoderID uint64

StubCommandEncoderID is a placeholder for actual wgpu CommandEncoderID.

type StubComputePassID 

type StubComputePassID uint64

StubComputePassID is a placeholder for actual wgpu ComputePassID.

type StubComputePipelineID 

type StubComputePipelineID uint64

StubComputePipelineID is a placeholder for actual wgpu ComputePipelineID.

type StubPipelineID 

type StubPipelineID uint64

StubPipelineID is a placeholder for actual wgpu RenderPipelineID. This will be replaced with core.RenderPipelineID when wgpu support is complete. 

const InvalidPipelineID StubPipelineID = 0

InvalidPipelineID represents an invalid/uninitialized pipeline.

type StubRenderPassID 

type StubRenderPassID uint64

StubRenderPassID is a placeholder for actual wgpu RenderPassID.

type StubSamplerID added in v0.11.0 

type StubSamplerID uint64

StubSamplerID is a placeholder for actual wgpu SamplerID.

type Tessellator 

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

Tessellator converts paths to sparse strips for GPU rendering. It uses scanline conversion with the Active Edge Table algorithm to produce anti-aliased coverage strips.

func NewTessellator 

func NewTessellator() *Tessellator

NewTessellator creates a new tessellator.

func (*Tessellator) Reset 

func (t *Tessellator) Reset()

Reset clears the tessellator for reuse.

func (*Tessellator) SetAntiAlias 

func (t *Tessellator) SetAntiAlias(aa bool)

SetAntiAlias enables or disables anti-aliasing.

func (*Tessellator) SetFillRule 

func (t *Tessellator) SetFillRule(rule scene.FillStyle)

SetFillRule sets the fill rule for the tessellator.

func (*Tessellator) SetFlattenTolerance 

func (t *Tessellator) SetFlattenTolerance(tolerance float32)

SetFlattenTolerance sets the curve flattening tolerance.

func (*Tessellator) TessellateCircle 

func (t *Tessellator) TessellateCircle(cx, cy, r float32) *StripBuffer

TessellateCircle is a convenience method for tessellating a circle.

func (*Tessellator) TessellatePath 

func (t *Tessellator) TessellatePath(path *scene.Path, transform scene.Affine) *StripBuffer

TessellatePath converts a path to strips. The path is transformed by the given affine transformation.

func (*Tessellator) TessellateRect 

func (t *Tessellator) TessellateRect(x, y, w, h float32) *StripBuffer

TessellateRect is a convenience method for tessellating a rectangle.

type TessellatorPool 

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

TessellatorPool manages a pool of reusable tessellators. It is safe for concurrent use.

func NewTessellatorPool 

func NewTessellatorPool() *TessellatorPool

NewTessellatorPool creates a new tessellator pool.

func (*TessellatorPool) Get 

func (tp *TessellatorPool) Get() *Tessellator

Get retrieves a tessellator from the pool or creates a new one.

func (*TessellatorPool) Put 

func (tp *TessellatorPool) Put(t *Tessellator)

Put returns a tessellator to the pool.

type TextBatch added in v0.11.0 

type TextBatch struct {
	Quads     []TextQuad
	Color     gg.RGBA
	Transform gg.Matrix
}

TextBatch represents a batch of text quads with shared rendering parameters.

type TextPipeline added in v0.11.0 

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

TextPipeline handles GPU-accelerated MSDF text rendering. It manages the render pipeline, bind groups, and vertex buffers for rendering text using multi-channel signed distance fields.

TextPipeline is safe for concurrent use after initialization.

func NewTextPipeline added in v0.11.0 

func NewTextPipeline(device core.DeviceID, config TextPipelineConfig) (*TextPipeline, error)

NewTextPipeline creates a new text rendering pipeline. The pipeline must be initialized before use.

func NewTextPipelineDefault added in v0.11.0 

func NewTextPipelineDefault(device core.DeviceID) (*TextPipeline, error)

NewTextPipelineDefault creates a text pipeline with default configuration.

func (*TextPipeline) Close added in v0.11.0 

func (p *TextPipeline) Close()

Close releases all pipeline resources.

func (*TextPipeline) Config added in v0.11.0 

func (p *TextPipeline) Config() TextPipelineConfig

Config returns the pipeline configuration.

func (*TextPipeline) GetOrCreateAtlasBindGroup added in v0.11.0 

func (p *TextPipeline) GetOrCreateAtlasBindGroup(atlasIndex int, atlasTexture *GPUTexture) (StubBindGroupID, error)

GetOrCreateAtlasBindGroup gets or creates a bind group for an atlas texture.

func (*TextPipeline) Init added in v0.11.0 

func (p *TextPipeline) Init() error

Init initializes the text pipeline, compiling shaders and creating GPU resources.

func (*TextPipeline) InvalidateAllAtlasBindGroups added in v0.11.0 

func (p *TextPipeline) InvalidateAllAtlasBindGroups()

InvalidateAllAtlasBindGroups removes all cached bind groups.

func (*TextPipeline) InvalidateAtlasBindGroup added in v0.11.0 

func (p *TextPipeline) InvalidateAtlasBindGroup(atlasIndex int)

InvalidateAtlasBindGroup removes a cached bind group for an atlas. Call this when an atlas texture is updated.

func (*TextPipeline) IsInitialized added in v0.11.0 

func (p *TextPipeline) IsInitialized() bool

IsInitialized returns true if the pipeline has been initialized.

func (*TextPipeline) RenderText added in v0.11.0 

func (p *TextPipeline) RenderText(
	pass *RenderPass,
	quads []TextQuad,
	atlasIndex int,
	color gg.RGBA,
	transform gg.Matrix,
) error

RenderText renders text quads using the specified atlas. All quads are rendered in a single draw call for efficiency.

Parameters:

  • pass: The render pass to record commands into
  • quads: Text quads to render (position and UV for each glyph)
  • atlasIndex: Index of the MSDF atlas texture to use
  • color: Text color (RGBA, will be premultiplied)
  • transform: 2D affine transform matrix (gg.Matrix)

Note: This is a stub implementation that validates inputs and prepares vertex data. Actual GPU rendering will be implemented when wgpu is ready.

func (*TextPipeline) RenderTextBatch added in v0.11.0 

func (p *TextPipeline) RenderTextBatch(
	pass *RenderPass,
	batches []TextBatch,
	atlasIndex int,
) error

RenderTextBatch renders multiple text batches efficiently. Each batch can have different color and transform but shares the same atlas.

type TextPipelineConfig added in v0.11.0 

type TextPipelineConfig struct {
	// InitialQuadCapacity is the initial vertex buffer capacity in quads.
	// Default: 256
	InitialQuadCapacity int

	// MaxQuadCapacity is the maximum number of quads per draw call.
	// Default: 16384
	MaxQuadCapacity int

	// DefaultPxRange is the default MSDF pixel range.
	// Default: 4.0
	DefaultPxRange float32
}

TextPipelineConfig holds configuration for the text pipeline.

func DefaultTextPipelineConfig added in v0.11.0 

func DefaultTextPipelineConfig() TextPipelineConfig

DefaultTextPipelineConfig returns default configuration.

type TextQuad added in v0.11.0 

type TextQuad struct {
	// Position of quad corners in screen/clip space
	X0, Y0, X1, Y1 float32

	// UV coordinates in MSDF atlas [0, 1]
	U0, V0, U1, V1 float32
}

TextQuad represents a single glyph quad for rendering. Each glyph is rendered as a textured quad with position and UV coordinates.

type TextRenderer added in v0.11.0 

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

TextRenderer provides a higher-level API for rendering text. It combines TextPipeline with AtlasManager for convenient text rendering.

func NewTextRenderer added in v0.11.0 

func NewTextRenderer(backend *WGPUBackend, config TextRendererConfig) (*TextRenderer, error)

NewTextRenderer creates a new text renderer.

func (*TextRenderer) AtlasManager added in v0.11.0 

func (r *TextRenderer) AtlasManager() *msdf.AtlasManager

AtlasManager returns the underlying atlas manager.

func (*TextRenderer) Close added in v0.11.0 

func (r *TextRenderer) Close()

Close releases all renderer resources.

func (*TextRenderer) Init added in v0.11.0 

func (r *TextRenderer) Init() error

Init initializes the text renderer.

func (*TextRenderer) Pipeline added in v0.11.0 

func (r *TextRenderer) Pipeline() *TextPipeline

Pipeline returns the underlying text pipeline.

func (*TextRenderer) SyncAtlases added in v0.11.0 

func (r *TextRenderer) SyncAtlases() error

SyncAtlases uploads dirty atlases to GPU.

type TextRendererConfig added in v0.11.0 

type TextRendererConfig struct {
	// PipelineConfig for the underlying text pipeline.
	PipelineConfig TextPipelineConfig

	// AtlasConfig for the MSDF atlas manager.
	AtlasConfig msdf.AtlasConfig
}

TextRendererConfig holds configuration for TextRenderer.

func DefaultTextRendererConfig added in v0.11.0 

func DefaultTextRendererConfig() TextRendererConfig

DefaultTextRendererConfig returns default configuration.

type TextUniforms added in v0.11.0 

type TextUniforms struct {
	// Transform matrix (4x4 for alignment, row-major)
	// Maps local coordinates to clip space [-1, 1]
	Transform [16]float32

	// Text color (RGBA, premultiplied alpha)
	Color [4]float32

	// MSDF parameters:
	// [0]: px_range (distance range in pixels)
	// [1]: atlas_size (texture size)
	// [2]: outline_width (for outline effect)
	// [3]: reserved
	MSDFParams [4]float32
}

TextUniforms represents the uniform buffer for text shaders. Matches the TextUniforms struct in msdf_text.wgsl.

type TextVertex added in v0.11.0 

type TextVertex struct {
	// Position in local/screen space
	X, Y float32

	// UV coordinates in atlas
	U, V float32
}

TextVertex represents a single vertex for text rendering. Matches the VertexInput struct in msdf_text.wgsl.

type TextureAtlas 

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

TextureAtlas manages a texture atlas for efficient batching of small images. It combines multiple small textures into a single large GPU texture to reduce draw calls and texture binding changes.

TextureAtlas is safe for concurrent use.

func NewTextureAtlas 

func NewTextureAtlas(backend *WGPUBackend, config TextureAtlasConfig) (*TextureAtlas, error)

NewTextureAtlas creates a new texture atlas with the given configuration.

func (*TextureAtlas) AllocCount 

func (a *TextureAtlas) AllocCount() int

AllocCount returns the number of allocated regions.

func (*TextureAtlas) Allocate 

func (a *TextureAtlas) Allocate(width, height int) (AtlasRegion, error)

Allocate finds space for a rectangle of the given size. Returns an invalid region (Width/Height == 0) if the atlas is full.

func (*TextureAtlas) AllocateAndUpload 

func (a *TextureAtlas) AllocateAndUpload(pixmap *gg.Pixmap) (AtlasRegion, error)

AllocateAndUpload combines Allocate and Upload into a single operation. This is a convenience method for adding new images to the atlas.

func (*TextureAtlas) Close 

func (a *TextureAtlas) Close()

Close releases the atlas resources. The atlas should not be used after Close is called.

func (*TextureAtlas) Height 

func (a *TextureAtlas) Height() int

Height returns the atlas height in pixels.

func (*TextureAtlas) IsClosed 

func (a *TextureAtlas) IsClosed() bool

IsClosed returns true if the atlas has been closed.

func (*TextureAtlas) Reset 

func (a *TextureAtlas) Reset()

Reset clears all allocations, making the entire atlas available again. Note: This does not clear the texture data, just the allocation tracking.

func (*TextureAtlas) Texture 

func (a *TextureAtlas) Texture() *GPUTexture

Texture returns the underlying GPU texture.

func (*TextureAtlas) Upload 

func (a *TextureAtlas) Upload(region AtlasRegion, pixmap *gg.Pixmap) error

Upload copies pixel data from a pixmap to a region of the atlas. The pixmap dimensions must match the region dimensions.

func (*TextureAtlas) Utilization 

func (a *TextureAtlas) Utilization() float64

Utilization returns the fraction of atlas area used (0.0 to 1.0).

func (*TextureAtlas) Width 

func (a *TextureAtlas) Width() int

Width returns the atlas width in pixels.

type TextureAtlasConfig 

type TextureAtlasConfig struct {
	// Width is the atlas width in pixels. Defaults to DefaultAtlasSize.
	Width int

	// Height is the atlas height in pixels. Defaults to DefaultAtlasSize.
	Height int

	// Padding is the spacing between regions. Defaults to DefaultShelfPadding.
	Padding int

	// Label is an optional debug label.
	Label string
}

TextureAtlasConfig holds configuration for creating a TextureAtlas.

type TextureConfig 

type TextureConfig struct {
	// Width is the texture width in pixels.
	Width int

	// Height is the texture height in pixels.
	Height int

	// Format is the pixel format.
	Format TextureFormat

	// Label is an optional debug label.
	Label string

	// Usage flags (default: CopySrc | CopyDst | TextureBinding)
	Usage types.TextureUsage
}

TextureConfig holds configuration for creating a new texture.

type TextureFormat 

type TextureFormat uint8

TextureFormat represents the pixel format of a GPU texture. 

const (
	// TextureFormatRGBA8 is the standard RGBA format with 8 bits per channel.
	TextureFormatRGBA8 TextureFormat = iota

	// TextureFormatBGRA8 is BGRA format, often used for surface presentation.
	TextureFormatBGRA8

	// TextureFormatR8 is single-channel 8-bit format, used for masks.
	TextureFormatR8
)

func (TextureFormat) BytesPerPixel 

func (f TextureFormat) BytesPerPixel() int

BytesPerPixel returns the number of bytes per pixel for the format.

func (TextureFormat) String 

func (f TextureFormat) String() string

String returns a human-readable name for the format.

func (TextureFormat) ToWGPUFormat 

func (f TextureFormat) ToWGPUFormat() types.TextureFormat

ToWGPUFormat converts to wgpu types.TextureFormat. This will be used when actual GPU texture creation is implemented.

type WGPUBackend 

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

WGPUBackend is a GPU-accelerated rendering backend using gogpu/wgpu. It implements the backend.RenderBackend interface.

The backend manages GPU resources including instance, adapter, device, and queue. It supports both immediate mode rendering (via NewRenderer) and retained mode rendering (via RenderScene).

func NewWGPUBackend 

func NewWGPUBackend() *WGPUBackend

NewWGPUBackend creates a new WGPU rendering backend. The backend must be initialized with Init() before use.

func (*WGPUBackend) Close 

func (b *WGPUBackend) Close()

Close releases all backend resources. The backend should not be used after Close is called.

func (*WGPUBackend) Device 

func (b *WGPUBackend) Device() core.DeviceID

Device returns the GPU device ID. Returns a zero ID if the backend is not initialized.

func (*WGPUBackend) GPUInfo 

func (b *WGPUBackend) GPUInfo() *GPUInfo

GPUInfo returns information about the selected GPU. Returns nil if the backend is not initialized.

func (*WGPUBackend) Init 

func (b *WGPUBackend) Init() error

Init initializes the backend by creating GPU resources. This includes creating an instance, requesting an adapter, creating a device, and getting the command queue.

Returns an error if GPU initialization fails.

func (*WGPUBackend) IsInitialized 

func (b *WGPUBackend) IsInitialized() bool

IsInitialized returns true if the backend has been initialized.

func (*WGPUBackend) Name 

func (b *WGPUBackend) Name() string

Name returns the backend identifier.

func (*WGPUBackend) NewRenderer 

func (b *WGPUBackend) NewRenderer(width, height int) gg.Renderer

NewRenderer creates a renderer for immediate mode rendering. The renderer is sized for the given dimensions.

Note: This is a stub implementation that returns a GPURenderer. The actual GPU rendering will be implemented in TASK-110.

func (*WGPUBackend) Queue 

func (b *WGPUBackend) Queue() core.QueueID

Queue returns the GPU queue ID. Returns a zero ID if the backend is not initialized.

func (*WGPUBackend) RenderScene 

func (b *WGPUBackend) RenderScene(target *gg.Pixmap, s *scene.Scene) error

RenderScene renders a scene to the target pixmap using retained mode. This method is optimized for complex scenes with many draw operations.

The implementation uses GPUSceneRenderer for tessellation, strip rasterization, and layer compositing on the GPU. When wgpu texture readback is fully implemented, results will be downloaded to the target pixmap. Currently, data flows through the GPU pipeline as stubs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.