restorable

Documentation

Overview

Package restorable offers an Image struct that stores image commands and restores its pixel data from the commands when context lost happens.

When a function like DrawImage or Fill is called, an Image tries to record the information for restoring.

* 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 Ebiten'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, ReplacePixels 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 any more. 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.

Index

• Constants
• func ClearVolatileImages()
• func CopyImage(origImg image.Image) *image.RGBA
• func EnableRestoringForTesting()
• func InitializeGLState() error
• func IsRestoringEnabled() bool
• func QuadVertexSizeInBytes() int
• func ResolveStaleImages() error
• func Restore() error
• type Image
  • func NewImage(width, height int, filter graphics.Filter, volatile bool) *Image
  • func NewImageFromImage(source image.Image, filter graphics.Filter) *Image
  • func NewScreenFramebufferImage(width, height int, offsetX, offsetY float64) *Image
  • func (i *Image) At(x, y int) (color.RGBA, error)
  • func (i *Image) BasePixelsForTesting() []byte
  • func (i *Image) Dispose()
  • func (i *Image) DrawImage(img *Image, vertices []float32, colorm *affine.ColorM, ...)
  • func (i *Image) Fill(r, g, b, a uint8)
  • func (i *Image) IsInvalidated() (bool, error)
  • func (i *Image) ReplacePixels(pixels []byte)
  • func (i *Image) Size() (int, int)

Constants

const MaxImageSize = graphics.MaxImageSize

MaxImageSize represents the maximum width/height of an image.

Functions

func ClearVolatileImages

func ClearVolatileImages()

ClearVolatileImages clears volatile images.

ClearVolatileImages is intended to be called at the start of a frame.

func CopyImage

func CopyImage(origImg image.Image) *image.RGBA

CopyImage copies origImg to a new RGBA image.

Basically CopyImage just calls draw.Draw. If origImg is a paletted image, an optimized copying method is used.

CopyImage is used only internally but it is exposed for testing.

func EnableRestoringForTesting

func EnableRestoringForTesting()

EnableRestoringForTesting forces to enable restoring for testing.

func InitializeGLState

func InitializeGLState() error

InitializeGLState initializes the GL state.

func IsRestoringEnabled

func IsRestoringEnabled() bool

IsRestoringEnabled returns a boolean value indicating whether restoring process works or not.

func QuadVertexSizeInBytes

func QuadVertexSizeInBytes() int

QuadVertexSizeInBytes returns the byte size of vertices for a quadrilateral.

func ResolveStaleImages

func ResolveStaleImages() error

ResolveStaleImages flushes the queued draw commands and resolves all stale images.

ResolveStaleImages is intended to be called at the end of a frame.

func Restore

func Restore() error

Restore restores the images.

Restoring means to make all *graphics.Image objects have their textures and framebuffers.

Types

type Image

type Image struct {
	// contains filtered or unexported fields
}

Image represents an image that can be restored when GL context is lost.

func NewImage

func NewImage(width, height int, filter graphics.Filter, volatile bool) *Image

NewImage creates an empty image with the given size and filter.

func NewImageFromImage

func NewImageFromImage(source image.Image, filter graphics.Filter) *Image

NewImageFromImage creates an image with source image.

func NewScreenFramebufferImage

func NewScreenFramebufferImage(width, height int, offsetX, offsetY float64) *Image

NewScreenFramebufferImage creates a special image that framebuffer is one for the screen.

func (*Image) At

func (i *Image) At(x, y int) (color.RGBA, error)

At returns a color value at (x, y).

Note that this must not be called until context is available.

func (*Image) BasePixelsForTesting

func (i *Image) BasePixelsForTesting() []byte

BasePixelsForTesting returns the image's basePixels for testing.

func (*Image) Dispose

func (i *Image) Dispose()

Dispose disposes the image.

After disposing, calling the function of the image causes unexpected results.

func (*Image) DrawImage

func (i *Image) DrawImage(img *Image, vertices []float32, colorm *affine.ColorM, mode opengl.CompositeMode)

DrawImage draws a given image img to the image.

func (*Image) Fill

func (i *Image) Fill(r, g, b, a uint8)

Fill fills the image with the given color.

func (*Image) IsInvalidated

func (i *Image) IsInvalidated() (bool, error)

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 (*Image) ReplacePixels

func (i *Image) ReplacePixels(pixels []byte)

ReplacePixels replaces the image pixels with the given pixels slice.

func (*Image) Size

func (i *Image) Size() (int, int)

Size returns the image's size.