internal/restorable: rename restoring -> restoration

This commit is contained in:
Hajime Hoshi 2024-09-07 19:07:13 +09:00
parent d50a438c07
commit 1b2a2afbfb
5 changed files with 35 additions and 35 deletions

View File

@ -16,7 +16,7 @@
// and restores its pixel data from the commands when context lost happens. // 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 // When a function like DrawImage or Fill is called, an Image tries to record
// the information for restoring. // the information for restoration.
// //
// * Context lost // * Context lost
// //
@ -26,7 +26,7 @@
// might cause context lost on mobiles. // might cause context lost on mobiles.
// As Ebitengine's image data is on GPU memory, the game can't continue when context lost happens // As Ebitengine's image data is on GPU memory, the game can't continue when context lost happens
// without restoring image information. // without restoring image information.
// The package restorable is the package to record information for such restoring. // The package restorable is the package to record information for such restoration.
// //
// * DrawImage // * DrawImage
// //

View File

@ -18,9 +18,9 @@ import (
"github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver" "github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver"
) )
// EnableRestoringForTesting forces to enable restoring for testing. // EnableRestorationForTesting forces to enable restoration for testing.
func EnableRestoringForTesting() { func EnableRestorationForTesting() {
forceRestoring = true forceRestoration = true
} }
func ResolveStaleImages(graphicsDriver graphicsdriver.Graphics) error { func ResolveStaleImages(graphicsDriver graphicsdriver.Graphics) error {

View File

@ -28,7 +28,7 @@ type Pixels struct {
pixelsRecords *pixelsRecords pixelsRecords *pixelsRecords
} }
// Apply applies the Pixels state to the given image especially for restoring. // Apply applies the Pixels state to the given image especially for restoration.
func (p *Pixels) Apply(img *graphicscommand.Image) { func (p *Pixels) Apply(img *graphicscommand.Image) {
// Pixels doesn't clear the image. This is a caller's responsibility. // Pixels doesn't clear the image. This is a caller's responsibility.
@ -230,7 +230,7 @@ func (i *Image) makeStale(rect image.Rectangle) {
} }
// Don't have to call makeStale recursively here. // Don't have to call makeStale recursively here.
// Restoring is done after topological sorting is done. // Restoration is done after topological sorting is done.
// If an image depends on another stale image, this means that // 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. // the former image can be restored from the latest state of the latter image.
} }
@ -240,7 +240,7 @@ func (i *Image) ClearPixels(region image.Rectangle) {
i.WritePixels(nil, region) i.WritePixels(nil, region)
} }
func (i *Image) needsRestoring() bool { func (i *Image) needsRestoration() bool {
return i.imageType == ImageTypeRegular return i.imageType == ImageTypeRegular
} }
@ -267,7 +267,7 @@ func (i *Image) WritePixels(pixels *graphics.ManagedBytes, region image.Rectangl
} }
// Even if the image is already stale, call makeStale to extend the stale region. // Even if the image is already stale, call makeStale to extend the stale region.
if !needsRestoring() || !i.needsRestoring() || i.stale { if !needsRestoration() || !i.needsRestoration() || i.stale {
i.makeStale(region) i.makeStale(region)
return return
} }
@ -330,7 +330,7 @@ func (i *Image) DrawTriangles(srcs [graphics.ShaderSrcImageCount]*Image, vertice
} }
// Even if the image is already stale, call makeStale to extend the stale region. // Even if the image is already stale, call makeStale to extend the stale region.
if srcstale || !needsRestoring() || !i.needsRestoring() || i.stale { if srcstale || !needsRestoration() || !i.needsRestoration() || i.stale {
i.makeStale(dstRegion) i.makeStale(dstRegion)
} else { } else {
i.appendDrawTrianglesHistory(srcs, vertices, indices, blend, dstRegion, srcRegions, shader, uniforms, fillRule) i.appendDrawTrianglesHistory(srcs, vertices, indices, blend, dstRegion, srcRegions, shader, uniforms, fillRule)
@ -348,8 +348,8 @@ func (i *Image) DrawTriangles(srcs [graphics.ShaderSrcImageCount]*Image, vertice
// appendDrawTrianglesHistory appends a draw-image history item to the image. // appendDrawTrianglesHistory appends a draw-image history item to the image.
func (i *Image) appendDrawTrianglesHistory(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) { func (i *Image) appendDrawTrianglesHistory(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) {
if i.stale || !i.needsRestoring() { if i.stale || !i.needsRestoration() {
panic("restorable: an image must not be stale or need restoring at appendDrawTrianglesHistory") panic("restorable: an image must not be stale or need restoration at appendDrawTrianglesHistory")
} }
if AlwaysReadPixelsFromGPU() { if AlwaysReadPixelsFromGPU() {
panic("restorable: appendDrawTrianglesHistory must not be called when AlwaysReadPixelsFromGPU() returns true") panic("restorable: appendDrawTrianglesHistory must not be called when AlwaysReadPixelsFromGPU() returns true")
@ -498,10 +498,10 @@ func (i *Image) readPixelsFromGPU(graphicsDriver graphicsdriver.Graphics) error
// resolveStale resolves the image's 'stale' state. // resolveStale resolves the image's 'stale' state.
func (i *Image) resolveStale(graphicsDriver graphicsdriver.Graphics) error { func (i *Image) resolveStale(graphicsDriver graphicsdriver.Graphics) error {
if !needsRestoring() { if !needsRestoration() {
return nil return nil
} }
if !i.needsRestoring() { if !i.needsRestoration() {
return nil return nil
} }
if !i.stale { if !i.stale {

View File

@ -25,28 +25,28 @@ import (
"github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver" "github.com/hajimehoshi/ebiten/v2/internal/graphicsdriver"
) )
// forceRestoring reports whether restoring forcibly happens or not. // forceRestoration reports whether restoration forcibly happens or not.
// This is used only for testing. // This is used only for testing.
var forceRestoring = false var forceRestoration = false
// disabled indicates that restoring is disabled or not. // disabled indicates that restoration is disabled or not.
// Restoring is enabled by default for some platforms like Android for safety. // Restoration is enabled by default for some platforms like Android for safety.
// Before SetGame, it is not possible to determine whether restoring is needed or not. // Before SetGame, it is not possible to determine whether restoration is needed or not.
var disabled atomic.Bool var disabled atomic.Bool
var disabledOnce sync.Once var disabledOnce sync.Once
// Disable disables restoring. // Disable disables restoration.
func Disable() { func Disable() {
disabled.Store(true) disabled.Store(true)
} }
// needsRestoring reports whether restoring process works or not. // needsRestoration reports whether restoration process works or not.
func needsRestoring() bool { func needsRestoration() bool {
if forceRestoring { if forceRestoration {
return true return true
} }
// TODO: If Vulkan is introduced, restoring might not be needed. // TODO: If Vulkan is introduced, restoration might not be needed.
if runtime.GOOS == "android" { if runtime.GOOS == "android" {
return !disabled.Load() return !disabled.Load()
} }
@ -55,7 +55,7 @@ func needsRestoring() bool {
// AlwaysReadPixelsFromGPU reports whether ReadPixels always reads pixels from GPU or not. // AlwaysReadPixelsFromGPU reports whether ReadPixels always reads pixels from GPU or not.
func AlwaysReadPixelsFromGPU() bool { func AlwaysReadPixelsFromGPU() bool {
return !needsRestoring() return !needsRestoration()
} }
// images is a set of Image objects. // images is a set of Image objects.
@ -99,7 +99,7 @@ func resolveStaleImages(graphicsDriver graphicsdriver.Graphics, endFrame bool) e
if err := graphicscommand.FlushCommands(graphicsDriver, endFrame); err != nil { if err := graphicscommand.FlushCommands(graphicsDriver, endFrame); err != nil {
return err return err
} }
if !needsRestoring() { if !needsRestoration() {
return nil return nil
} }
return theImages.resolveStaleImages(graphicsDriver) return theImages.resolveStaleImages(graphicsDriver)
@ -107,13 +107,13 @@ func resolveStaleImages(graphicsDriver graphicsdriver.Graphics, endFrame bool) e
// RestoreIfNeeded restores the images. // RestoreIfNeeded restores the images.
// //
// Restoring means to make all *graphicscommand.Image objects have their textures and framebuffers. // Restoration means to make all *graphicscommand.Image objects have their textures and framebuffers.
func RestoreIfNeeded(graphicsDriver graphicsdriver.Graphics) error { func RestoreIfNeeded(graphicsDriver graphicsdriver.Graphics) error {
if !needsRestoring() { if !needsRestoration() {
return nil return nil
} }
if !forceRestoring && !theImages.contextLost.Load() { if !forceRestoration && !theImages.contextLost.Load() {
return nil return nil
} }
@ -195,13 +195,13 @@ func (i *images) makeStaleIfDependingOnShader(shader *Shader) {
// restore restores the images. // restore restores the images.
// //
// Restoring means to make all *graphicscommand.Image objects have their textures and framebuffers. // Restoration means to make all *graphicscommand.Image objects have their textures and framebuffers.
func (i *images) restore(graphicsDriver graphicsdriver.Graphics) error { func (i *images) restore(graphicsDriver graphicsdriver.Graphics) error {
if !needsRestoring() { if !needsRestoration() {
panic("restorable: restore cannot be called when restoring is disabled") panic("restorable: restore cannot be called when restoration is disabled")
} }
// Dispose all the shaders ahead of restoring. A current shader ID and a new shader ID can be duplicated. // Dispose all the shaders ahead of restoration. A current shader ID and a new shader ID can be duplicated.
for s := range i.shaders { for s := range i.shaders {
s.shader.Dispose() s.shader.Dispose()
s.shader = nil s.shader = nil
@ -210,7 +210,7 @@ func (i *images) restore(graphicsDriver graphicsdriver.Graphics) error {
s.restore() s.restore()
} }
// Dispose all the images ahead of restoring. A current texture ID and a new texture ID can be duplicated. // Dispose all the images ahead of restoration. A current texture ID and a new texture ID can be duplicated.
// TODO: Write a test to confirm that ID duplication never happens. // TODO: Write a test to confirm that ID duplication never happens.
for i := range i.images { for i := range i.images {
i.image.Dispose() i.image.Dispose()

View File

@ -27,7 +27,7 @@ import (
) )
func TestMain(m *testing.M) { func TestMain(m *testing.M) {
restorable.EnableRestoringForTesting() restorable.EnableRestorationForTesting()
etesting.MainWithRunLoop(m) etesting.MainWithRunLoop(m)
} }