pix

type Control interface {
	// Display/human readable name and description.
	Describe() (name, description string)
	// ActualValue returns the current value of the control.
	ActualValue() any
	// ChangeValue attempts to update the ActualValue to newValue.
	ChangeValue(newValue any) error
}

type ControlCurve struct {
	Name        string
	Description string
	Points      []CurvePoint // Control points, X/Y in 0-1 range.
	OnChange    func([]CurvePoint) error
}

type ControlEnum[T enum] struct {
	Name        string
	Description string
	Value       T
	ValidValues []T
	OnChange    func(T) error
}

type ControlOrdered[T cmp.Ordered] struct {
	Name        string
	Description string
	Value       T
	Min         T
	Max         T
	Step        T
	OnChange    func(T) error
}

type CurvePoint = ms2.Vec

type Dims struct {
	Width  int
	Height int
	Stride int
	Shape  Shape
}

type Filter interface {
	// ShapeIO returns expected output and input [pixel.Shape] of the filter.
	// output shape MUST match Process [Dims.Shape] output.
	ShapeIO() (output, input Shape)
	// Process processes an input image and writes the result to
	// destination buffer and returns the dimensions of the resulting image.
	//
	// If destination buffer is nil Filter will assert [ImageBuffered.Buffer] non-nilness
	// and use the buffer as the destination data. In-place does not support ROI.
	// Use [ValidateProcessArgs] to acquire dst buffer and validate arguments.
	//
	// For sub-byte ROI alignment filter must implement bit-level extraction.
	Process(dstOrNilForInPlace []byte, src Image, roi *image.Rectangle) (Dims, error)
	// Controls returns the actual controls of the filter.
	// Controls should remain valid even after calling [Control.ChangeValue]
	// and their [Control.ActualValue] return the updated value.
	Controls() []Control
}

type Image interface {
	// Dims returns information on in-memory image structure.
	// Row spacing must be homogenous in entire image separated by stride bytes.
	Dims() Dims
	// ReadAt reads from the image buffer of pixels, which may be in-memory or elsewhere (disk, network).
	//
	// Users should always try casting [Image] to [ImageBuffered]
	// to see if they can work with the image in-memory which is more efficient.
	io.ReaderAt
}

type ImageBuffered interface {
	Image
	// Buffer returns the raw underlying buffer for images stored in memory.
	// Buffer returns the entire buffer or nil to signal buffer is currently not in memory.
	//
	// Application note: A Load method is not included because
	// if the user wishes for Buffered to be used then the user
	// should worry about loading the buffer early or adding logic to their
	// ImageBuffered implementation so it loads on this Buffer call.
	// Users will decide which works best for their use case.
	Buffer() []byte
}

type Shape int