From 5a4a82ab501f96744d615190034f1b842d634db2 Mon Sep 17 00:00:00 2001
From: Hajime Hoshi <hajimehoshi@gmail.com>
Date: Tue, 30 May 2017 03:31:29 +0900
Subject: [PATCH] restorable: Add TODO comments (#357)

---
 graphicscontext.go            | 1 +
 image.go                      | 2 ++
 internal/restorable/image.go  | 6 ++++--
 internal/restorable/images.go | 2 ++
 4 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/graphicscontext.go b/graphicscontext.go
index d02bb7060..ee3c8153c 100644
--- a/graphicscontext.go
+++ b/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
 	}
diff --git a/image.go b/image.go
index fa6f43f6f..ec787ce6f 100644
--- a/image.go
+++ b/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.
diff --git a/internal/restorable/image.go b/internal/restorable/image.go
index b7eab1b3d..36de52a13 100644
--- a/internal/restorable/image.go
+++ b/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.
diff --git a/internal/restorable/images.go b/internal/restorable/images.go
index 67f8a0640..4d742a815 100644
--- a/internal/restorable/images.go
+++ b/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()