restorable: Add TODO comments (#357)

graphicscontext.go

@@ -144,6 +144,7 @@ func (c *graphicsContext) UpdateAndDraw(context *opengl.Context, updateCount int
 		return err
 	}
 	// TODO: Is it OK to restore images here? The images can be in 'stale' state after c.f().
+	// (#357)
 	if err := restorable.ResolveStalePixels(context); err != nil {
 		return err
 	}

image.go

@@ -257,6 +257,8 @@ func NewImage(width, height int, filter Filter) (*Image, error) {
 // On the other hand, pixels in volatile images are not saved.
 // Saving pixels is an expensive operation, and it is desirable to avoid it if possible.
 //
+// Note that volatile images are internal only and will never be source of drawing.
+//
 // If width or height is less than 1 or more than MaxImageSize, newVolatileImage panics.
 //
 // Error returned by newVolatileImage is always nil as of 1.5.0-alpha.

internal/restorable/image.go

@@ -43,9 +43,11 @@ type Image struct {
 	basePixels       []uint8
 	baseColor        color.RGBA
 	drawImageHistory []*drawImageHistoryItem
-	stale            bool
 
-	// volatile indicates whether the image is cleared at every frame.
+	// stale indicates whether the image needs to be synced with GPU as soon as possible.
+	stale bool
+
+	// volatile indicates whether the image is cleared whenever a frame starts.
 	volatile bool
 
 	// screen indicates whether the image is used as an actual screen.

internal/restorable/images.go

@@ -79,6 +79,8 @@ func (i *images) resetPixelsIfDependingOn(target *Image) {
 	}
 	i.lastChecked = target
 	for img := range i.images {
+		// TODO: This seems not enough: What if img becomes stale but what about
+		// other images depend on img? (#357)
 		img.makeStaleIfDependingOn(target)
 	}
 	i.m.Unlock()