From 81f474f5d73672a1855e6d7efab77055aa6718e3 Mon Sep 17 00:00:00 2001
From: Elias Naur <mail@eliasnaur.com>
Date: Thu, 14 May 2020 13:15:05 +0200
Subject: [PATCH] op/paint,io/system: document ImageOp lifetime

Signed-off-by: Elias Naur <mail@eliasnaur.com>
---
 io/system/system.go | 19 +++++++++++++++++++
 op/paint/paint.go   | 14 +++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/io/system/system.go b/io/system/system.go
index 52cf45fe..dd8faf40 100644
--- a/io/system/system.go
+++ b/io/system/system.go
@@ -23,6 +23,25 @@ type FrameEvent struct {
 	Insets Insets
 	// Frame is the callback to supply the list of
 	// operations to complete the FrameEvent.
+	//
+	// Note that the operation list and the operations themselves
+	// may not be mutated until another FrameEvent is received from
+	// the same event source.
+	// That means that calls to frame.Reset and changes to referenced
+	// data such as ImageOp backing images should happen between
+	// receiving a FrameEvent and calling Frame.
+	//
+	// Example:
+	//
+	//	var w *app.Window
+	//	var frame *op.Ops
+	// 	for e := range w.Events() {
+	//  	if e, ok := e.(system.FrameEvent); ok {
+	//			// Call frame.Reset and manipulate images for ImageOps
+	//			// here.
+	//			e.Frame(frame)
+	//  	}
+	//  }
 	Frame func(frame *op.Ops)
 	// Queue supplies the events for event handlers.
 	Queue event.Queue
diff --git a/op/paint/paint.go b/op/paint/paint.go
index 7ec1d2d1..3daf5371 100644
--- a/op/paint/paint.go
+++ b/op/paint/paint.go
@@ -16,7 +16,9 @@ import (
 
 // ImageOp sets the material to an image.
 type ImageOp struct {
-	Rect    image.Rectangle
+	// Rect is the section if the backing image to use.
+	Rect image.Rectangle
+
 	uniform bool
 	color   color.RGBA
 	src     *image.RGBA
@@ -34,9 +36,19 @@ type ColorOp struct {
 // PaintOp draws the current material, respecting the
 // clip path and transformation.
 type PaintOp struct {
+	// The destination rectangle to paint. If necessary, the material is resized to
+	// cover it.
 	Rect f32.Rectangle
 }
 
+// NewImageOp creates an ImageOp backed by src. See
+// gioui.org/io/system.FrameEvent for a description of when data
+// referenced by operations is safe to re-use.
+//
+// NewImageOp assumes the backing image is immutable, and may cache a
+// copy of its contents in a GPU-friendly way. Create new ImageOps to
+// ensure that changes to an image is reflected in the display of
+// it.
 func NewImageOp(src image.Image) ImageOp {
 	switch src := src.(type) {
 	case *image.Uniform: