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 restoration.

* 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 restoration.

* 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.

Index

• func AlwaysReadPixelsFromGPU() bool
• func Disable()
• func DumpImages(graphicsDriver graphicsdriver.Graphics, dir string) (string, error)
• func InitializeGraphicsDriverState(graphicsDriver graphicsdriver.Graphics) error
• func MaxImageSize(graphicsDriver graphicsdriver.Graphics) int
• func OnContextLost()
• func RestoreIfNeeded(graphicsDriver graphicsdriver.Graphics) error
• func SwapBuffers(graphicsDriver graphicsdriver.Graphics) error
• type Hint
• type Image
  • func NewImage(width, height int, imageType ImageType) *Image
  • func (i *Image) BasePixelsForTesting() *Pixels
  • func (i *Image) ClearPixels(region image.Rectangle)
  • func (i *Image) Dispose()
  • func (i *Image) DrawTriangles(srcs [graphics.ShaderSrcImageCount]*Image, vertices []float32, ...)
  • func (i *Image) Dump(graphicsDriver graphicsdriver.Graphics, path string, blackbg bool, ...) (string, error)
  • func (i *Image) Extend(width, height int) *Image
  • func (i *Image) InternalSize() (int, int)
  • func (i *Image) ReadPixels(graphicsDriver graphicsdriver.Graphics, pixels []byte, region image.Rectangle) error
  • func (i *Image) WritePixels(pixels *graphics.ManagedBytes, region image.Rectangle)
• type ImageType
• type Pixels
  • func (p *Pixels) AddOrReplace(pix *graphics.ManagedBytes, region image.Rectangle)
  • func (p *Pixels) AppendRegion(regions []image.Rectangle) []image.Rectangle
  • func (p *Pixels) Apply(img *graphicscommand.Image)
  • func (p *Pixels) Clear(region image.Rectangle)
  • func (p *Pixels) Dispose()
  • func (p *Pixels) ReadPixels(pixels []byte, region image.Rectangle, imageWidth, imageHeight int)
• type Shader
  • func NewShader(ir *shaderir.Program, name string) *Shader
  • func (s *Shader) Dispose()
  • func (s *Shader) Unit() shaderir.Unit

Functions

func AlwaysReadPixelsFromGPU

func AlwaysReadPixelsFromGPU() bool

AlwaysReadPixelsFromGPU reports whether ReadPixels always reads pixels from GPU or not.

func Disable

func Disable()

Disable disables restoration.

func DumpImages

func DumpImages(graphicsDriver graphicsdriver.Graphics, dir string) (string, error)

DumpImages dumps all the current images to the specified directory.

This is for testing usage.

func InitializeGraphicsDriverState

func InitializeGraphicsDriverState(graphicsDriver graphicsdriver.Graphics) error

InitializeGraphicsDriverState initializes the graphics driver state.

func MaxImageSize

func MaxImageSize(graphicsDriver graphicsdriver.Graphics) int

MaxImageSize returns the maximum size of an image.

func OnContextLost

func OnContextLost()

OnContextLost is called when the context lost is detected in an explicit way.

func RestoreIfNeeded

func RestoreIfNeeded(graphicsDriver graphicsdriver.Graphics) error

RestoreIfNeeded restores the images.

Restoration means to make all *graphicscommand.Image objects have their textures and framebuffers.

func SwapBuffers

func SwapBuffers(graphicsDriver graphicsdriver.Graphics) error

Types

type Hint

type Hint int

Hint is a hint to optimize the info to restore the image.

const (
	// HintNone indicates that there is no hint.
	HintNone Hint = iota

	// HintOverwriteDstRegion indicates that the destination region is overwritten.
	// HintOverwriteDstRegion helps to reduce the size of the draw-image history.
	HintOverwriteDstRegion
)

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, imageType ImageType) *Image

NewImage creates an emtpy image with the given size.

The returned image is cleared.

Note that Dispose is not called automatically.

func (*Image) BasePixelsForTesting

func (i *Image) BasePixelsForTesting() *Pixels

BasePixelsForTesting returns the image's basePixels for testing.

func (*Image) ClearPixels

func (i *Image) ClearPixels(region image.Rectangle)

ClearPixels clears the specified region by WritePixels.

func (*Image) Dispose

func (i *Image) Dispose()

Dispose disposes the image.

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

func (*Image) DrawTriangles

func (i *Image) DrawTriangles(srcs [graphics.ShaderSrcImageCount]*Image, vertices []float32, indices []uint32, blend graphicsdriver.Blend, dstRegion image.Rectangle, srcRegions [graphics.ShaderSrcImageCount]image.Rectangle, shader *Shader, uniforms []uint32, fillRule graphicsdriver.FillRule, hint Hint)

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 texels
3: Source Y in texels
4: Color R [0.0-1.0]
5: Color G
6: Color B
7: Color Y

func (*Image) Dump

func (i *Image) Dump(graphicsDriver graphicsdriver.Graphics, path string, blackbg bool, rect image.Rectangle) (string, error)

func (*Image) Extend

func (i *Image) Extend(width, height int) *Image

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.

func (*Image) InternalSize

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

func (*Image) ReadPixels

func (i *Image) ReadPixels(graphicsDriver graphicsdriver.Graphics, pixels []byte, region image.Rectangle) error

func (*Image) WritePixels

func (i *Image) WritePixels(pixels *graphics.ManagedBytes, region image.Rectangle)

WritePixels replaces the image pixels with the given pixels slice.

The specified region must not be overlapped with other regions by WritePixels.

type ImageType

type ImageType int

const (
	// ImageTypeRegular indicates the image is a regular image.
	ImageTypeRegular ImageType = iota

	// ImageTypeScreen indicates the image is used as an actual screen.
	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
)

type Pixels

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

func (*Pixels) AddOrReplace

func (p *Pixels) AddOrReplace(pix *graphics.ManagedBytes, region image.Rectangle)

func (*Pixels) AppendRegion

func (p *Pixels) AppendRegion(regions []image.Rectangle) []image.Rectangle

func (*Pixels) Apply

func (p *Pixels) Apply(img *graphicscommand.Image)

Apply applies the Pixels state to the given image especially for restoration.

func (*Pixels) Clear

func (p *Pixels) Clear(region image.Rectangle)

func (*Pixels) Dispose

func (p *Pixels) Dispose()

func (*Pixels) ReadPixels

func (p *Pixels) ReadPixels(pixels []byte, region image.Rectangle, imageWidth, imageHeight int)

type Shader

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

var (
	NearestFilterShader *Shader
	LinearFilterShader  *Shader
)

func NewShader

func NewShader(ir *shaderir.Program, name string) *Shader

func (*Shader) Dispose

func (s *Shader) Dispose()

func (*Shader) Unit

func (s *Shader) Unit() shaderir.Unit