all: [API] split operation stack into per-state stacks

The op.Save and Load methods exist to support the need for
transformation, clip, pointer area state to behave as stacks. For
example, layout needs to apply an offset to its children but not
subsequent operations.

Before this change, op.Save and Load were used to save and restore the
state:

    ops := new(op.Ops)
    // Save state.
    state := op.Save(ops)
    // Apply offset.
    op.Offset(...).Add(ops)
    // Draw with offset applied.
    draw(ops)
    // Restore state.
    state.Load()

A drawback with the op.Save mechanism is that there is no direct
connection between the state change and the saving and loading of state.
This causes confusion as to when a Save/Load is needed and who is
responsible for performing them, which leads to subtle bugs and over-use
of Save/Loads.

This change gets rid of the general state stack and replaces it with
per-state stacks. There is now a stack for transformation, clip, pointer
areas, and they can only be restored by the code pushing state to them.
The example above now becomes:

    ops := new(op.Ops)
    // Push offset to the transformation stack.
    stack := op.Offset(...).Push(ops)
    // Draw with offset applied.
    draw(ops)
    // Restore state.
    stack.Pop()

For convenience, transformation also be Add'ed if the stack operation is
not required.

Simple state such as the current material no longer has a way to be
restored; it is assumed the client of a PaintOp adds their desired
material operation before it.

API change: replace op.Save/Load with explicit Push/Pop scopes for
op.TransformOps, pointer.AreaOps, clip.Ops.

To ease porting, this change retains a version of op.Save/Load that
saves and restores the transformation and clip stacks. It also retains
an Add method for clip.Op.

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

op/clip/clip.go

@@ -16,12 +16,6 @@ import (
 	"gioui.org/op"
 )
 
-var pathSeed maphash.Seed
-
-func init() {
-	pathSeed = maphash.MakeSeed()
-}
-
 // Op represents a clip area. Op intersects the current clip area with
 // itself.
 type Op struct {
@@ -32,7 +26,35 @@ type Op struct {
 	dashes  DashSpec
 }
 
+// Stack represents an Op pushed on the clip stack.
+type Stack struct {
+	ops     *op.Ops
+	id      op.StackID
+	macroID int
+}
+
+var pathSeed maphash.Seed
+
+func init() {
+	pathSeed = maphash.MakeSeed()
+}
+
+// Push saves the current clip state on the stack and updates the current
+// state to the intersection of the current p.
+func (p Op) Push(o *op.Ops) Stack {
+	id, macroID := o.PushOp(op.ClipStack)
+	p.add(o, true)
+	return Stack{ops: o, id: id, macroID: macroID}
+}
+
+// Add is like Push except it doesn't save the current state on the stack.
+//
+// Deprecated: use Push instead.
 func (p Op) Add(o *op.Ops) {
+	p.add(o, false)
+}
+
+func (p Op) add(o *op.Ops, push bool) {
 	str := p.stroke
 	path := p.path
 	outline := p.outline
@@ -76,6 +98,15 @@ func (p Op) Add(o *op.Ops) {
 	if outline {
 		data[17] = byte(1)
 	}
+	if push {
+		data[18] = byte(1)
+	}
+}
+
+func (s Stack) Pop() {
+	s.ops.PopOp(op.ClipStack, s.id, s.macroID)
+	data := s.ops.Write(opconst.TypePopClipLen)
+	data[0] = byte(opconst.TypePopClip)
 }
 
 func (p Op) approximateStroke(o *op.Ops) PathSpec {

op/clip/clip_test.go

@@ -20,3 +20,15 @@ func TestOpenPathOutlinePanic(t *testing.T) {
 	p.Line(f32.Pt(10, 10))
 	Outline{Path: p.End()}.Op()
 }
+
+func TestTransformChecks(t *testing.T) {
+	defer func() {
+		if err := recover(); err == nil {
+			t.Error("cross-macro Pop didn't panic")
+		}
+	}()
+	var ops op.Ops
+	st := Op{}.Push(&ops)
+	op.Record(&ops)
+	st.Pop()
+}

op/clip/doc.go

@@ -4,13 +4,11 @@
 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.
+The current clip is initially the infinite set. Pushing and Op sets the clip
+to the intersection of the current clip and pushed clip area. Popping the
+area restores the clip to its state before pushing.
 
-General clipping areas are constructed with Path. Simpler special
-cases such as rectangular clip areas also exist as convenient
-constructors.
+General clipping areas are constructed with Path. Common cases such as
+rectangular clip areas also exist as convenient constructors.
 */
 package clip

op/clip/shapes.go

@@ -23,7 +23,14 @@ func (r Rect) Op() Op {
 	}
 }
 
-// Add the clip operation.
+// Push the clip operation on the clip stack.
+func (r Rect) Push(ops *op.Ops) Stack {
+	return r.Op().Push(ops)
+}
+
+// Add the rectangle clip to the clip state.
+//
+// Deprecated: use Push instead.
 func (r Rect) Add(ops *op.Ops) {
 	r.Op().Add(ops)
 }
@@ -66,7 +73,14 @@ func (rr RRect) Op(ops *op.Ops) Op {
 	return Outline{Path: rr.Path(ops)}.Op()
 }
 
-// Add the rectangle clip.
+// Push the rectangle clip on the clip stack.
+func (rr RRect) Push(ops *op.Ops) Stack {
+	return rr.Op(ops).Push(ops)
+}
+
+// Add the rectangle clip to the clip state.
+//
+// Deprecated: use Push instead.
 func (rr RRect) Add(ops *op.Ops) {
 	rr.Op(ops).Add(ops)
 }
@@ -119,7 +133,14 @@ func (c Circle) Op(ops *op.Ops) Op {
 	return Outline{Path: c.Path(ops)}.Op()
 }
 
-// Add the circle clip.
+// Push the circle clip on the clip stack.
+func (c Circle) Push(ops *op.Ops) Stack {
+	return c.Op(ops).Push(ops)
+}
+
+// Add the circle clip to the clip state.
+//
+// Deprecated: use Push instead.
 func (c Circle) Add(ops *op.Ops) {
 	c.Op(ops).Add(ops)
 }