ebiten/vector/path.go

// Copyright 2019 The Ebiten Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package vector provides functions for vector graphics rendering.
//
// This package is under experiments and the API might be changed with breaking backward compatibility.
package vector

import (
	"math"

	"github.com/hajimehoshi/ebiten/v2"
)

// Direction represents clockwise or counterclockwise.
type Direction int

const (
	Clockwise Direction = iota
	CounterClockwise
)

type point struct {
	x float32
	y float32
}

// Path represents a collection of path segments.
type Path struct {
	segs [][]point
	cur  point
}

// MoveTo skips the current position of the path to the given position (x, y) without adding any strokes.
func (p *Path) MoveTo(x, y float32) {
	p.cur = point{x: x, y: y}
	p.segs = append(p.segs, []point{p.cur})
}

// LineTo adds a line segument to the path, which starts from the current position and ends to the given position (x, y).
//
// LineTo updates the current position to (x, y).
func (p *Path) LineTo(x, y float32) {
	if len(p.segs) == 0 {
		p.segs = append(p.segs, []point{{x: x, y: y}})
		p.cur = point{x: x, y: y}
		return
	}
	seg := p.segs[len(p.segs)-1]
	if seg[len(seg)-1].x != x || seg[len(seg)-1].y != y {
		p.segs[len(p.segs)-1] = append(seg, point{x: x, y: y})
	}
	p.cur = point{x: x, y: y}
}

// QuadTo adds a quadratic Bézier curve to the path.
// (x1, y1) is the control point, and (x2, y2) is the destination.
//
// QuadTo updates the current position to (x2, y2).
func (p *Path) QuadTo(x1, y1, x2, y2 float32) {
	p.quadTo(x1, y1, x2, y2, 0)
}

// lineForTwoPoints returns parameters for a line passing through p0 and p1.
func lineForTwoPoints(p0, p1 point) (a, b, c float32) {
	// Line passing through p0 and p1 in the form of ax + by + c = 0
	a = p1.y - p0.y
	b = -(p1.x - p0.x)
	c = (p1.x-p0.x)*p0.y - (p1.y-p0.y)*p0.x
	return
}

// isPointCloseToSegment detects the distance between a segment (x0, y0)-(x1, y1) and a point (x, y) is less than allow.
func isPointCloseToSegment(x, y, x0, y0, x1, y1 float32, allow float32) bool {
	a, b, c := lineForTwoPoints(point{x: x0, y: y0}, point{x: x1, y: y1})

	// The distance between a line ax+by+c=0 and (x0, y0) is
	//     |ax0 + by0 + c| / √(a² + b²)
	return allow*allow*(a*a+b*b) > (a*x+b*y+c)*(a*x+b*y+c)
}

// crossingPointForTwoLines returns a crossing point for two lines.
func crossingPointForTwoLines(p00, p01, p10, p11 point) point {
	a0, b0, c0 := lineForTwoPoints(p00, p01)
	a1, b1, c1 := lineForTwoPoints(p10, p11)
	det := a0*b1 - a1*b0
	return point{
		x: (b0*c1 - b1*c0) / det,
		y: (a1*c0 - a0*c1) / det,
	}
}

func (p *Path) quadTo(x1, y1, x2, y2 float32, level int) {
	if level > 10 {
		return
	}

	x0 := p.cur.x
	y0 := p.cur.y
	if isPointCloseToSegment(x1, y1, x0, y0, x2, y2, 0.5) {
		p.LineTo(x2, y2)
		return
	}

	x01 := (x0 + x1) / 2
	y01 := (y0 + y1) / 2
	x12 := (x1 + x2) / 2
	y12 := (y1 + y2) / 2
	x012 := (x01 + x12) / 2
	y012 := (y01 + y12) / 2
	p.quadTo(x01, y01, x012, y012, level+1)
	p.quadTo(x12, y12, x2, y2, level+1)
}

// CubicTo adds a cubic Bézier curve to the path.
// (x1, y1) and (x2, y2) are the control points, and (x3, y3) is the destination.
//
// CubicTo updates the current position to (x3, y3).
func (p *Path) CubicTo(x1, y1, x2, y2, x3, y3 float32) {
	p.cubicTo(x1, y1, x2, y2, x3, y3, 0)
}

func (p *Path) cubicTo(x1, y1, x2, y2, x3, y3 float32, level int) {
	if level > 10 {
		return
	}

	x0 := p.cur.x
	y0 := p.cur.y
	if isPointCloseToSegment(x1, y1, x0, y0, x3, y3, 0.5) && isPointCloseToSegment(x2, y2, x0, y0, x3, y3, 0.5) {
		p.LineTo(x3, y3)
		return
	}

	x01 := (x0 + x1) / 2
	y01 := (y0 + y1) / 2
	x12 := (x1 + x2) / 2
	y12 := (y1 + y2) / 2
	x23 := (x2 + x3) / 2
	y23 := (y2 + y3) / 2
	x012 := (x01 + x12) / 2
	y012 := (y01 + y12) / 2
	x123 := (x12 + x23) / 2
	y123 := (y12 + y23) / 2
	x0123 := (x012 + x123) / 2
	y0123 := (y012 + y123) / 2
	p.cubicTo(x01, y01, x012, y012, x0123, y0123, level+1)
	p.cubicTo(x123, y123, x23, y23, x3, y3, level+1)
}

func normalize(x, y float32) (float32, float32) {
	len := float32(math.Hypot(float64(x), float64(y)))
	return x / len, y / len
}

func cross(x0, y0, x1, y1 float32) float32 {
	return x0*y1 - x1*y0
}

// ArcTo adds an arc curve to the path. (x1, y1) is the control point, and (x2, y2) is the destination.
//
// ArcTo updates the current position to (x2, y2).
func (p *Path) ArcTo(x1, y1, x2, y2, radius float32) {
	x0 := p.cur.x
	y0 := p.cur.y
	dx0 := x0 - x1
	dy0 := y0 - y1
	dx1 := x2 - x1
	dy1 := y2 - y1
	dx0, dy0 = normalize(dx0, dy0)
	dx1, dy1 = normalize(dx1, dy1)

	// theta is the angle between two vectors (dx0, dy0) and (dx1, dy1).
	theta := math.Acos(float64(dx0*dx1 + dy0*dy1))
	// TODO: When theta is bigger than π/2, the arc should be split into two.

	// dist is the distance between the control point and the arc's begenning and ending points.
	dist := radius / float32(math.Tan(theta/2))

	// TODO: What if dist is too big?

	// (ax0, ay0) is the start of the arc.
	ax0 := x1 + dx0*dist
	ay0 := y1 + dy0*dist

	var cx, cy, a0, a1 float32
	var dir Direction
	if cross(dx0, dy0, dx1, dy1) >= 0 {
		cx = ax0 - dy0*radius
		cy = ay0 + dx0*radius
		a0 = float32(math.Atan2(float64(-dx0), float64(dy0)))
		a1 = float32(math.Atan2(float64(dx1), float64(-dy1)))
		dir = CounterClockwise
	} else {
		cx = ax0 + dy0*radius
		cy = ay0 - dx0*radius
		a0 = float32(math.Atan2(float64(dx0), float64(-dy0)))
		a1 = float32(math.Atan2(float64(-dx1), float64(dy1)))
		dir = Clockwise
	}
	p.Arc(cx, cy, radius, a0, a1, dir)

	p.LineTo(x2, y2)
}

// Arc adds an arc to the path.
// (x, y) is the center of the arc.
//
// Arc updates the current position to the end of the arc.
func (p *Path) Arc(x, y, radius, startAngle, endAngle float32, dir Direction) {
	// Adjust the angles.
	var da float64
	if dir == Clockwise {
		for startAngle > endAngle {
			endAngle += 2 * math.Pi
		}
		da = float64(endAngle - startAngle)
	} else {
		for startAngle < endAngle {
			startAngle += 2 * math.Pi
		}
		da = float64(startAngle - endAngle)
	}

	if da >= 2*math.Pi {
		da = 2 * math.Pi
		if dir == Clockwise {
			endAngle = startAngle + 2*math.Pi
		} else {
			startAngle = endAngle + 2*math.Pi
		}
	}

	// If the angle is big, splict this into multiple Arc calls.
	if da > math.Pi/2 {
		const delta = math.Pi / 3
		a := float64(startAngle)
		if dir == Clockwise {
			for {
				p.Arc(x, y, radius, float32(a), float32(math.Min(a+delta, float64(endAngle))), dir)
				if a+delta >= float64(endAngle) {
					break
				}
				a += delta
			}
		} else {
			for {
				p.Arc(x, y, radius, float32(a), float32(math.Max(a-delta, float64(endAngle))), dir)
				if a-delta <= float64(endAngle) {
					break
				}
				a -= delta
			}
		}
		return
	}

	sin0, cos0 := math.Sincos(float64(startAngle))
	x0 := x + radius*float32(cos0)
	y0 := y + radius*float32(sin0)
	sin1, cos1 := math.Sincos(float64(endAngle))
	x1 := x + radius*float32(cos1)
	y1 := y + radius*float32(sin1)

	p.LineTo(x0, y0)

	// Calculate the control points for an approximated Bézier curve.
	// See https://docs.microsoft.com/en-us/xamarin/xamarin-forms/user-interface/graphics/skiasharp/curves/beziers.
	l := radius * float32(math.Tan(da/4)*4/3)
	var cx0, cy0, cx1, cy1 float32
	if dir == Clockwise {
		cx0 = x0 + l*float32(-sin0)
		cy0 = y0 + l*float32(cos0)
		cx1 = x1 + l*float32(sin1)
		cy1 = y1 + l*float32(-cos1)
	} else {
		cx0 = x0 + l*float32(sin0)
		cy0 = y0 + l*float32(-cos0)
		cx1 = x1 + l*float32(-sin1)
		cy1 = y1 + l*float32(cos1)
	}
	p.CubicTo(cx0, cy0, cx1, cy1, x1, y1)
}

// AppendVerticesAndIndicesForFilling appends vertices and indices to fill this path and returns them.
// AppendVerticesAndIndicesForFilling works in a similar way to the built-in append function.
// If the arguments are nils, AppendVerticesAndIndicesForFilling returns new slices.
//
// The returned vertice's SrcX and SrcY are 0, and ColorR, ColorG, ColorB, and ColorA are 1.
//
// The returned values are intended to be passed to DrawTriangles or DrawTrianglesShader with EvenOdd fill mode
// in order to render a complex polygon like a concave polygon, a polygon with holes, or a self-intersecting polygon.
func (p *Path) AppendVerticesAndIndicesForFilling(vertices []ebiten.Vertex, indices []uint16) ([]ebiten.Vertex, []uint16) {
	// TODO: Add tests.

	base := uint16(len(vertices))
	for _, seg := range p.segs {
		if len(seg) < 3 {
			continue
		}
		for i, pt := range seg {
			vertices = append(vertices, ebiten.Vertex{
				DstX:   pt.x,
				DstY:   pt.y,
				SrcX:   0,
				SrcY:   0,
				ColorR: 1,
				ColorG: 1,
				ColorB: 1,
				ColorA: 1,
			})
			if i < 2 {
				continue
			}
			indices = append(indices, base, base+uint16(i-1), base+uint16(i))
		}
		base += uint16(len(seg))
	}
	return vertices, indices
}

// LineJoin represents the way in which how two segments are joined.
type LineJoin int

const (
	LineJoinMiter LineJoin = iota
	LineJoinBevel
	LineJoinRound
)

// StokeOptions is options to render a stroke.
type StrokeOptions struct {
	// Width is the stroke width in pixels.
	Width float32

	// LineJoin is the way in which how two segments are joined.
	// The default (zero) value is LineJoiMiter.
	LineJoin LineJoin
}

// AppendVerticesAndIndicesForStroke appends vertices and indices to render a stroke of this path and returns them.
// AppendVerticesAndIndicesForStroke works in a similar way to the built-in append function.
// If the arguments are nils, AppendVerticesAndIndicesForStroke returns new slices.
//
// The returned vertice's SrcX and SrcY are 0, and ColorR, ColorG, ColorB, and ColorA are 1.
//
// The returned values are intended to be passed to DrawTriangles or DrawTrianglesShader with FillAll fill mode, not EvenOdd fill mode.
func (p *Path) AppendVerticesAndIndicesForStroke(vertices []ebiten.Vertex, indices []uint16, op *StrokeOptions) ([]ebiten.Vertex, []uint16) {
	if op == nil {
		return vertices, indices
	}

	for _, seg := range p.segs {
		if len(seg) < 2 {
			continue
		}

		var rects [][4]point
		for i := 0; i < len(seg)-1; i++ {
			pt := seg[i]
			if seg[i+1] == pt {
				continue
			}

			nextPt := seg[i+1]
			dx := nextPt.x - pt.x
			dy := nextPt.y - pt.y
			dist := float32(math.Sqrt(float64(dx*dx + dy*dy)))
			extX := (dy) * op.Width / 2 / dist
			extY := (-dx) * op.Width / 2 / dist

			rects = append(rects, [4]point{
				{
					x: pt.x + extX,
					y: pt.y + extY,
				},
				{
					x: nextPt.x + extX,
					y: nextPt.y + extY,
				},
				{
					x: pt.x - extX,
					y: pt.y - extY,
				},
				{
					x: nextPt.x - extX,
					y: nextPt.y - extY,
				},
			})
		}

		for i, rect := range rects {
			idx := uint16(len(vertices))
			for _, pt := range rect {
				vertices = append(vertices, ebiten.Vertex{
					DstX:   pt.x,
					DstY:   pt.y,
					SrcX:   0,
					SrcY:   0,
					ColorR: 1,
					ColorG: 1,
					ColorB: 1,
					ColorA: 1,
				})
			}
			indices = append(indices, idx, idx+1, idx+2, idx+1, idx+2, idx+3)

			if i >= len(rects)-1 {
				continue
			}

			// Add line joints.
			nextRect := rects[i+1]

			// c is the center of the 'end' edge of the current rect (= the second point of the segment).
			c := point{
				x: (rect[1].x + rect[3].x) / 2,
				y: (rect[1].y + rect[3].y) / 2,
			}

			// Note that the Y direction and the angle direction are opposite from math's.
			a0 := float32(math.Atan2(float64(rect[1].y-c.y), float64(rect[1].x-c.x)))
			a1 := float32(math.Atan2(float64(nextRect[0].y-c.y), float64(nextRect[0].x-c.x)))
			da := a1 - a0
			for da < 0 {
				da += 2 * math.Pi
			}
			if da == 0 {
				continue
			}

			switch op.LineJoin {
			case LineJoinMiter:
				// TODO: Enable to configure this.
				const miterLimit = 10
				delta := math.Pi - da
				exceed := math.Abs(1/math.Sin(float64(delta/2))) > miterLimit
				var quad Path
				quad.MoveTo(c.x, c.y)
				if da < math.Pi {
					quad.LineTo(rect[1].x, rect[1].y)
					if !exceed {
						pt := crossingPointForTwoLines(rect[0], rect[1], nextRect[0], nextRect[1])
						quad.LineTo(pt.x, pt.y)
					}
					quad.LineTo(nextRect[0].x, nextRect[0].y)
				} else {
					quad.LineTo(rect[3].x, rect[3].y)
					if !exceed {
						pt := crossingPointForTwoLines(rect[2], rect[3], nextRect[2], nextRect[3])
						quad.LineTo(pt.x, pt.y)
					}
					quad.LineTo(nextRect[2].x, nextRect[2].y)
				}
				vertices, indices = quad.AppendVerticesAndIndicesForFilling(vertices, indices)

			case LineJoinBevel:
				var tri Path
				tri.MoveTo(c.x, c.y)
				if da < math.Pi {
					tri.LineTo(rect[1].x, rect[1].y)
					tri.LineTo(nextRect[0].x, nextRect[0].y)
				} else {
					tri.LineTo(rect[3].x, rect[3].y)
					tri.LineTo(nextRect[2].x, nextRect[2].y)
				}
				vertices, indices = tri.AppendVerticesAndIndicesForFilling(vertices, indices)

			case LineJoinRound:
				var arc Path
				arc.MoveTo(c.x, c.y)
				if da < math.Pi {
					arc.Arc(c.x, c.y, op.Width/2, a0, a1, Clockwise)
				} else {
					arc.Arc(c.x, c.y, op.Width/2, a0+math.Pi, a1+math.Pi, CounterClockwise)
				}
				vertices, indices = arc.AppendVerticesAndIndicesForFilling(vertices, indices)
			}
		}
	}
	return vertices, indices
}