UI texture atlas support

[mwbryant]

Objective

This adds support for using texture atlas sprites in UI. From discussions today in the ui-dev discord it seems this is a much wanted feature.

This was previously attempted in #5070 by @ManevilleF however that was blocked #5103. This work can be easily modified to support #5103 changes after that merges.

Solution

I created a new UI bundle that reuses the existing texture atlas infrastructure. I create a new atlas image component to prevent it from being drawn by the existing non-UI systems and to remove unused parameters.

In extract I added new system to calculate the required values for the texture atlas image, this extracts into the same resource as the existing UI Image and Text components.

This should have minimal performance impact because if texture atlas is not present then the exact same code path is followed. Also there should be no unintended behavior changes because without the new components the existing systems write the extract same resulting data.

I also added an example showing the sprite working and a system to advance the animation on space bar presses.

Naming is hard and I would accept any feedback on the bundle name!

---

Changelog

Added TextureAtlasImageBundle

[github-actions]

You added a new example but didn't update the readme. Please run cargo run -p build-templated-pages -- update examples to update it, and commit the file change.

[ickshonpe]

Seems like it works fine, I identified lots of problems but they are all really down to the confused state of the render module and not the fault of the PR author.

Work still needed:

• Check that the UV coordinates on flipped images are correct after clipping (an easy way to do this would be to change the image in the Overflow example to an image from a texture atlas).
• Check that clipped images aren't stretched or shrunk with a scale factor not equal to 1.
• Needs a system similar to update_image_content_size_system that adds a Measure so that the UI can automatically size the image to preserve its aspect ratio instead of requiring a user to constrain the image's node to the exact dimensions.

I'm 90%+ sure this passes the first two checks, but need to make certain as those bugs have been reintroduced a few times.

[mwbryant]

uv_rect has been removed from ExtractedUiNode, now there should be no change to the existing flow. I also tested with the overflow example (and blundered some git commands....) as was suggested and clipping works:

[mwbryant]

New version now uses a standalone extract system and has a less confusing API by only using the parameters on UiTextureAtlasSprite that we actually use.

[mwbryant]

Also here is clipping working in the overflow example with flip x and y set and texture atlases being used in the scaling example. This should satisfy the other concerns in the top level comment if I am understanding them correctly (blur is caused by linear sampling, it's intended and changed the same way pixel art is used elsewhere):

[mwbryant]

With Measure setting system added this should be ready to go. I believe I have covered everything @ickshonpe requested and pointed out in their review. From my testing, every feature I am aware of works and none of the existing examples are broken (and there shouldn't be a mechanism for this to affect them)

[wilk10]

Thanks a lot for this!! I think this will make many users happy.

I have only left non blocking nits, feel free to ignore if you prefer.

Did you check if it works also when a normal UI node is a child of a node with an AtlasImageBundle? For example: Animated border around a normal button

[ickshonpe]

Thanks a lot for this!! I think this will make many users happy.
I have only left non blocking nits, feel free to ignore if you prefer.
Did you check if it works also when a normal UI node is a child of a node with an AtlasImageBundle? For example: Animated border around a normal button

With ImageBundle and AtlasImageBundle UI nodes you shouldn't give them child nodes as the MeasureFunc won't work. Instead, use a regular NodeBundle with its BackgroundColor set to white and insert either the UiImage component or, to display atlas images with this PR, Handle<TextureAtlas> and UiTextureAtlasSprite. Maybe there needs to be a separate bundle for image nodes without a MeasureFunc` as it's really unintuitive how the current API works.

Ok I didn't know that. But if it's the same behaviour as ImageBundle then it's not relevant for this PR specifically. Maybe it's worth a separate issue then?

Oh yes definitely a separate issue, I didn't mean that as a suggestion for this PR

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[ickshonpe]

It looks good now. Just left some non-essential suggestions for the example you can apply if you like.

[pkupper]

Considering #5103 may be merged soon, how does this compare to #5070 which is based on that Texture Atlas Rework PR? I personally find the API proposed in #5070 slightly more ergonomic.

[mwbryant]

Considering #5103 may be merged soon, how does this compare to #5070 which is based on that Texture Atlas Rework PR? I personally find the API proposed in #5070 slightly more ergonomic.

If #5103 is merged then I can rework this pr to use the new interface and then API will be identical, the only difference is they don't create a new bundle for texture atlas ui nodes which is debatable.

Looking at #5070 shows that it's current state is pretty similar to the first draft of this PR. Since then there's been some work to ensure scaling, clipping and the measure systems all work with this PR and that is missing from #5070 (from a quick glance). This makes me personally believe that after #5103 is merged this would be the correct PR to add for support in UI but I'm obviously biased toward my own work.

Also #5070 uses the existing extract system instead of creating a new one. That was my original approach but we opted to change into a standalone system because of the complexity working with atlases added. With the new API for atlases it might make sense to revert this back to the single system approach.

[alice-i-cecile]

@mwbryant can you mention @ManevilleF in the initial post so we can remember to include their work in the release notes?

[alice-i-cecile]

Nice example, a fairly direct (and well-debated) implementation, great docs. Let's merge this now: we can refine it with use.