What unmanaged images are good for? Can we have a couple of examples?

[quasilyte]

I usually stumble across this comment:

ebiten/image.go

Line 1427 in 2eddff9

// Unmanaged is useful when you want finer controls over the image for performance and memory reasons.

And I wonder: this feature had some rationale behind it, right?
Someone knew what can be done with it, which performance benefits can be gained and what use cases can need an unmanaged image for better performance.

So if we can discuss it here and get extra information, maybe it can be added to that option's comment?
If not, then at the very least there will be this ticket for anyone wondering in the future (I still think having a short info in the source code or a link to this or some other internet resource for extra info is useful for discoverability).

[hajimehoshi]

This is useful to get (almost) full control for memory managements in some environments with very limited available memory. I know there is at least one actual usage, but this is not public so I cannot show this as an example.

[quasilyte]

I think I get the overall idea, but it would require investigation and source reading to know whether it's good in some of my "use case ideas". So I would like to hear from Ebitengine users about their use cases for it, perhaps it intersects with my needs or maybe it will add the extra context I might be missing right now. :)
I hope someone has such a case to share 👉👈

[tinne26]

For me the main usage is not memory limited environments, but making complex drawing chains viable. https://github.com/erparts/go-shapes is a public package that makes plenty of use of unmanaged images, and it necessarily needs to do so (mainly due to automatic memory management limitations):

• When you are only drawing from source images to a screen, automatic management is good enough.
• When you need complex draw chains (A => B, B => C, A + B => screen (and many others)), automatic texture management starts to get inefficient and even outright fail (I need to spend some time reproducing this, but another person managed to reproduce the same issues I had with a complex draw chain). Basically, automatic memory management can enter a loop of images copies and new atlas generation because multiple images are used as both sources and targets before going into the screen. This is fairly common with multi-pass shaders, e.g. hierarchical blurs, jump flooding and others.

The second case is similar but more oriented to pure optimization: using DrawTriangles over a set of images. For example, if you are doing text rendering or dynamic atlas generation of many small images, the ideal way to cache that is to put everything into the same atlas and use DrawTriangles for minimal overhead... and with a limited set of images you can do and you do that. You can technically do this without unmanaged images, but for large images intended to be used as atlases, automatic memory management has no advantages and risks significantly hurting performance in some specific cases. This also comes up for particle systems, to give another example. But in the really hard case where you don't know how many images you will have you can't even do that. A complete solution needs to consider what happens when you can't put everything into the same atlas anymore. In those cases, you need multiple atlases and manual swaps to deal with overfilling of the cache texture. Which is ideally done with multiple unmanaged images.

In fact, this is very important and I really want to make a package to expose multiple unmanaged images for draw optimization with DrawTriangles and atlas reuse for complex draw chains and specific caches. You can do DrawTriangles without an unmanaged image, and Zyko has https://github.com/Zyko0/Ebiary/tree/main/atlas which offers the option (both managed and unmanaged), but what I mentioned earlier: for big images, managed can be risky (ebitengine will almost always have to switch atlas anyway, and you risk the automatic texture management trying to move that around reusing tiny bits of space left on the underlying atlas); and unmanaged images also have other pros in terms of flexibility and reuse control. But yeah, Zyko's atlas is not even considering all the hardest cases.

So, imo unmanaged images are super important for a large number of advanced use-cases.

[quasilyte]

I do use some dst<->src chains in my games and I was considering unmanaged images for that. The only issue is that I know they don't play nice with draw batching (?) and it's hard to tell how to use them and not screw up with a number of draw calls.

My common use cases are:

• recolor an image. A source image colors are replaced with a shader, which means we usually need to create a new image for the result (the recolored version). That image is first used as a destination (we draw recolored pixels there) and then as a source (after it's done and we want to display it).
• generating a new image based on several base images. All of these are dst first, then src. This includes many use cases: background generation (taking several source images and then combining them and/or applying some noise to them), modular avatars/units/objects (combining several layered sprites into a single one)
• fully program-generated images, like a heavy shader-generated graphics that we want to render to an image once and use it as a ready-to-use texture later

I have a feeling that making every "generated" (dst -> src) image unmanaged is not an option, it would mean hundreds of small images not being a part of a draw batch (does every one of them gets drawn in a separate draw call?). So maybe what I need to do is to have an unmanaged large image like 1000x1000 and use it as an atlas for all of those generated images?

Another an perhaps a bit unrelated use case is temporary images. You mentioned the shader pipelines and it's also something I'm interested in. AFAIK, there is no way to do shader processing like A->A->A where A is an image, so we usually need a temporary image to work with that. That temporary image is also something that I wonder can benefit from being in an unmanaged category.