Support texture atlases in CustomCursor::Image #17121

mgi388 · 2025-01-03T12:10:01Z

Objective

Bevy 0.15 added support for custom cursor images.
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 · 2025-01-03T12:17:11Z

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 · 2025-01-03T14:22:07Z

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 · 2025-01-06T09:07:24Z

@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.

eero-lehtinen · 2025-01-06T10:12:16Z

crates/bevy_winit/src/cursor.rs

        _ => None,
+    };
+
+    let image_data = image_data?;


I would like to keep a fast path when there is no transformations and just return the data.

Makes sense, I think I can adjust this.

Done. There are technically some cases where texture atlas might be the full image rect, but I decided to not let those follow the fast path since it's not obvious to me how to check that properly.

crates/bevy_winit/Cargo.toml

# Objective - Allow other crates to use `TextureAtlas` and friends without needing to depend on `bevy_sprite`. - Specifically, this allows adding `TextureAtlas` support to custom cursors in #17121 by allowing `bevy_winit` to depend on `bevy_image` instead of `bevy_sprite` which is a [non-starter]. [non-starter]: #17121 (comment) ## Solution - Move `TextureAtlas`, `TextureAtlasBuilder`, `TextureAtlasSources`, `TextureAtlasLayout` and `DynamicTextureAtlasBuilder` into `bevy_image`. - Add a new plugin to `bevy_image` named `TextureAtlasPlugin` which allows us to register `TextureAtlas` and `TextureAtlasLayout` which was previously done in `SpritePlugin`. Since `SpritePlugin` did the registration previously, we just need to make it add `TextureAtlasPlugin`. ## Testing - CI builds it. - I also ran multiple examples which hopefully covered any issues: ``` $ cargo run --example sprite $ cargo run --example text $ cargo run --example ui_texture_atlas $ cargo run --example sprite_animation $ cargo run --example sprite_sheet $ cargo run --example sprite_picking ``` --- ## Migration Guide The following types have been moved from `bevy_sprite` to `bevy_image`: `TextureAtlas`, `TextureAtlasBuilder`, `TextureAtlasSources`, `TextureAtlasLayout` and `DynamicTextureAtlasBuilder`. If you are using the `bevy` crate, and were importing these types directly (e.g. before `use bevy::sprite::TextureAtlas`), be sure to update your import paths (e.g. after `use bevy::image::TextureAtlas`) If you are using the `bevy` prelude to import these types (e.g. `use bevy::prelude::*`), you don't need to change anything. If you are using the `bevy_sprite` subcrate, be sure to add `bevy_image` as a dependency if you do not already have it, and be sure to update your import paths.

mgi388 · 2025-01-08T03:04:16Z

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 · 2025-01-08T03:06:54Z

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 · 2025-01-08T04:08:05Z

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 · 2025-01-08T04:14:53Z

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

mgi388 force-pushed the custom-cursor-image-texture-atlas branch from c6ba500 to 2f77a85 Compare January 6, 2025 00:31

eero-lehtinen suggested changes Jan 6, 2025

View reviewed changes

crates/bevy_winit/Cargo.toml Outdated Show resolved Hide resolved

mgi388 mentioned this pull request Jan 7, 2025

Move TextureAtlas and friends into bevy_image #17219

Merged

BenjaminBrienen added S-Blocked This cannot move forward until something else changes and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 7, 2025

mgi388 added 9 commits January 8, 2025 09:21

Support texture atlases in CustomCursor::Image

f1064b5

update examples

081b6cb

add missing assets

1990e60

add tests for RGBA8 branch of image_to_rgba_pixels

95d33e5

fix RGBA32Float branch of image_to_rgba_pixels with tests

79c2743

refactor image_to_rgba_pixels

77f7d78

fix bad merge (forgot to press save...)

6de87b9

don't depend on bevy_sprite

86f0729

support fast path when no image transforms, add mod+plugin

569260c

mgi388 force-pushed the custom-cursor-image-texture-atlas branch from 00a36d4 to 569260c Compare January 8, 2025 02:33

mgi388 added 2 commits January 8, 2025 13:35

inline width and height

ade36b2

lint

a83db48

BenjaminBrienen added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Blocked This cannot move forward until something else changes labels Jan 8, 2025

mgi388 requested review from BenjaminBrienen, alice-i-cecile and eero-lehtinen January 8, 2025 03:04

BenjaminBrienen approved these changes Jan 8, 2025

View reviewed changes

alice-i-cecile added this to the 0.16 milestone Jan 8, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support texture atlases in CustomCursor::Image #17121

Support texture atlases in CustomCursor::Image #17121

mgi388 commented Jan 3, 2025 •

edited

Loading

mgi388 commented Jan 3, 2025

LikeLakers2 commented Jan 3, 2025 •

edited

Loading

mgi388 commented Jan 6, 2025

eero-lehtinen left a comment •

edited

Loading

eero-lehtinen Jan 6, 2025 •

edited

Loading

mgi388 Jan 6, 2025

mgi388 Jan 8, 2025

mgi388 commented Jan 8, 2025

BenjaminBrienen commented Jan 8, 2025

BenjaminBrienen left a comment

mgi388 commented Jan 8, 2025

BenjaminBrienen commented Jan 8, 2025

Support texture atlases in CustomCursor::Image #17121

Are you sure you want to change the base?

Support texture atlases in CustomCursor::Image #17121

Conversation

mgi388 commented Jan 3, 2025 • edited Loading

Objective

Solution

Testing

Showcase

Migration Guide

References

mgi388 commented Jan 3, 2025

LikeLakers2 commented Jan 3, 2025 • edited Loading

mgi388 commented Jan 6, 2025

eero-lehtinen left a comment • edited Loading

Choose a reason for hiding this comment

eero-lehtinen Jan 6, 2025 • edited Loading

Choose a reason for hiding this comment

mgi388 Jan 6, 2025

Choose a reason for hiding this comment

mgi388 Jan 8, 2025

Choose a reason for hiding this comment

mgi388 commented Jan 8, 2025

BenjaminBrienen commented Jan 8, 2025

BenjaminBrienen left a comment

Choose a reason for hiding this comment

mgi388 commented Jan 8, 2025

BenjaminBrienen commented Jan 8, 2025

mgi388 commented Jan 3, 2025 •

edited

Loading

LikeLakers2 commented Jan 3, 2025 •

edited

Loading

eero-lehtinen left a comment •

edited

Loading

eero-lehtinen Jan 6, 2025 •

edited

Loading