ebiten: add a new image API to 'deallocate' its internal state and deprecate Dispose

[hajimehoshi]

Operating System

• Windows
• macOS
• Linux
• FreeBSD
• OpenBSD
• Android
• iOS
• Nintendo Switch
• PlayStation 5
• Xbox
• Web Browsers

What feature would you like to be added?

If an image is disposed, the image is no longer available. While explicit dispoing is necessary for actual games, I don't like the exisistence of this additional state in an image. Actually, this prevents us from introducing some optimization (#825 (comment)). (EDIT: Now Dispose does nothing for a subimage, we might be able to introduce this optimization.)

There are some possible solutions:

1. Changing the meaning of (*Image).Dispose. The new Dispose disposes the internal state of an image, but an image is still available as a cleared image. internal/atlas state is recreated when the image is used again. This is a breaking change, so this would be introduced in v3.
2. Changing the behavior of (*Image).Clear. If the image is not used for a while after Clear, Ebitengine can dispose its internal state. If the image is used again, internal/atlas state is recreated like 1. This is not a breaking change so we can introduce in v2, but we have to be careful the performance impact. Also, the new Clear might be confusing to users. Dispose is deprecated in v2 and removed in v3.
3. Introducing a new function like (*Image).Clear2 or a better name, and deprecating (*Image).Dispose. Clear2 is the same as the new Deprecate in 1.

Why is this needed?

In order to simplify the model of an image.

[hajimehoshi]

For 3., what about (*Image).Unmap for example?

[Zyko0]

What about removing the Dispose method and have a global explicit method such as ebiten.DestroyImage (Free, Release, Collect are also potential keywords)
As for the behavior, it could be:
a. Take an **ebiten.Image (double pointer) as argument to ensure setting to nil the user-owned object after clearing internal resources (so that if fails on user side properly when accessing it again), but it probably feels a bit weird? => Would handle subimage, since it could be handled as a noop internally
b. Set the internal *ebiten.Image.image (internal image wrapped by an ebiten.Image) to nil so that any new attempt at a draw operation using it would segv => handles subimage as well

internal/atlas state is recreated when the image is used again.

The re-creation of the atlas in such cases sounds a bit complicated, no? Considering this is understandable for 2
But for 1, I don't understand why it should be possible to re-use an image as-is after disposing it (even if it's "possible")

[hajimehoshi]

This issue is to simplified the model of an image by removing the disposed state. I'm afraid I don't think your proposal aligns with this.

The re-creation of the atlas in such cases sounds a bit complicated, no?

An image just after NewImage is in the same situation, so there is nothing completed.

[hajimehoshi]

I'm adding comments from Discord:

My aim is to avoid a kind of 'dangling pointer': Now a disposed image is not available and cuases panics when used as a destination. In a new model, this would never happen as an unmapped image can be treated as a new cleared image.

Actually Dispose was an necessary evil as in an the ideal world GC should resolve everything, but in the actual world it does not.

Unmap would be useful when you are sure that the image is no longer used and want to remove the internal images to save GPU memory. Sometimes image references unexpectedly live so always depending on GC is risky especially for big projects.
Actually quasilyte had a similar issue. They found unepxected references, but before resolving them, Dispose helped them to confirm to save GPU memory.

[hajimehoshi]

Another name candidate is (*Image).ClearAndUnmap

[bjorndm]

I think Image.Dispose() is not really a problem, not more than the standard library File.Close(), or close(channel) is. We can't use closed files or closed channels either. By the way, I fee Close() is a good name in stead of Dispose().

[hajimehoshi]

I think Image.Dispose() is not really a problem, not more than the standard library File.Close(), or close(channel) is. We can't use closed files or closed channels either. By the way, I fee Close() is a good name in stead of Dispose().

This is not a name issue. Please read #2808 (comment)