b25af47c45adcaef27ae241623f40208c53a1866 — Elias Naur 3 months ago 40091c5
ui/paint: expand documentation and add package description

Signed-off-by: Elias Naur <mail@eliasnaur.com>
3 files changed, 35 insertions(+), 5 deletions(-)

A ui/paint/doc.go
M ui/paint/paint.go
M ui/paint/path.go
A ui/paint/doc.go => ui/paint/doc.go +15 -0
@@ 0,0 1,15 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+/*
+Package paint provides 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

M ui/paint/paint.go => ui/paint/paint.go +10 -3
@@ 13,15 13,22 @@
 	"gioui.org/ui/internal/opconst"
 )
 
+// ImageOp sets the material to a section of an
+// image.
 type ImageOp struct {
-	Src  image.Image
+	// Src is the image.
+	Src image.Image
+	// Rect defines the section of Src to use.
 	Rect image.Rectangle
 }
 
+// ColorOp sets the material to a constant color.
 type ColorOp struct {
 	Color color.RGBA
 }
 
+// PaintOp draws the current material, respecting the
+// clip path and transformation.
 type PaintOp struct {
 	Rect f32.Rectangle
 }


@@ 58,8 65,8 @@
 	o.Write(data)
 }
 
-// RectClip returns a ClipOp op corresponding to
-// a pixel aligned rectangular area.
+// RectClip returns a ClipOp corresponding to a pixel aligned
+// rectangular area.
 func RectClip(r image.Rectangle) ClipOp {
 	return ClipOp{bounds: toRectF(r)}
 }

M ui/paint/path.go => ui/paint/path.go +10 -2
@@ 13,6 13,11 @@
 	"gioui.org/ui/internal/path"
 )
 
+// PathBuilder builds and adds a general ClipOp clip path
+// from lines and curves.
+// PathBuilder generates no garbage and can be used for
+// dynamic paths; path data is stored directly in the Ops
+// list supplied to Init.
 type PathBuilder struct {
 	ops       *ui.Ops
 	firstVert int


@@ 23,8 28,7 @@
 	hasBounds bool
 }
 
-// ClipOp structure must match opClip in package ui/internal/gpu.
-
+// ClipOp sets the current clip path.
 type ClipOp struct {
 	bounds f32.Rectangle
 }


@@ 40,6 44,8 @@
 	o.Write(data)
 }
 
+// Init the builder and specify the operations list for
+// storing the path data and final ClipOp.
 func (p *PathBuilder) Init(ops *ui.Ops) {
 	p.ops = ops
 }


@@ 276,6 282,8 @@
 	p.pen = to
 }
 
+// End the path and add the resulting ClipOp to
+// the operation list passed to Init.
 func (p *PathBuilder) End() {
 	p.end()
 	ClipOp{