restoreable: Add ClearState to clear the state explicitly

Fixes #566

image.go

@@ -126,7 +126,7 @@ func (i *Image) fill(r, g, b, a uint8) {
 	}
 	op.CompositeMode = CompositeModeCopy
 	op.Filter = FilterNearest
-	_ = i.DrawImage(emptyImage, op)
+	i.drawImage(emptyImage, op, r == 0 && g == 0 && b == 0 && a == 0)
 }
 
 func (i *Image) disposeMipmaps() {
@@ -170,12 +170,17 @@ func (i *Image) disposeMipmaps() {
 //
 // DrawImage always returns nil as of 1.5.0-alpha.
 func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error {
+	i.drawImage(img, options, false)
+	return nil
+}
+
+func (i *Image) drawImage(img *Image, options *DrawImageOptions, clear bool) {
 	i.copyCheck()
 	if img.isDisposed() {
 		panic("ebiten: the given image to DrawImage must not be disposed")
 	}
 	if i.isDisposed() {
-		return nil
+		return
 	}
 
 	// Calculate vertices before locking because the user can do anything in
@@ -209,7 +214,7 @@ func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error {
 			op.GeoM.Concat(options.GeoM)
 			i.DrawImage(img, op)
 		}
-		return nil
+		return
 	}
 
 	w, h := img.Size()
@@ -256,10 +261,10 @@ func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error {
 	if filter == graphics.FilterLinear {
 		det := geom.det()
 		if det == 0 {
-			return nil
+			return
 		}
 		if math.IsNaN(float64(det)) {
-			return nil
+			return
 		}
 		level = graphicsutil.MipmapLevel(det)
 		if level < 0 {
@@ -311,8 +316,10 @@ func (i *Image) DrawImage(img *Image, options *DrawImageOptions) error {
 		is := graphicsutil.QuadIndices()
 		i.shareableImages[0].DrawImage(src, vs, is, options.ColorM.impl, mode, filter)
 	}
+	if clear {
+		i.shareableImages[0].ClearRestorableState()
+	}
 	i.disposeMipmaps()
-	return nil
 }
 
 // Bounds returns the bounds of the image.

internal/restorable/image.go

@@ -216,6 +216,17 @@ func (i *Image) DrawImage(img *Image, vertices []float32, indices []uint16, colo
 	i.image.DrawImage(img.image, vertices, indices, colorm, mode, filter)
 }
 
+// ClearState clears the internal state. This is useful when it is known that the image is cleared and not stale.
+//
+// TODO: This is a tricky function since it is hard to determine when to call ClearState.
+// Refactor this.
+func (i *Image) ClearState() {
+	// TODO: Ensure i.image is already cleared?
+	i.basePixels = nil
+	i.drawImageHistory = nil
+	i.stale = false
+}
+
 // appendDrawImageHistory appends a draw-image history item to the image.
 func (i *Image) appendDrawImageHistory(image *Image, vertices []float32, indices []uint16, colorm *affine.ColorM, mode opengl.CompositeMode, filter graphics.Filter) {
 	if i.stale || i.volatile || i.screen {

internal/shareable/shareable.go

@@ -232,6 +232,22 @@ func (i *Image) DrawImage(img *Image, vertices []float32, indices []uint16, colo
 	// }
 }
 
+func (i *Image) ClearRestorableState() {
+	backendsM.Lock()
+	defer backendsM.Unlock()
+
+	if i.disposed {
+		panic("shareable: the image must not be disposed")
+	}
+	if i.backend == nil {
+		panic("shareable: the image must have backend")
+	}
+	if i.isShared() {
+		panic("shareable: the image must not be shared")
+	}
+	i.backend.restorable.ClearState()
+}
+
 func (i *Image) ReplacePixels(p []byte) {
 	backendsM.Lock()
 	defer backendsM.Unlock()