coord

type Axis uint8

type Coord interface {
	// Frame gives the coord a panel rectangle and that panel's scales, sets
	// the interval each scale maps into, and returns the coord positioned in
	// the rectangle. Cartesian sets the rectangle's edges; Polar sets an angle
	// range and a radius range.
	//
	// The receiver is not modified: the returned value is what the panel's
	// geoms are handed, so two panels drawn on two goroutines never share one
	// position.
	Frame(area ir.Rect, x, y scale.Scale) Coord

	// Extent reports the interval each scale maps into — what Frame chose.
	// A mark that spans a whole axis needs it: the far end of a rule is where
	// the scale ends, and under a polar coord that is not where the rectangle
	// does.
	Extent() (x0, x1, y0, y1 float32)

	// Point turns one mapped pair into a device point.
	Point(x, y float32) ir.Point

	// Points is the batch form, and the one a geom on the hot path calls. It
	// appends into dst, which the caller owns and reuses between frames.
	//
	// It exists so that a per-row interface call does not reappear here: a
	// variadic or per-row method on this interface is the shape that cost a
	// million allocations on a million-row column once already.
	Points(dst []ir.Point, xs, ys []float32) []ir.Point

	// Straight reports whether an edge that is straight in data space is also
	// straight on screen. It is true for Cartesian and for a polar coord asked
	// for chords; it is false for one drawing arcs, where a geom has to build
	// a path instead of a polyline.
	Straight() bool

	// Edge appends the device path of an edge that is straight in data space,
	// continuing from p's current point. Cartesian appends one LineTo; Polar
	// appends the cubics of an arc.
	Edge(p *ir.Path, from, to ir.Point)

	// Area appends the closed device path of a data-space rectangle, given as
	// two mapped pairs. Cartesian appends four corners; Polar appends an
	// annular sector.
	Area(p *ir.Path, x0, y0, x1, y1 float32)

	// Clip appends the path a panel's data is clipped to: the rectangle, or
	// the disc inscribed in it.
	Clip(p *ir.Path, area ir.Rect)

	// Invert turns a device point back into a mapped pair, which is what a
	// tooltip needs before it asks the scales what the values were.
	Invert(pt ir.Point) (x, y float32)

	// Furniture reports the geometry of the grid lines, the axis lines and the
	// tick labels of one panel, one entry per tick in tick order. It fills dst
	// rather than returning a value so that a chart redrawn every frame does
	// not pay for its furniture again; render resets and reuses one.
	Furniture(dst *Furniture, area ir.Rect, m Metrics, xTicks, yTicks []scale.Tick)

	// Decimates reports whether a reduction defined over pixel columns still
	// measures what it was defined to measure under this coord.
	//
	// It is true for Cartesian, where [github.com/timzifer/refract/stat.LTTB]
	// and MinMax bucket by a column of screen and that is exactly the unit
	// they were designed in. It is false for Polar, where a bucket of equal
	// angle is not a bucket of equal width — and nothing polar is a big-data
	// chart, so saying no costs nothing. See docs/adr/0011-decimation.md.
	Decimates() bool
}

type Desc struct {
	// Type is which coord this is.
	Type Type

	// Theta is the axis a polar coord sweeps around the circle.
	Theta Axis
	// Hole is the inner radius as a fraction of the outer one, zero for a
	// coord with no hole.
	Hole float64
	// Radius is how much of the panel's shorter half-side the circle fills.
	Radius float64
	// Start is where the angular scale begins, in radians clockwise from
	// twelve o'clock, and Sweep how much of the circle it covers.
	Start, Sweep float64
	// Counterclockwise reverses the direction the angular scale runs in.
	Counterclockwise bool
	// Chord reports a coord drawing an edge between two marks as the straight
	// line between them rather than as an arc.
	Chord bool
}

type Describer interface {
	Describe() Desc
}

type Exploder interface {
	// Explode reports the device displacement of a mark whose extent in the
	// space the scales map into is the given pair of mapped positions, when it
	// is broken out by the fraction by of the coord's outer radius.
	Explode(x0, y0, x1, y1 float32, by float64) (dx, dy float32)
}

type Furniture struct {
	// AxisX and AxisY are the two axis lines.
	AxisX, AxisY Shape

	// GridX is one shape per X tick and GridY one per Y tick, in tick order.
	// A tick with no grid line — a minor one, or one outside the panel — has
	// an empty shape.
	GridX, GridY []Shape

	// TickX and TickY are the tick marks, in tick order, empty where there is
	// none.
	TickX, TickY []Shape

	// LabelX and LabelY are where the tick labels go, in tick order.
	LabelX, LabelY []Label

	// InX and InY report, per tick, whether the tick falls inside the panel at
	// all. A Cartesian coord culls a tick that a float32 mapping put a hair
	// outside the plot rectangle; a polar one has nothing to fall off.
	InX, InY []bool

	// XLabelsShareARow reports whether the X tick labels sit along one
	// horizontal line and can therefore run into each other. render drops the
	// ones that would overlap when they do — and must not when they do not:
	// two labels on opposite sides of a ring can share an x and still be a
	// finger apart.
	XLabelsShareARow bool
}

type Label struct {
	At ir.Point
	H  ir.HAlign
	V  ir.VAlign
	// Rotation turns the label about its anchor, in radians clockwise. It is
	// zero for every label a Cartesian axis writes.
	Rotation float64
}

type Metrics struct {
	// TickLen is how far a major tick mark reaches out of the axis, and
	// MinorTickLen the same for a minor one.
	TickLen, MinorTickLen float32
	// LabelPad is the gap between the end of a full-length tick mark and the
	// label beyond it.
	LabelPad float32
}

type Option func(*polar)

type Shape struct {
	// Pts is a straight run, empty when the shape is curved.
	Pts []ir.Point
	// Path is a curve, empty when the shape is straight. It is a value rather
	// than a pointer so that its buffers survive [Furniture.Reset].
	Path ir.Path
}

type Type string