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>

io/pointer/doc.go

@@ -41,25 +41,23 @@ operations is the intersection of the areas.
 
 Matching events
 
-StackOp operations and input handlers form an implicit tree.
-Each stack operation is a node, and each input handler is associated
-with the most recent node.
+Areas form an implicit tree, with input handlers as leaves. The children of
+an area is every area and handler added between its Push and corresponding Pop.
 
 For example:
 
 	ops := new(op.Ops)
-	var stack op.StackOp
 	var h1, h2 *Handler
 
-	state := op.Save(ops)
+	area := pointer.Rect(...).Push(ops)
 	pointer.InputOp{Tag: h1}.Add(Ops)
-	state.Load()
+	area.Pop()
 
-	state = op.Save(ops)
+	area := pointer.Rect(...).Push(ops)
 	pointer.InputOp{Tag: h2}.Add(ops)
-	state.Load()
+	area.Pop()
 
-implies a tree of two inner nodes, each with one pointer handler.
+implies a tree of two inner nodes, each with one pointer handler attached.
 
 When determining which handlers match an Event, only handlers whose
 areas contain the event position are considered. The matching

io/pointer/pointer.go

@@ -54,6 +54,13 @@ type AreaOp struct {
 	rect image.Rectangle
 }
 
+// AreaStack represents an AreaOp on the stack of areas.
+type AreaStack struct {
+	ops     *op.Ops
+	id      op.StackID
+	macroID int
+}
+
 // CursorNameOp sets the cursor for the current area.
 type CursorNameOp struct {
 	Name CursorName
@@ -185,18 +192,32 @@ func Ellipse(size image.Rectangle) AreaOp {
 	}
 }
 
-func (op AreaOp) Add(o *op.Ops) {
-	data := o.Write(opconst.TypeAreaLen)
+// Push the current area to the stack and intersects the current area with the
+// area represented by o.
+func (o AreaOp) Push(ops *op.Ops) AreaStack {
+	id, macroID := ops.PushOp(op.AreaStack)
+	o.add(ops, true)
+	return AreaStack{ops: ops, id: id, macroID: macroID}
+}
+
+func (o AreaOp) add(ops *op.Ops, push bool) {
+	data := ops.Write(opconst.TypeAreaLen)
 	data[0] = byte(opconst.TypeArea)
-	data[1] = byte(op.kind)
-	if op.PassThrough {
+	data[1] = byte(o.kind)
+	if o.PassThrough {
 		data[2] = 1
 	}
 	bo := binary.LittleEndian
-	bo.PutUint32(data[3:], uint32(op.rect.Min.X))
-	bo.PutUint32(data[7:], uint32(op.rect.Min.Y))
-	bo.PutUint32(data[11:], uint32(op.rect.Max.X))
-	bo.PutUint32(data[15:], uint32(op.rect.Max.Y))
+	bo.PutUint32(data[3:], uint32(o.rect.Min.X))
+	bo.PutUint32(data[7:], uint32(o.rect.Min.Y))
+	bo.PutUint32(data[11:], uint32(o.rect.Max.X))
+	bo.PutUint32(data[15:], uint32(o.rect.Max.Y))
+}
+
+func (o AreaStack) Pop() {
+	o.ops.PopOp(op.AreaStack, o.id, o.macroID)
+	data := o.ops.Write(opconst.TypePopAreaLen)
+	data[0] = byte(opconst.TypePopArea)
 }
 
 func (op CursorNameOp) Add(o *op.Ops) {

io/pointer/pointer_test.go

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Unlicense OR MIT
+
+package pointer
+
+import (
+	"testing"
+
+	"gioui.org/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
+	area := AreaOp{}.Push(&ops)
+	op.Record(&ops)
+	area.Pop()
+}

io/router/key_test.go

@@ -60,22 +60,14 @@ func TestKeyStacked(t *testing.T) {
 	ops := new(op.Ops)
 	r := new(Router)
 
-	s := op.Save(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
 	key.FocusOp{Tag: nil}.Add(ops)
-	s.Load()
-	s = op.Save(ops)
 	key.SoftKeyboardOp{Show: false}.Add(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
 	key.FocusOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[2]}.Add(ops)
 	key.SoftKeyboardOp{Show: true}.Add(ops)
-	s.Load()
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[3]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -107,16 +99,12 @@ func TestKeyRemoveFocus(t *testing.T) {
 	r := new(Router)
 
 	// New InputOp with Focus and Keyboard:
-	s := op.Save(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
 	key.FocusOp{Tag: &handlers[0]}.Add(ops)
 	key.SoftKeyboardOp{Show: true}.Add(ops)
-	s.Load()
 
 	// New InputOp without any focus:
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -132,19 +120,13 @@ func TestKeyRemoveFocus(t *testing.T) {
 	ops.Reset()
 
 	// Will get the focus removed:
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
-	s.Load()
 
 	// Unchanged:
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	// Remove focus by focusing on a tag that don't exist.
-	s = op.Save(ops)
 	key.FocusOp{Tag: new(int)}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -154,13 +136,9 @@ func TestKeyRemoveFocus(t *testing.T) {
 
 	ops.Reset()
 
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
-	s.Load()
 
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -173,17 +151,13 @@ func TestKeyRemoveFocus(t *testing.T) {
 
 	// Set focus to InputOp which already
 	// exists in the previous frame:
-	s = op.Save(ops)
 	key.FocusOp{Tag: &handlers[0]}.Add(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
 	key.SoftKeyboardOp{Show: true}.Add(ops)
-	s.Load()
 
 	// Remove focus.
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
 	key.FocusOp{Tag: nil}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -198,16 +172,12 @@ func TestKeyFocusedInvisible(t *testing.T) {
 	r := new(Router)
 
 	// Set new InputOp with focus:
-	s := op.Save(ops)
 	key.FocusOp{Tag: &handlers[0]}.Add(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
 	key.SoftKeyboardOp{Show: true}.Add(ops)
-	s.Load()
 
 	// Set new InputOp without focus:
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -223,9 +193,7 @@ func TestKeyFocusedInvisible(t *testing.T) {
 	//
 
 	// Unchanged:
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 
@@ -238,14 +206,10 @@ func TestKeyFocusedInvisible(t *testing.T) {
 
 	// Respawn the first element:
 	// It must receive one `Event{Focus: false}`.
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[0]}.Add(ops)
-	s.Load()
 
 	// Unchanged
-	s = op.Save(ops)
 	key.InputOp{Tag: &handlers[1]}.Add(ops)
-	s.Load()
 
 	r.Frame(ops)
 

io/router/pointer.go

@@ -23,8 +23,10 @@ type pointerQueue struct {
 	pointers []pointerInfo
 	reader   ops.Reader
 
+	nodeStack  []int
+	transStack []f32.Affine2D
 	// states holds the storage for save/restore ops.
-	states  []collectState
+	states  []f32.Affine2D
 	scratch []event.Tag
 }
 
@@ -81,6 +83,7 @@ type areaKind uint8
 type collectState struct {
 	t    f32.Affine2D
 	node int
+	pass bool
 }
 
 const (
@@ -88,32 +91,30 @@ const (
 	areaEllipse
 )
 
-func (q *pointerQueue) save(id int, state collectState) {
+func (q *pointerQueue) save(id int, state f32.Affine2D) {
 	if extra := id - len(q.states) + 1; extra > 0 {
-		q.states = append(q.states, make([]collectState, extra)...)
+		q.states = append(q.states, make([]f32.Affine2D, extra)...)
 	}
 	q.states[id] = state
 }
 
 func (q *pointerQueue) collectHandlers(r *ops.Reader, events *handlerEvents) {
-	state := collectState{
-		node: -1,
+	var state collectState
+	reset := func() {
+		state = collectState{
+			node: -1,
+		}
 	}
-	q.save(opconst.InitialStateID, state)
+	reset()
 	for encOp, ok := r.Decode(); ok; encOp, ok = r.Decode() {
 		switch opconst.OpType(encOp.Data[0]) {
 		case opconst.TypeSave:
 			id := ops.DecodeSave(encOp.Data)
-			q.save(id, state)
+			q.save(id, state.t)
 		case opconst.TypeLoad:
-			id, mask := ops.DecodeLoad(encOp.Data)
-			s := q.states[id]
-			if mask&opconst.TransformState != 0 {
-				state.t = s.t
-			}
-			if mask&^opconst.TransformState != 0 {
-				state = s
-			}
+			reset()
+			id := ops.DecodeLoad(encOp.Data)
+			state.t = q.states[id]
 		case opconst.TypeArea:
 			var op areaOp
 			op.Decode(encOp.Data)
@@ -123,14 +124,26 @@ func (q *pointerQueue) collectHandlers(r *ops.Reader, events *handlerEvents) {
 				area = n.area
 			}
 			q.areas = append(q.areas, areaNode{trans: state.t, next: area, area: op, pass: op.pass})
+			q.nodeStack = append(q.nodeStack, state.node)
 			q.hitTree = append(q.hitTree, hitNode{
 				next: state.node,
 				area: len(q.areas) - 1,
 			})
 			state.node = len(q.hitTree) - 1
+		case opconst.TypePopArea:
+			n := len(q.nodeStack)
+			state.node = q.nodeStack[n-1]
+			q.nodeStack = q.nodeStack[:n-1]
 		case opconst.TypeTransform:
-			dop := ops.DecodeTransform(encOp.Data)
+			dop, push := ops.DecodeTransform(encOp.Data)
+			if push {
+				q.transStack = append(q.transStack, state.t)
+			}
 			state.t = state.t.Mul(dop)
+		case opconst.TypePopTransform:
+			n := len(q.transStack)
+			state.t = q.transStack[n-1]
+			q.transStack = q.transStack[:n-1]
 		case opconst.TypePointerInput:
 			op := pointer.InputOp{
 				Tag:   encOp.Refs[0].(event.Tag),
@@ -242,6 +255,8 @@ func (q *pointerQueue) Frame(root *op.Ops, events *handlerEvents) {
 	}
 	q.hitTree = q.hitTree[:0]
 	q.areas = q.areas[:0]
+	q.nodeStack = q.nodeStack[:0]
+	q.transStack = q.transStack[:0]
 	q.cursors = q.cursors[:0]
 	q.reader.Reset(root)
 	q.collectHandlers(&q.reader, events)

io/router/pointer_test.go

@@ -122,11 +122,13 @@ func TestPointerMove(t *testing.T) {
 	types := pointer.Move | pointer.Enter | pointer.Leave
 
 	// Handler 1 area: (0, 0) - (100, 100)
-	pointer.Rect(image.Rect(0, 0, 100, 100)).Add(&ops)
+	r1 := pointer.Rect(image.Rect(0, 0, 100, 100)).Push(&ops)
 	pointer.InputOp{Tag: handler1, Types: types}.Add(&ops)
 	// Handler 2 area: (50, 50) - (100, 100) (areas intersect).
-	pointer.Rect(image.Rect(50, 50, 200, 200)).Add(&ops)
+	r2 := pointer.Rect(image.Rect(50, 50, 200, 200)).Push(&ops)
 	pointer.InputOp{Tag: handler2, Types: types}.Add(&ops)
+	r2.Pop()
+	r1.Pop()
 
 	var r Router
 	r.Frame(&ops)
@@ -157,11 +159,12 @@ func TestPointerMove(t *testing.T) {
 func TestPointerTypes(t *testing.T) {
 	handler := new(int)
 	var ops op.Ops
-	pointer.Rect(image.Rect(0, 0, 100, 100)).Add(&ops)
+	r1 := pointer.Rect(image.Rect(0, 0, 100, 100)).Push(&ops)
 	pointer.InputOp{
 		Tag:   handler,
 		Types: pointer.Press | pointer.Release,
 	}.Add(&ops)
+	r1.Pop()
 
 	var r Router
 	r.Frame(&ops)
@@ -188,28 +191,29 @@ func TestPointerPriority(t *testing.T) {
 	handler3 := new(int)
 	var ops op.Ops
 
-	st := op.Save(&ops)
-	pointer.Rect(image.Rect(0, 0, 100, 100)).Add(&ops)
+	r1 := pointer.Rect(image.Rect(0, 0, 100, 100)).Push(&ops)
 	pointer.InputOp{
 		Tag:          handler1,
 		Types:        pointer.Scroll,
 		ScrollBounds: image.Rectangle{Max: image.Point{X: 100}},
 	}.Add(&ops)
 
-	pointer.Rect(image.Rect(0, 0, 100, 50)).Add(&ops)
+	r2 := pointer.Rect(image.Rect(0, 0, 100, 50)).Push(&ops)
 	pointer.InputOp{
 		Tag:          handler2,
 		Types:        pointer.Scroll,
 		ScrollBounds: image.Rectangle{Max: image.Point{X: 20}},
 	}.Add(&ops)
-	st.Load()
+	r2.Pop()
+	r1.Pop()
 
-	pointer.Rect(image.Rect(0, 100, 100, 200)).Add(&ops)
+	r3 := pointer.Rect(image.Rect(0, 100, 100, 200)).Push(&ops)
 	pointer.InputOp{
 		Tag:          handler3,
 		Types:        pointer.Scroll,
 		ScrollBounds: image.Rectangle{Min: image.Point{X: -20, Y: -40}},
 	}.Add(&ops)
+	r3.Pop()
 
 	var r Router
 	r.Frame(&ops)
@@ -357,12 +361,11 @@ func TestMultipleAreas(t *testing.T) {
 	var ops op.Ops
 
 	addPointerHandler(&ops, handler, image.Rect(0, 0, 100, 100))
-	st := op.Save(&ops)
-	pointer.Rect(image.Rect(50, 50, 200, 200)).Add(&ops)
+	r1 := pointer.Rect(image.Rect(50, 50, 200, 200)).Push(&ops)
 	// Second area has no Types set, yet should receive events because
 	// Types for the same handles are or-ed together.
 	pointer.InputOp{Tag: handler}.Add(&ops)
-	st.Load()
+	r1.Pop()
 
 	var r Router
 	r.Frame(&ops)
@@ -392,12 +395,14 @@ func TestPointerEnterLeaveNested(t *testing.T) {
 	types := pointer.Press | pointer.Move | pointer.Release | pointer.Enter | pointer.Leave
 
 	// Handler 1 area: (0, 0) - (100, 100)
-	pointer.Rect(image.Rect(0, 0, 100, 100)).Add(&ops)
+	r1 := pointer.Rect(image.Rect(0, 0, 100, 100)).Push(&ops)
 	pointer.InputOp{Tag: handler1, Types: types}.Add(&ops)
 
 	// Handler 2 area: (25, 25) - (75, 75) (nested within first).
-	pointer.Rect(image.Rect(25, 25, 75, 75)).Add(&ops)
+	r2 := pointer.Rect(image.Rect(25, 25, 75, 75)).Push(&ops)
 	pointer.InputOp{Tag: handler2, Types: types}.Add(&ops)
+	r2.Pop()
+	r1.Pop()
 
 	var r Router
 	r.Frame(&ops)
@@ -538,7 +543,7 @@ func TestCursorNameOp(t *testing.T) {
 	var widget2 func()
 	widget := func() {
 		// This is the area where the cursor is changed to CursorPointer.
-		pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Add(ops)
+		defer pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Push(ops).Pop()
 		// The cursor is checked and changed upon cursor movement.
 		pointer.InputOp{Tag: &h}.Add(ops)
 		pointer.CursorNameOp{Name: pointer.CursorPointer}.Add(ops)
@@ -652,8 +657,7 @@ func TestCursorNameOp(t *testing.T) {
 // addPointerHandler adds a pointer.InputOp for the tag in a
 // rectangular area.
 func addPointerHandler(ops *op.Ops, tag event.Tag, area image.Rectangle) {
-	defer op.Save(ops).Load()
-	pointer.Rect(area).Add(ops)
+	defer pointer.Rect(area).Push(ops).Pop()
 	pointer.InputOp{
 		Tag:   tag,
 		Types: pointer.Press | pointer.Release | pointer.Move | pointer.Drag | pointer.Enter | pointer.Leave,
@@ -729,7 +733,7 @@ func BenchmarkRouterAdd(b *testing.B) {
 						X: 100,
 						Y: 100,
 					},
-				}).Add(&ops)
+				}).Push(&ops)
 				pointer.InputOp{
 					Tag:   handlers[i],
 					Types: pointer.Move,
@@ -755,7 +759,7 @@ var benchAreaOp areaOp
 
 func BenchmarkAreaOp_Decode(b *testing.B) {
 	ops := new(op.Ops)
-	pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Add(ops)
+	pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Push(ops).Pop()
 	for i := 0; i < b.N; i++ {
 		benchAreaOp.Decode(ops.Data())
 	}
@@ -763,7 +767,7 @@ func BenchmarkAreaOp_Decode(b *testing.B) {
 
 func BenchmarkAreaOp_Hit(b *testing.B) {
 	ops := new(op.Ops)
-	pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Add(ops)
+	pointer.Rect(image.Rectangle{Max: image.Pt(100, 100)}).Push(ops).Pop()
 	benchAreaOp.Decode(ops.Data())
 	for i := 0; i < b.N; i++ {
 		benchAreaOp.Hit(f32.Pt(50, 50))