op/paint,io/system: document ImageOp lifetime

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

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

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: