op/clip: split clip operations into its own package

Signed-off-by: Elias Naur <mail@eliasnaur.com>

op/clip/clip.go

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
-package paint
+package clip
 
 import (
 	"encoding/binary"
+	"image"
 	"math"
 
 	"gioui.org/f32"
@@ -12,10 +13,13 @@ import (
 	"gioui.org/op"
 )
 
-// Path constructs a ClipOp clip path described by lines and
-// Bézier curves. Path generates no garbage and can be used for
-// dynamic paths; path data is stored directly in the Ops list
-// supplied to Begin.
+// Path constructs a Op clip path described by lines and
+// Bézier curves, where drawing outside the Path is discarded.
+// The inside-ness of a pixel is determines by the even-odd rule,
+// similar to the SVG rule of the same name.
+//
+// Path generates no garbage and can be used for dynamic paths; path
+// data is stored directly in the Ops list supplied to Begin.
 type Path struct {
 	ops       *op.Ops
 	contour   int
@@ -25,17 +29,17 @@ type Path struct {
 	macro     op.MacroOp
 }
 
-// ClipOp sets the current clip to the intersection of
+// Op sets the current clip to the intersection of
 // the existing clip with this clip.
 //
 // If you need to reset the clip to its previous values after
-// applying a ClipOp, use op.StackOp.
-type ClipOp struct {
+// applying a Op, use op.StackOp.
+type Op struct {
 	macro  op.MacroOp
 	bounds f32.Rectangle
 }
 
-func (p ClipOp) Add(o *op.Ops) {
+func (p Op) Add(o *op.Ops) {
 	p.macro.Add(o)
 	data := o.Write(opconst.TypeClipLen)
 	data[0] = byte(opconst.TypeClip)
@@ -46,7 +50,7 @@ func (p ClipOp) Add(o *op.Ops) {
 	bo.PutUint32(data[13:], math.Float32bits(p.bounds.Max.Y))
 }
 
-// Begin the path, storing the path data and final ClipOp into ops.
+// Begin the path, storing the path data and final Op into ops.
 func (p *Path) Begin(ops *op.Ops) {
 	p.ops = ops
 	p.macro.Record(ops)
@@ -270,12 +274,24 @@ func (p *Path) simpleQuadTo(ctrl, to f32.Point) {
 	p.pen = to
 }
 
-// End the path and return the resulting ClipOp.
-func (p *Path) End() ClipOp {
+// End the path and return a clip operation that represents it.
+func (p *Path) End() Op {
 	p.end()
 	p.macro.Stop()
-	return ClipOp{
+	return Op{
 		macro:  p.macro,
 		bounds: p.bounds,
 	}
 }
+
+// Rect returns the clip area of a pixel aligned rectangular area.
+func Rect(r image.Rectangle) Op {
+	return Op{bounds: toRectF(r)}
+}
+
+func toRectF(r image.Rectangle) f32.Rectangle {
+	return f32.Rectangle{
+		Min: f32.Point{X: float32(r.Min.X), Y: float32(r.Min.Y)},
+		Max: f32.Point{X: float32(r.Max.X), Y: float32(r.Max.Y)},
+	}
+}

op/clip/doc.go

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package clip provides operations for clipping paint operations.
+Drawing outside the current clip area is ignored.
+
+The current clip is initially the infinite set. An Op sets the clip
+to the intersection of the current clip and the clip area it
+represents. If you need to reset the current clip to its value
+before applying an Op, use op.StackOp.
+
+General clipping areas are constructed with Path. Simpler special
+cases such as rectangular clip areas also exist as convenient
+constructors.
+*/
+package clip

op/paint/doc.go

@@ -1,15 +1,12 @@
 // SPDX-License-Identifier: Unlicense OR MIT
 
 /*
-Package paint provides operations for 2D graphics.
+Package paint provides drawing operations for 2D graphics.
 
 The PaintOp operation draws the current material into a rectangular
 area, taking the current clip path and transformation into account.
 
 The material is set by either a ColorOp for a constant color, or
 ImageOp for an image.
-
-The ClipOp operation sets the clip path. Drawing outside the clip
-path is ignored. A path is a closed shape of lines or curves.
 */
 package paint

op/paint/paint.go

@@ -102,16 +102,3 @@ func (d PaintOp) Add(o *op.Ops) {
 	bo.PutUint32(data[9:], math.Float32bits(d.Rect.Max.X))
 	bo.PutUint32(data[13:], math.Float32bits(d.Rect.Max.Y))
 }
-
-// RectClip returns a ClipOp corresponding to a pixel aligned
-// rectangular area.
-func RectClip(r image.Rectangle) ClipOp {
-	return ClipOp{bounds: toRectF(r)}
-}
-
-func toRectF(r image.Rectangle) f32.Rectangle {
-	return f32.Rectangle{
-		Min: f32.Point{X: float32(r.Min.X), Y: float32(r.Min.Y)},
-		Max: f32.Point{X: float32(r.Max.X), Y: float32(r.Max.Y)},
-	}
-}