surface

type BackendNotFoundError struct {
	Name string
}

type BackendUnavailableError struct {
	Name string
}

type BlendMode uint8

type BlendableSurface interface {
	Surface

	// SetBlendMode sets the blend mode for subsequent operations.
	SetBlendMode(mode BlendMode)

	// BlendMode returns the current blend mode.
	BlendMode() BlendMode
}

type Capabilities struct {
	// SupportsSubSurface indicates CreateSubSurface is available.
	SupportsSubSurface bool

	// SupportsResize indicates Resize is available.
	SupportsResize bool

	// SupportsClipping indicates clipping operations are available.
	SupportsClipping bool

	// SupportsBlendModes indicates blend mode control is available.
	SupportsBlendModes bool

	// SupportsAntialias indicates anti-aliased rendering is available.
	SupportsAntialias bool

	// MaxWidth is the maximum supported width (0 = unlimited).
	MaxWidth int

	// MaxHeight is the maximum supported height (0 = unlimited).
	MaxHeight int
}

type CapableSurface interface {
	Surface

	// Capabilities returns the surface's capabilities.
	Capabilities() Capabilities
}

type ClippableSurface interface {
	Surface

	// SetClip sets the clipping region.
	// Only pixels within the path will be affected by subsequent operations.
	SetClip(path *Path)

	// ClearClip removes the clipping region.
	ClearClip()

	// PushClip saves the current clip state.
	PushClip()

	// PopClip restores the previous clip state.
	PopClip()
}

type DrawImageOptions struct {
	// SrcRect is the source rectangle within the image.
	// If nil, the entire image is used.
	SrcRect *image.Rectangle

	// DstRect is the destination rectangle on the surface.
	// If nil, the image is drawn at At with its original size.
	DstRect *image.Rectangle

	// Alpha is the opacity (0.0 = transparent, 1.0 = opaque).
	// Default: 1.0
	Alpha float64

	// Filter is the interpolation mode for scaling.
	Filter Filter
}

type FillRule uint8

type FillStyle struct {
	// Color is the fill color.
	Color color.Color

	// Rule is the fill rule (NonZero or EvenOdd).
	Rule FillRule

	// Pattern is an optional pattern brush for complex fills.
	// When set, takes precedence over Color.
	Pattern Pattern
}

type Filter uint8

type GPUBackend interface {
	// Clear fills the surface with a color.
	Clear(c color.Color)

	// Fill fills a path with the given style.
	Fill(path *Path, style FillStyle)

	// Stroke strokes a path with the given style.
	Stroke(path *Path, style StrokeStyle)

	// DrawImage draws an image at the specified position.
	DrawImage(img image.Image, at Point, opts *DrawImageOptions)

	// Flush ensures all pending operations are submitted.
	Flush() error

	// Readback reads the surface contents to an image.
	Readback() (*image.RGBA, error)

	// Close releases GPU resources.
	Close() error
}

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

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

type LineCap uint8

type LineJoin uint8

type Options struct {
	// Width is the surface width in pixels.
	Width int

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

	// Antialias enables anti-aliased rendering.
	// Default: true
	Antialias bool

	// BackgroundColor is the initial background color.
	// Default: transparent
	BackgroundColor color.Color

	// Custom options for specific backends.
	Custom map[string]any
}

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

type Pattern interface {
	// ColorAt returns the color at the given coordinates.
	ColorAt(x, y float64) color.Color
}

type Point struct {
	X, Y float64
}

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

type RegistryEntry struct {
	// Name is the unique identifier for this backend.
	Name string

	// Priority determines selection order (higher = preferred).
	// Standard priorities:
	//   - 100: GPU backends (Vulkan, Metal, D3D12)
	//   - 50: Hardware-accelerated software (WARP)
	//   - 10: Pure software backends
	Priority int

	// Factory creates surface instances.
	Factory SurfaceFactory

	// Available reports if the backend is available on this system.
	// This is called during registration and cached.
	Available func() bool
}

type ResizableSurface interface {
	Surface

	// Resize changes the surface dimensions.
	// Existing content may be discarded or preserved depending on implementation.
	Resize(width, height int) error
}

type SolidPattern struct {
	Color color.Color
}

type StrokeStyle struct {
	// Color is the stroke color.
	Color color.Color

	// Width is the line width in pixels.
	Width float64

	// Cap is the line cap style.
	Cap LineCap

	// Join is the line join style.
	Join LineJoin

	// MiterLimit is the limit for miter joins.
	// When the miter length exceeds this, a bevel join is used instead.
	MiterLimit float64

	// DashPattern defines the dash/gap pattern.
	// nil or empty means solid line.
	DashPattern []float64

	// DashOffset is the starting offset into the dash pattern.
	DashOffset float64

	// Pattern is an optional pattern brush for complex strokes.
	// When set, takes precedence over Color.
	Pattern Pattern
}

type SubSurface interface {
	Surface

	// CreateSubSurface creates a new surface backed by a region of this surface.
	// Drawing to the sub-surface affects the parent surface.
	CreateSubSurface(bounds image.Rectangle) (Surface, error)
}

type Surface interface {
	// Width returns the surface width in pixels.
	Width() int

	// Height returns the surface height in pixels.
	Height() int

	// Clear fills the entire surface with the given color.
	// This is typically the fastest way to reset the surface.
	Clear(c color.Color)

	// Fill fills the given path using the specified style.
	// The path is not modified or consumed.
	Fill(path *Path, style FillStyle)

	// Stroke strokes the given path using the specified style.
	// The path is not modified or consumed.
	Stroke(path *Path, style StrokeStyle)

	// DrawImage draws an image at the specified position.
	// If opts is nil, default options are used.
	DrawImage(img image.Image, at Point, opts *DrawImageOptions)

	// Flush ensures all pending drawing operations are complete.
	// For CPU surfaces, this is typically a no-op.
	// For GPU surfaces, this may submit commands and wait for completion.
	// Returns an error if flushing fails.
	Flush() error

	// Snapshot returns the current surface contents as an RGBA image.
	// The returned image is a copy; modifications to it do not affect the surface.
	// This may be slow for GPU surfaces as it requires readback.
	Snapshot() *image.RGBA

	// Close releases all resources associated with the surface.
	// After Close, the surface must not be used.
	// Close is idempotent; multiple calls are safe.
	Close() error
}

type SurfaceFactory func(opts Options) (Surface, error)