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.



    This section is empty.


    This section is empty.


    func DumpImages

    func DumpImages(dir string) error

      DumpImages dumps all the current images to the specified directory.

      This is for testing usage.

      func EnableRestoringForTesting

      func EnableRestoringForTesting()

        EnableRestoringForTesting forces to enable restoring for testing.

        func InitializeGraphicsDriverState

        func InitializeGraphicsDriverState() error

          InitializeGraphicsDriverState initializes the graphics driver state.

          func OnContextLost

          func OnContextLost()

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

            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 RestoreIfNeeded

              func RestoreIfNeeded() error

                RestoreIfNeeded restores the images.

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


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

                    NewImage creates an empty image with the given size.

                    The returned image is cleared.

                    Note that Dispose is not called automatically.

                    func NewScreenFramebufferImage

                    func NewScreenFramebufferImage(width, height int) *Image

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

                      func (i *Image) At(x, y int) (byte, byte, byte, byte, 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() *Pixels

                          BasePixelsForTesting returns the image's basePixels for testing.

                          func (*Image) ClearPixels

                          func (i *Image) ClearPixels(x, y, width, height int)

                            ClearPixels clears the specified region by ReplacePixels.

                            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.ShaderImageNum]*Image, offsets [graphics.ShaderImageNum - 1][2]float32, vertices []float32, indices []uint16, colorm *affine.ColorM, mode driver.CompositeMode, filter driver.Filter, address driver.Address, sourceRegion driver.Region, shader *Shader, uniforms []interface{})

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

                                func (*Image) Dump

                                func (i *Image) Dump(path string, blackbg bool) 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.

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

                                  func (i *Image) Fill(clr color.RGBA)

                                    Fill fills the specified part of the image with a solid color.

                                    func (*Image) ReplacePixels

                                    func (i *Image) ReplacePixels(pixels []byte, x, y, width, height int)

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

                                      func (i *Image) SetVolatile(volatile bool)

                                        SetVolatile sets the volatile state of the image.

                                        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.

                                        type Pixels

                                        type Pixels struct {
                                        	// contains filtered or unexported fields

                                        func (*Pixels) AddOrReplace

                                        func (p *Pixels) AddOrReplace(pix []byte, x, y, width, height int)

                                        func (*Pixels) Apply

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

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

                                          func (*Pixels) At

                                          func (p *Pixels) At(i, j int) (byte, byte, byte, byte)

                                          func (*Pixels) Remove

                                          func (p *Pixels) Remove(x, y, width, height int)

                                          type Shader

                                          type Shader struct {
                                          	// contains filtered or unexported fields

                                          func NewShader

                                          func NewShader(program *shaderir.Program) *Shader

                                          func (*Shader) Dispose

                                          func (s *Shader) Dispose()