ebiten/internal/restorable/image.go

// Copyright 2016 The Ebiten 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 (
	"fmt"
	"image/color"

	"github.com/hajimehoshi/ebiten/internal/affine"
	"github.com/hajimehoshi/ebiten/internal/driver"
	"github.com/hajimehoshi/ebiten/internal/graphics"
	"github.com/hajimehoshi/ebiten/internal/graphicscommand"
)

type Pixels struct {
	baseColor    color.RGBA
	rectToPixels *rectToPixels
}

// 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.baseColor != (color.RGBA{}) {
		fillImage(img, p.baseColor)
	}

	if p.rectToPixels == nil {
		return
	}
	p.rectToPixels.apply(img)
}

func (p *Pixels) AddOrReplace(pix []byte, x, y, width, height int) {
	if p.rectToPixels == nil {
		p.rectToPixels = &rectToPixels{}
	}
	p.rectToPixels.addOrReplace(pix, x, y, width, height)
}

func (p *Pixels) Remove(x, y, width, height int) {
	// 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.rectToPixels == nil {
		return
	}
	p.rectToPixels.remove(x, y, width, height)
}

func (p *Pixels) At(i, j int) (byte, byte, byte, byte) {
	if p.rectToPixels != nil {
		if r, g, b, a, ok := p.rectToPixels.at(i, j); ok {
			return r, g, b, a
		}
	}
	return p.baseColor.R, p.baseColor.G, p.baseColor.B, p.baseColor.A
}

// drawTrianglesHistoryItem is an item for history of draw-image commands.
type drawTrianglesHistoryItem struct {
	image    *Image
	vertices []float32
	indices  []uint16
	colorm   *affine.ColorM
	mode     driver.CompositeMode
	filter   driver.Filter
	address  driver.Address
}

// 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

	// drawTrianglesHistory is a set of draw-image commands.
	// TODO: This should be merged with the similar command queue in package graphics (#433).
	drawTrianglesHistory []*drawTrianglesHistoryItem

	// 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.
	screen bool

	// priority indicates whether the image is restored in high priority when context-lost happens.
	priority bool
}

var emptyImage *Image

func init() {
	// Use a big-enough image as an rendering source. By enlarging with x128, this can reach to 16384.
	// See #907 for details.
	const w, h = 128, 128
	emptyImage = &Image{
		image:    graphicscommand.NewImage(w, h),
		width:    w,
		height:   h,
		priority: true,
	}
	pix := make([]byte, 4*w*h)
	for i := range pix {
		pix[i] = 0xff
	}

	// As emptyImage is the source at clearImage, initialize this with ReplacePixels, not clearImage.
	// This operation is also important when restoring emptyImage.
	emptyImage.ReplacePixels(pix, 0, 0, w, h)
	theImages.add(emptyImage)
}

// NewImage creates an empty image with the given size.
//
// volatile indicates whether the image is volatile. 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 oprations, but the image content is cleared every frame instead.
//
// The returned image is cleared.
//
// Note that Dispose is not called automatically.
func NewImage(width, height int, volatile bool) *Image {
	i := &Image{
		image:    graphicscommand.NewImage(width, height),
		width:    width,
		height:   height,
		volatile: volatile,
	}
	i.clear()
	theImages.add(i)
	return i
}

// Extend extends the image by the given size.
// Extend creates a new image with the given size and copies the pixels of the given source image.
// Extend disposes itself after its call.
//
// If the given size (width and height) is smaller than the source image, ExtendImage panics.
//
// The image must be ReplacePixels-only image. Extend panics when Fill or DrawTriangles are applied on the image.
//
// Extend panics when the image is stale.
func (i *Image) Extend(width, height int) *Image {
	if i.width > width || i.height > height {
		panic(fmt.Sprintf("restorable: the original size (%d, %d) cannot be extended to (%d, %d)", i.width, i.height, width, height))
	}

	if i.stale {
		panic("restorable: Extend at a stale image is forbidden")
	}

	if len(i.drawTrianglesHistory) > 0 {
		panic("restorable: Extend after DrawTriangles is forbidden")
	}

	newImg := NewImage(width, height, i.volatile)
	i.basePixels.Apply(newImg.image)

	if i.basePixels.baseColor != (color.RGBA{}) {
		panic("restorable: baseColor must be empty at Extend")
	}
	newImg.basePixels = i.basePixels

	i.Dispose()

	return newImg
}

// NewScreenFramebufferImage creates a special image that framebuffer is one for the screen.
//
// The returned image is cleared.
//
// Note that Dispose is not called automatically.
func NewScreenFramebufferImage(width, height int) *Image {
	i := &Image{
		image:  graphicscommand.NewScreenFramebufferImage(width, height),
		width:  width,
		height: height,
		screen: true,
	}
	i.clear()
	theImages.add(i)
	return i
}

func (i *Image) Clear() {
	theImages.makeStaleIfDependingOn(i)
	i.clear()
}

// quadVertices returns vertices to render a quad. These values are passed to graphicscommand.Image.
func quadVertices(dx0, dy0, dx1, dy1, sx0, sy0, sx1, sy1, cr, cg, cb, ca float32) []float32 {
	return []float32{
		dx0, dy0, sx0, sy0, sx0, sy0, sx1, sy1, cr, cg, cb, ca,
		dx1, dy0, sx1, sy0, sx0, sy0, sx1, sy1, cr, cg, cb, ca,
		dx0, dy1, sx0, sy1, sx0, sy0, sx1, sy1, cr, cg, cb, ca,
		dx1, dy1, sx1, sy1, sx0, sy0, sx1, sy1, cr, cg, cb, ca,
	}
}

// clearImage clears a graphicscommand.Image.
// This does nothing to do with a restorable.Image's rendering state.
func clearImage(img *graphicscommand.Image) {
	if img == emptyImage.image {
		panic("restorable: clearImage cannot be called on emptyImage")
	}

	// There are not 'drawTrianglesHistoryItem's for this image and emptyImage.
	// As emptyImage is a priority image, this is restored before other regular images are restored.

	// The rendering target size needs to be its 'internal' size instead of the exposed size to avoid glitches on
	// mobile platforms (See the change 1e1f309a).
	dw, dh := img.InternalSize()
	sw, sh := emptyImage.image.InternalSize()
	vs := quadVertices(0, 0, float32(dw), float32(dh), 0, 0, float32(sw), float32(sh), 0, 0, 0, 0)
	is := graphics.QuadIndices()
	// The first DrawTriangles must be clear mode for initialization.
	// TODO: Can the graphicscommand package hide this knowledge?
	img.DrawTriangles(emptyImage.image, vs, is, nil, driver.CompositeModeClear, driver.FilterNearest, driver.AddressClampToZero)
}

func (i *Image) clear() {
	if i.priority {
		panic("restorable: clear cannot be called on a priority image")
	}

	clearImage(i.image)

	i.basePixels = Pixels{}
	i.drawTrianglesHistory = nil
	i.stale = false
}

// Fill fills the specified part of the image with a solid color.
func (i *Image) Fill(clr color.RGBA) {
	i.basePixels = Pixels{
		baseColor: clr,
	}
	i.drawTrianglesHistory = nil
	i.stale = false

	// Do not call i.DrawTriangles as emptyImage is special (#928).
	// baseColor is updated instead.
	fillImage(i.image, i.basePixels.baseColor)
}

func fillImage(i *graphicscommand.Image, clr color.RGBA) {
	if i == emptyImage.image {
		panic("restorable: fillImage cannot be called on emptyImage")
	}

	var rf, gf, bf, af float32
	if clr.A > 0 {
		rf = float32(clr.R) / float32(clr.A)
		gf = float32(clr.G) / float32(clr.A)
		bf = float32(clr.B) / float32(clr.A)
		af = float32(clr.A) / 0xff
	}

	// TODO: Use the previous composite mode if possible.
	compositemode := driver.CompositeModeSourceOver
	if af < 1.0 {
		compositemode = driver.CompositeModeCopy
	}

	// TODO: Integrate with clearColor
	dw, dh := i.InternalSize()
	sw, sh := emptyImage.image.InternalSize()
	vs := quadVertices(0, 0, float32(dw), float32(dh), 0, 0, float32(sw), float32(sh), rf, gf, bf, af)
	is := graphics.QuadIndices()

	i.DrawTriangles(emptyImage.image, vs, is, nil, compositemode, driver.FilterNearest, driver.AddressClampToZero)
}

// BasePixelsForTesting returns the image's basePixels for testing.
func (i *Image) BasePixelsForTesting() *Pixels {
	return &i.basePixels
}

// makeStale makes the image stale.
func (i *Image) makeStale() {
	i.basePixels = Pixels{}
	i.drawTrianglesHistory = nil
	i.stale = true

	// Don't have to call makeStale recursively here.
	// Restoring is done after topological sorting is done.
	// If an image depends on another stale image, this means that
	// the former image can be restored from the latest state of the latter image.
}

// ClearPixels clears the specified region by ReplacePixels.
func (i *Image) ClearPixels(x, y, width, height int) {
	i.ReplacePixels(nil, x, y, width, height)
}

// ReplacePixels replaces the image pixels with the given pixels slice.
//
// ReplacePixels for a part is forbidden if the image is rendered with DrawTriangles or Fill.
func (i *Image) ReplacePixels(pixels []byte, x, y, width, height int) {
	if width <= 0 || height <= 0 {
		panic("restorable: width/height must be positive")
	}
	w, h := i.width, i.height
	if x < 0 || y < 0 || w <= x || h <= y || x+width <= 0 || y+height <= 0 || w < x+width || h < y+height {
		panic(fmt.Sprintf("restorable: out of range x: %d, y: %d, width: %d, height: %d", x, y, width, height))
	}

	// TODO: Avoid making other images stale if possible. (#514)
	// For this purpuse, images should remember which part of that is used for DrawTriangles.
	theImages.makeStaleIfDependingOn(i)

	if pixels != nil {
		i.image.ReplacePixels(pixels, x, y, width, height)
	} else {
		// TODO: When pixels == nil, we don't have to care the pixel state there. In such cases, the image
		// accepts only ReplacePixels and not Fill or DrawTriangles.
		// TODO: Separate Image struct into two: images for only-ReplacePixels, and the others.
		i.image.ReplacePixels(make([]byte, 4*width*height), x, y, width, height)
	}

	if x == 0 && y == 0 && width == w && height == h {
		if pixels != nil {
			i.basePixels.AddOrReplace(pixels, 0, 0, w, h)
		} else {
			i.basePixels.Remove(0, 0, w, h)
		}
		i.drawTrianglesHistory = nil
		i.stale = false
		return
	}

	// It looked like ReplacePixels on a part of image deletes other region that are rendered by DrawTriangles
	// (#593, #758).

	if len(i.drawTrianglesHistory) > 0 {
		panic("restorable: ReplacePixels for a part after DrawTriangles is forbidden")
	}

	if i.stale {
		// TODO: panic here?
		return
	}

	if pixels != nil {
		i.basePixels.AddOrReplace(pixels, x, y, width, height)
	} else {
		i.basePixels.Remove(x, y, width, height)
	}
}

// DrawTriangles draws triangles with the given image.
//
// The vertex floats are:
//
//   0:  Destination X in pixels
//   1:  Destination Y in pixels
//   2:  Source X in pixels (not texels!)
//   3:  Source Y in pixels
//   4:  Bounds of the source min X in pixels
//   5:  Bounds of the source min Y in pixels
//   6:  Bounds of the source max X in pixels
//   7:  Bounds of the source max Y in pixels
//   8:  Color R [0.0-1.0]
//   9:  Color G
//   10: Color B
//   11: Color Y
func (i *Image) DrawTriangles(img *Image, vertices []float32, indices []uint16, colorm *affine.ColorM, mode driver.CompositeMode, filter driver.Filter, address driver.Address) {
	if i.priority {
		panic("restorable: DrawTriangles cannot be called on a priority image")
	}
	if len(vertices) == 0 {
		return
	}
	theImages.makeStaleIfDependingOn(i)

	if img.stale || img.volatile || i.screen || !needsRestoring() || i.volatile {
		i.makeStale()
	} else {
		i.appendDrawTrianglesHistory(img, vertices, indices, colorm, mode, filter, address)
	}
	i.image.DrawTriangles(img.image, vertices, indices, colorm, mode, filter, address)
}

// appendDrawTrianglesHistory appends a draw-image history item to the image.
func (i *Image) appendDrawTrianglesHistory(image *Image, vertices []float32, indices []uint16, colorm *affine.ColorM, mode driver.CompositeMode, filter driver.Filter, address driver.Address) {
	if i.stale || i.volatile || i.screen {
		return
	}
	// TODO: Would it be possible to merge draw image history items?
	const maxDrawTrianglesHistoryNum = 1024
	if len(i.drawTrianglesHistory)+1 > maxDrawTrianglesHistoryNum {
		i.makeStale()
		return
	}
	// All images must be resolved and not stale each after frame.
	// So we don't have to care if image is stale or not here.
	item := &drawTrianglesHistoryItem{
		image:    image,
		vertices: vertices,
		indices:  indices,
		colorm:   colorm,
		mode:     mode,
		filter:   filter,
		address:  address,
	}
	i.drawTrianglesHistory = append(i.drawTrianglesHistory, item)
}

func (i *Image) readPixelsFromGPUIfNeeded() {
	if len(i.drawTrianglesHistory) > 0 || i.stale {
		graphicscommand.FlushCommands()
		i.readPixelsFromGPU()
		i.drawTrianglesHistory = nil
		i.stale = false
	}
}

// At returns a color value at (x, y).
//
// Note that this must not be called until context is available.
func (i *Image) At(x, y int) (byte, byte, byte, byte) {
	if x < 0 || y < 0 || i.width <= x || i.height <= y {
		return 0, 0, 0, 0
	}

	i.readPixelsFromGPUIfNeeded()

	return i.basePixels.At(x, y)
}

// 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) {
		i.makeStale()
	}
}

// readPixelsFromGPU reads the pixels from GPU and resolves the image's 'stale' state.
func (i *Image) readPixelsFromGPU() {
	i.basePixels = Pixels{}
	i.basePixels.AddOrReplace(i.image.Pixels(), 0, 0, i.width, i.height)
	i.drawTrianglesHistory = nil
	i.stale = false
}

// resolveStale resolves the image's 'stale' state.
func (i *Image) resolveStale() {
	if !needsRestoring() {
		return
	}

	if i.volatile {
		return
	}
	if i.screen {
		return
	}
	if !i.stale {
		return
	}
	i.readPixelsFromGPU()
}

// dependsOn returns a boolean value indicating whether the image depends on target.
func (i *Image) dependsOn(target *Image) bool {
	for _, c := range i.drawTrianglesHistory {
		if c.image == target {
			return true
		}
	}
	return false
}

// dependingImages returns all images that is depended by the image.
func (i *Image) dependingImages() map[*Image]struct{} {
	r := map[*Image]struct{}{}
	for _, c := range i.drawTrianglesHistory {
		r[c.image] = struct{}{}
	}
	return r
}

// hasDependency returns a boolean value indicating whether the image depends on another image.
func (i *Image) hasDependency() bool {
	if i.stale {
		return false
	}
	return len(i.drawTrianglesHistory) > 0
}

// Restore restores *graphicscommand.Image from the pixels using its state.
func (i *Image) restore() {
	w, h := i.width, i.height
	// Do not dispose the image here. The image should be already disposed.

	if i.screen {
		// The screen image should also be recreated because framebuffer might
		// be changed.
		i.image = graphicscommand.NewScreenFramebufferImage(w, h)
		i.basePixels = Pixels{}
		i.drawTrianglesHistory = nil
		i.stale = false
		return
	}
	if i.volatile {
		i.image = graphicscommand.NewImage(w, h)
		i.clear()
		return
	}
	if i.stale {
		panic("restorable: pixels must not be stale when restoring")
	}

	gimg := graphicscommand.NewImage(w, h)
	// Clear the image explicitly.
	if i != emptyImage {
		// As clearImage uses emptyImage, clearImage cannot be called on emptyImage.
		// It is OK to skip this since emptyImage has its entire pixel information.
		clearImage(gimg)
	}
	i.basePixels.Apply(gimg)

	for _, c := range i.drawTrianglesHistory {
		if c.image.hasDependency() {
			panic("restorable: all dependencies must be already resolved but not")
		}
		gimg.DrawTriangles(c.image.image, c.vertices, c.indices, c.colorm, c.mode, c.filter, c.address)
	}

	if len(i.drawTrianglesHistory) > 0 {
		i.basePixels = Pixels{}
		i.basePixels.AddOrReplace(gimg.Pixels(), 0, 0, w, h)
	}

	i.image = gimg
	i.drawTrianglesHistory = nil
	i.stale = false
}

// 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 = Pixels{}
	i.drawTrianglesHistory = nil
	i.stale = false
}

// isInvalidated returns a boolean value indicating whether the image is invalidated.
//
// If an image is invalidated, GL context is lost and all the images should be restored asap.
func (i *Image) isInvalidated() bool {
	// FlushCommands is required because c.offscreen.impl might not have an actual texture.
	graphicscommand.FlushCommands()
	return i.image.IsInvalidated()
}

func (i *Image) Dump(path string) error {
	return i.image.Dump(path)
}