Support texture atlases in CustomCursor::Image

[mgi388]

Objective

• Bevy 0.15 added support for custom cursor images in Add custom cursors #14284.
• However, to do animated cursors using the initial support shipped in 0.15 means you'd have to animate the Handle<Image>: You can't use a TextureAtlas like you can with sprites and UI images.
• For my use case, my cursors are spritesheets. To animate them, I'd have to break them down into multiple Image assets, but that seems less than ideal.

Solution

• Allow users to specify a TextureAtlas field when creating a custom cursor image.
• To create parity with Bevy's TextureAtlas support on Sprites and ImageNodes, this also allows users to specify rect, flip_x and flip_y. In fact, for my own use case, I need to flip_y.

Testing

• I added unit tests for calculate_effective_rect and extract_and_transform_rgba_pixels.
• I added a brand new example for custom cursor images. It has controls to toggle fields on and off. I opted to add a new example because the existing cursor example (window_settings) would be far too messy for showcasing these custom cursor features (I did start down that path but decided to stop and make a brand new example).
• The new example uses a Kenny cursor icon sprite sheet. I included the licence even though it's not required (and it's CC0).
• I decided to make the example just loop through all cursor icons for its animation even though it's not a realistic in-game animation sequence.
• I ran the PNG through https://tinypng.com. Looks like it's about 35KB.
• I'm open to adjusting the example spritesheet if required, but if it's fine as is, great.

---

Showcase

custom-cursor-001.mov

Migration Guide

The CustomCursor::Image enum variant has some new fields. Update your code to set them.

Before:

CustomCursor::Image {
    handle: asset_server.load("branding/icon.png"),
    hotspot: (128, 128),
}

After:

CustomCursor::Image {
    handle: asset_server.load("branding/icon.png"),
    texture_atlas: None,
    flip_x: false,
    flip_y: false,
    rect: None,
    hotspot: (128, 128),
}

References

• Feature request originally raised in Discord.

[mgi388]

Another showcase video. This is a more realistic in-game animated cursor. The pointer animates every 5s (blink and you'll miss it):

Screen.Recording.2025-01-03.at.11.15.03.PM.mov

[LikeLakers2]

The new example uses a Kenny cursor icon sprite sheet. I included the licence even though it's not required (and it's CC0).

First off: Thank you for attributing to Kenney. He's a cool person. :D

Second off: I don't see any assets added by this PR? All the files touched are code, except for examples/README.md and a Cargo.toml.

[mgi388]

@eero-lehtinen 👋 would you be interested in reviewing this PR for texture atlas support on custom cursor images?

[eero-lehtinen]

Seems fine to me except for a couple of things.

[mgi388]

Changes (also see latest commits):

• Don't depend on bevy_sprite.
• Follow fast path in the case there is no image transform to do.
• Add custom_cursor.rs, CustomCursorPlugin and move most of the custom cursor code to it. This has the nice benefits of a) allowing us to encapsulate the registration of TextureAtlasPlugin and b) remove some #[cfg(feature = "custom_cursor")]. There's still room to move the CustomCursor type, but I wanted to reduce the diff in this PR so it's still in cursor.rs.

[BenjaminBrienen]

I don't have time to do a full code review, but I'll run the examples when I get to my laptop

[BenjaminBrienen]

custom_cursor_image works. window_settings actually seems broken here and on main.

[mgi388]

custom_cursor_image works. window_settings actually seems broken here and on main.

@BenjaminBrienen how so? Seems to work for me. You need to left/right click to cycle the cursor icon if you didn't already do that.

[BenjaminBrienen]

custom_cursor_image works. window_settings actually seems broken here and on main.

@BenjaminBrienen how so? Seems to work for me. You need to left/right click to cycle the cursor icon if you didn't already do that.

See #17227

[eero-lehtinen]

Nice tests, looks good.