Revert "internal/restorable: remove unused functions and variables"

This reverts commit 8169253.

Updates #3083

internal/restorable/doc.go

@@ -12,11 +12,57 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package restorable used to offer an Image struct that stores image commands
+// Package restorable offers an Image struct that stores image commands
 // and restores its pixel data from the commands when context lost happens.
 //
-// However, now Ebitengine doesn't handle context losts, and this package is
-// just a thin wrapper.
+// When a function like DrawImage or Fill is called, an Image tries to record
+// the information for restoring.
 //
-// TODO: Integrate this package into internal/atlas and internal/graphicscommand (#805).
+// * Context lost
+//
+// Contest lost is a process that information on GPU memory are removed by OS
+// to make more room on GPU memory.
+// This can happen e.g. when GPU memory usage is high, or just switching applications
+// might cause context lost on mobiles.
+// As Ebitengine's image data is on GPU memory, the game can't continue when context lost happens
+// without restoring image information.
+// The package restorable is the package to record information for such restoring.
+//
+// * DrawImage
+//
+// DrawImage function tries to record an item of 'draw image history' in the target image.
+// If a target image is stale or volatile, no item is created.
+// If an item of the history is created,
+// it can be said that the target image depends on the source image.
+// In other words, If A.DrawImage(B, ...) is called,
+// it can be said that the image A depends on the image B.
+//
+// * Fill, WritePixels and Dispose
+//
+// These functions are also drawing functions and the target image stores the pixel data
+// instead of draw image history items. There is no dependency here.
+//
+// * Making images stale
+//
+// After any of the drawing functions is called, the target image can't be depended on by
+// any other images. For example, if an image A depends on an image B, and B is changed
+// by a Fill call after that, the image A can't depend on the image B anymore.
+// In this case, as the image B can no longer be used to restore the image A,
+// the image A becomes 'stale'.
+// As all the stale images are resolved before context lost happens,
+// draw image history items are kept as they are
+// (even if an image C depends on the stale image A, it is still fine).
+//
+// * Stale image
+//
+// A stale image is an image that can't be restored from the recorded information.
+// All stale images must be resolved by reading pixels from GPU before the frame ends.
+// If a source image of DrawImage is a stale image, the target always becomes stale.
+//
+// * Volatile image
+//
+// A volatile image is a special image that is always cleared when a frame starts.
+// For instance, the game screen passed via the update function is a volatile image.
+// A volatile image doesn't have to record the drawing history.
+// If a source image of DrawImage is a volatile image, the target always becomes stale.
 package restorable

internal/restorable/export_test.go

@@ -0,0 +1,23 @@
+// Copyright 2023 The Ebitengine Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package restorable
+
+import (
+	"image"
+)
+
+func AppendRegionRemovingDuplicates(regions *[]image.Rectangle, region image.Rectangle) {
+	appendRegionRemovingDuplicates(regions, region)
+}

internal/restorable/image.go

@@ -23,6 +23,60 @@ import (
 	"github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver"
 )
 
+type Pixels struct {
+	pixelsRecords *pixelsRecords
+}
+
+// Apply applies the Pixels state to the given image especially for restoring.
+func (p *Pixels) Apply(img *graphicscommand.Image) {
+	// Pixels doesn't clear the image. This is a caller's responsibility.
+
+	if p.pixelsRecords == nil {
+		return
+	}
+	p.pixelsRecords.apply(img)
+}
+
+func (p *Pixels) AddOrReplace(pix *graphics.ManagedBytes, region image.Rectangle) {
+	if p.pixelsRecords == nil {
+		p.pixelsRecords = &pixelsRecords{}
+	}
+	p.pixelsRecords.addOrReplace(pix, region)
+}
+
+func (p *Pixels) Clear(region image.Rectangle) {
+	// Note that we don't care whether the region is actually removed or not here. There is an actual case that
+	// the region is allocated but nothing is rendered. See TestDisposeImmediately at shareable package.
+	if p.pixelsRecords == nil {
+		return
+	}
+	p.pixelsRecords.clear(region)
+}
+
+func (p *Pixels) ReadPixels(pixels []byte, region image.Rectangle, imageWidth, imageHeight int) {
+	if p.pixelsRecords == nil {
+		for i := range pixels {
+			pixels[i] = 0
+		}
+		return
+	}
+	p.pixelsRecords.readPixels(pixels, region, imageWidth, imageHeight)
+}
+
+func (p *Pixels) AppendRegion(regions []image.Rectangle) []image.Rectangle {
+	if p.pixelsRecords == nil {
+		return regions
+	}
+	return p.pixelsRecords.appendRegions(regions)
+}
+
+func (p *Pixels) Dispose() {
+	if p.pixelsRecords == nil {
+		return
+	}
+	p.pixelsRecords.dispose()
+}
+
 type ImageType int
 
 const (
@@ -33,16 +87,44 @@ const (
 	ImageTypeScreen
 
 	// ImageTypeVolatile indicates the image is cleared whenever a frame starts.
+	//
+	// Regular non-volatile images need to record drawing history or read its pixels from GPU if necessary so that all
+	// the images can be restored automatically from the context lost. However, such recording the drawing history or
+	// reading pixels from GPU are expensive operations. Volatile images can skip such operations, but the image content
+	// is cleared every frame instead.
 	ImageTypeVolatile
 )
 
-// Image represents an image.
+// Image represents an image that can be restored when GL context is lost.
 type Image struct {
 	image *graphicscommand.Image
 
 	width  int
 	height int
 
+	basePixels Pixels
+
+	// stale indicates whether the image needs to be synced with GPU as soon as possible.
+	stale bool
+
+	// staleRegions indicates the regions to restore.
+	// staleRegions is valid only when stale is true.
+	// staleRegions is not used when AlwaysReadPixelsFromGPU() returns true.
+	staleRegions []image.Rectangle
+
+	// pixelsCache is cached byte slices for pixels.
+	// pixelsCache is just a cache to avoid allocations (#2375).
+	//
+	// A key is the region and a value is a byte slice for the region.
+	//
+	// It is fine to reuse the same byte slice for the same region for basePixels,
+	// as old pixels for the same region will be invalidated at basePixel.AddOrReplace.
+	pixelsCache map[image.Rectangle][]byte
+
+	// regionsCache is cached regions.
+	// regionsCache is just a cache to avoid allocations (#2375).
+	regionsCache []image.Rectangle
+
 	imageType ImageType
 }
 
@@ -102,11 +184,20 @@ func clearImage(i *graphicscommand.Image, region image.Rectangle) {
 	i.DrawTriangles([graphics.ShaderSrcImageCount]*graphicscommand.Image{}, vs, is, graphicsdriver.BlendClear, region, [graphics.ShaderSrcImageCount]image.Rectangle{}, clearShader.shader, nil, graphicsdriver.FillRuleFillAll)
 }
 
+// makeStale makes the image stale.
+func (i *Image) makeStale(rect image.Rectangle) {
+	i.stale = true
+}
+
 // ClearPixels clears the specified region by WritePixels.
 func (i *Image) ClearPixels(region image.Rectangle) {
 	i.WritePixels(nil, region)
 }
 
+func (i *Image) needsRestoring() bool {
+	return i.imageType == ImageTypeRegular
+}
+
 // WritePixels replaces the image pixels with the given pixels slice.
 //
 // The specified region must not be overlapped with other regions by WritePixels.
@@ -119,11 +210,18 @@ func (i *Image) WritePixels(pixels *graphics.ManagedBytes, region image.Rectangl
 		panic(fmt.Sprintf("restorable: out of range %v", region))
 	}
 
+	// TODO: Avoid making other images stale if possible. (#514)
+	// For this purpose, images should remember which part of that is used for DrawTriangles.
+	theImages.makeStaleIfDependingOn(i)
+
 	if pixels != nil {
 		i.image.WritePixels(pixels, region)
 	} else {
 		clearImage(i.image, region)
 	}
+
+	// Even if the image is already stale, call makeStale to extend the stale region.
+	i.makeStale(region)
 }
 
 // DrawTriangles draws triangles with the given image.
@@ -142,6 +240,10 @@ func (i *Image) DrawTriangles(srcs [graphics.ShaderSrcImageCount]*Image, vertice
 	if len(vertices) == 0 {
 		return
 	}
+	theImages.makeStaleIfDependingOn(i)
+
+	// Even if the image is already stale, call makeStale to extend the stale region.
+	i.makeStale(dstRegion)
 
 	var imgs [graphics.ShaderSrcImageCount]*graphicscommand.Image
 	for i, src := range srcs {
@@ -165,13 +267,100 @@ func (i *Image) ReadPixels(graphicsDriver graphicsdriver.Graphics, pixels []byte
 	return nil
 }
 
+// makeStaleIfDependingOn makes the image stale if the image depends on target.
+func (i *Image) makeStaleIfDependingOn(target *Image) {
+	if i.stale {
+		return
+	}
+	if i.dependsOn(target) {
+		// There is no new region to make stale.
+		i.makeStale(image.Rectangle{})
+	}
+}
+
+// makeStaleIfDependingOnShader makes the image stale if the image depends on shader.
+func (i *Image) makeStaleIfDependingOnShader(shader *Shader) {
+	if i.stale {
+		return
+	}
+	if i.dependsOnShader(shader) {
+		// There is no new region to make stale.
+		i.makeStale(image.Rectangle{})
+	}
+}
+
+// dependsOn reports whether the image depends on target.
+func (i *Image) dependsOn(target *Image) bool {
+	return false
+}
+
+// dependsOnShader reports whether the image depends on shader.
+func (i *Image) dependsOnShader(shader *Shader) bool {
+	return false
+}
+
+// dependingImages returns all images that is depended on the image.
+func (i *Image) dependingImages() map[*Image]struct{} {
+	r := map[*Image]struct{}{}
+	return r
+}
+
+// hasDependency returns a boolean value indicating whether the image depends on another image.
+func (i *Image) hasDependency() bool {
+	return false
+}
+
+// Restore restores *graphicscommand.Image from the pixels using its state.
+func (i *Image) restore(graphicsDriver graphicsdriver.Graphics) error {
+	w, h := i.width, i.height
+	// Do not dispose the image here. The image should be already disposed.
+
+	switch i.imageType {
+	case ImageTypeScreen:
+		// The screen image should also be recreated because framebuffer might
+		// be changed.
+		i.image = graphicscommand.NewImage(w, h, true)
+		i.basePixels.Dispose()
+		i.basePixels = Pixels{}
+		i.stale = false
+		i.staleRegions = i.staleRegions[:0]
+		return nil
+	case ImageTypeVolatile:
+		i.image = graphicscommand.NewImage(w, h, false)
+		iw, ih := i.image.InternalSize()
+		clearImage(i.image, image.Rect(0, 0, iw, ih))
+		return nil
+	}
+
+	if i.stale {
+		panic("restorable: pixels must not be stale when restoring")
+	}
+
+	gimg := graphicscommand.NewImage(w, h, false)
+	// Clear the image explicitly.
+	iw, ih := gimg.InternalSize()
+	clearImage(gimg, image.Rect(0, 0, iw, ih))
+
+	i.basePixels.Apply(gimg)
+
+	i.image = gimg
+	i.stale = false
+	i.staleRegions = i.staleRegions[:0]
+	return nil
+}
+
 // Dispose disposes the image.
 //
 // After disposing, calling the function of the image causes unexpected results.
 func (i *Image) Dispose() {
 	theImages.remove(i)
 	i.image.Dispose()
 	i.image = nil
+	i.basePixels.Dispose()
+	i.basePixels = Pixels{}
+	i.pixelsCache = nil
+	i.stale = false
+	i.staleRegions = i.staleRegions[:0]
 }
 
 func (i *Image) Dump(graphicsDriver graphicsdriver.Graphics, path string, blackbg bool, rect image.Rectangle) (string, error) {
@@ -181,3 +370,30 @@ func (i *Image) Dump(graphicsDriver graphicsdriver.Graphics, path string, blackb
 func (i *Image) InternalSize() (int, int) {
 	return i.image.InternalSize()
 }
+
+// appendRegionRemovingDuplicates adds a region to a given list of regions,
+// but removes any duplicate between the newly added region and any existing regions.
+//
+// In case the newly added region is fully contained in any pre-existing region, this function does nothing.
+// Otherwise, any pre-existing regions that are fully contained in the newly added region are removed.
+//
+// This is done to avoid unnecessary reading pixels from GPU.
+func appendRegionRemovingDuplicates(regions *[]image.Rectangle, region image.Rectangle) {
+	for _, r := range *regions {
+		if region.In(r) {
+			// The newly added rectangle is fully contained in one of the input regions.
+			// Nothing to add.
+			return
+		}
+	}
+	// Separate loop, as regions must not get mutated before above return.
+	n := 0
+	for _, r := range *regions {
+		if r.In(region) {
+			continue
+		}
+		(*regions)[n] = r
+		n++
+	}
+	*regions = append((*regions)[:n], region)
+}