Proportional scaling for the sprite's texture. #17258

silvestrpredko · 2025-01-09T13:32:52Z

Objective

Bevy sprite image mode lacks proportional scaling for the underlying texture. In many cases, it's required. For example, if it is desired to support a wide variety of screens with a single texture, it's okay to cut off some portion of the original texture.

Solution

I added scaling of the texture during the preparation step. To fill the sprite with the original texture, I scaled UV coordinates accordingly to the sprite size aspect ratio and texture size aspect ratio. To fit texture in a sprite the original quad is scaled and then the additional translation is applied to place the scaled quad properly.

Testing

For testing purposes could be used 2d/sprite_scale.rs. Also, I am thinking that it would be nice to have some tests for a crates/bevy_sprite/src/render/mod.rs:sprite_scale.

Showcase

This change introduces new texture scaling options for sprites that maintain aspect ratio: - Add `TextureScale` enum with `FillCenter`, `FillStart`, `FillEnd`, `FitCenter`, `FitStart`, and `FitEnd` modes - Extend `SpriteImageMode` with `ScaleMode` variant to support the new scaling options

Update `Cargo.toml` accordingly.

examples/2d/sprite_scale.rs

crates/bevy_sprite/src/texture_slice/computed_slices.rs

crates/bevy_sprite/src/sprite.rs

crates/bevy_sprite/src/render/mod.rs

alice-i-cecile · 2025-01-14T20:37:25Z

I like the feature, and the algorithms seem to be correct. Some mild style / docs / naming feedback, but do push back if you disagree with any of them.

Much of this feels like it belongs in bevy_image, but we should move that later. Being able to share this style of logic across windows/UI/decals/sprites would be great.

- Update SpriteImageMode::ScaleMode variant to Scale - Fix unreachable error messages to be more specific - Clean up sprite scale example code - Update documentation comments This change improves naming consistency and makes the sprite scaling API more intuitive while maintaining all existing functionality.

kristoff3r · 2025-01-17T14:54:38Z

Cargo.toml

+
+[package.metadata.example.sprite_scale]
+name = "Sprite Scale"
+description = "Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio"


Suggested change

description = "Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio"

description = "Shows how a sprite can be scaled into a rectangle while keeping the aspect ratio"

kristoff3r · 2025-01-17T14:57:14Z

examples/README.md

@@ -120,6 +120,7 @@ Example | Description
 [Sprite](../examples/2d/sprite.rs) | Renders a sprite
 [Sprite Animation](../examples/2d/sprite_animation.rs) | Animates a sprite in response to an event
 [Sprite Flipping](../examples/2d/sprite_flipping.rs) | Renders a sprite flipped along an axis
+[Sprite Scale](../examples/2d/sprite_scale.rs) | Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio


Suggested change

[Sprite Scale](../examples/2d/sprite_scale.rs) | Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio

[Sprite Scale](../examples/2d/sprite_scale.rs) | Shows how a sprite can be scaled into a rectangle while keeping the aspect ratio

kristoff3r · 2025-01-17T15:05:37Z

crates/bevy_sprite/src/render/mod.rs

+        ScalingMode::FitStart => {
+            if texture_ratio > quad_ratio {
+                // The quad is scaled to match the image ratio, and the quad translation is adjusted
+                // to start of the quad within the original quad size.
+                let scale = Vec2::new(1.0, quad_ratio / texture_ratio);
+                let new_quad = *quad_size * scale;
+                let offset = *quad_size - new_quad;
+                *quad_translation = Vec2::new(0.0, -offset.y);
+                *quad_size = new_quad;
+            } else {
+                let scale = Vec2::new(texture_ratio / quad_ratio, 1.0);
+                let new_quad = *quad_size * scale;
+                let offset = *quad_size - new_quad;
+                *quad_translation = Vec2::new(offset.x, 0.0);
+                *quad_size = new_quad;
+            }
+        }
+        ScalingMode::FitEnd => {
+            if texture_ratio > quad_ratio {
+                let scale = Vec2::new(1.0, quad_ratio / texture_ratio);
+                let new_quad = *quad_size * scale;
+                let offset = *quad_size - new_quad;
+                *quad_translation = Vec2::new(0.0, offset.y);
+                *quad_size = new_quad;
+            } else {
+                let scale = Vec2::new(texture_ratio / quad_ratio, 1.0);
+                let new_quad = *quad_size * scale;
+                let offset = *quad_size - new_quad;
+                *quad_translation = Vec2::new(-offset.x, 0.0);
+                *quad_size = new_quad;
+            }
+        }


These are identical except for 1 minus sign, and there are similar duplication in the other Start/End cases. On one hand it would be nice if the repetition could be factored out so e.g. FitEnd is just FitStart and set the minus. On the other hand this code is pretty simple and easy to read.

It might also become simpler if you match on (scaling_mode, quad_ratio > texture_ratio) since every case has that if inside.

I understand your concern about code duplication, and I agree that maintaining clarity is important. However, considering the minimal amount of code duplication we currently have, I believe it's reasonable to keep things as they are. The existing structure seems to be functioning well without introducing unnecessary complexity.

ickshonpe · 2025-01-17T23:53:41Z

crates/bevy_sprite/src/sprite.rs

+    /// Fill rect with a centered texture.
+    #[default]
+    FillCenter,
+    /// Scale the texture to fill the rect with a start of the texture,


Suggested change

/// Scale the texture to fill the rect with a start of the texture,

/// Scale the texture to fill the rect with the start of the texture,

This isn't really very clear about what the "start" of the texture is.

ickshonpe · 2025-01-17T23:54:06Z

crates/bevy_sprite/src/sprite.rs

+    /// Scale the texture to fill the rect with a start of the texture,
+    /// maintaining the aspect ratio.
+    FillStart,
+    /// Scale the texture to fill the rect with a end of the texture,


Suggested change

/// Scale the texture to fill the rect with a end of the texture,

/// Scale the texture to fill the rect with the end of the texture,

ickshonpe · 2025-01-17T23:55:02Z

crates/bevy_sprite/src/sprite.rs

+    FillEnd,
+    /// Scaling the texture will maintain the original aspect ratio
+    /// and ensure that the original texture fits entirely inside the rect.
+    /// At least one axis (X or Y) will fit exactly. The result is centered inside the rect.


Suggested change

/// At least one axis (X or Y) will fit exactly. The result is centered inside the rect.

/// At least one axis (x or y) will fit exactly. The result is centered inside the rect.

ickshonpe · 2025-01-17T23:55:15Z

crates/bevy_sprite/src/sprite.rs

+    FitCenter,
+    /// Scaling the texture will maintain the original aspect ratio
+    /// and ensure that the original texture fits entirely inside rect.
+    /// At least one axis (X or Y) will fit exactly.


Suggested change

/// At least one axis (X or Y) will fit exactly.

/// At least one axis (x or y) will fit exactly.

ickshonpe · 2025-01-17T23:55:26Z

crates/bevy_sprite/src/sprite.rs

+    FitStart,
+    /// Scaling the texture will maintain the original aspect ratio
+    /// and ensure that the original texture fits entirely inside rect.
+    /// At least one axis (X or Y) will fit exactly.


Suggested change

/// At least one axis (X or Y) will fit exactly.

/// At least one axis (x or y) will fit exactly.

ickshonpe · 2025-01-18T00:03:10Z

examples/2d/sprite_scale.rs

+
+    let square = asset_server.load("textures/slice_square_2.png");
+    let banner = asset_server.load("branding/banner.png");
+


There should be some example cases with a sprite from a texture atlas.

There should be some example cases with a sprite from a texture atlas.

It's important to note that the sprite sheet won't function correctly with scaling. Scaling completely overrides both the scaling and offset for the sprite, disregarding the rect.

I just updated the documentation to properly notify a user that it couldn't be used for a sprite sheet. For now, I don't know how to easily add additional scaling of the sprite sheet to the desired rect

ickshonpe · 2025-01-18T00:11:56Z

crates/bevy_ui/src/render/ui_texture_slice_pipeline.rs

@@ -813,7 +813,10 @@ fn compute_texture_slices(
            [[0., 0., 1., 1.], [0., 0., 1., 1.], [1., 1., rx, ry]]
        }
        SpriteImageMode::Auto => {
-            unreachable!("Slices should not be computed for ImageScaleMode::Stretch")
+            unreachable!("Slices should not be computed for SpriteImageMode::Stretch")


Suggested change

unreachable!("Slices should not be computed for SpriteImageMode::Stretch")

unreachable!("Slices can not be computed for SpriteImageMode::Auto")

ickshonpe · 2025-01-18T00:12:08Z

crates/bevy_ui/src/render/ui_texture_slice_pipeline.rs

+            unreachable!("Slices should not be computed for SpriteImageMode::Stretch")
+        }
+        SpriteImageMode::Scale(_) => {
+            unreachable!("Slices should not be computed for SpriteImageMode::Scale")


Suggested change

unreachable!("Slices should not be computed for SpriteImageMode::Scale")

unreachable!("Slices can not be computed for SpriteImageMode::Scale")

ickshonpe · 2025-01-18T00:36:28Z

crates/bevy_sprite/src/render/mod.rs

@@ -430,6 +431,7 @@ pub fn extract_sprites(
                    image_handle_id: sprite.image.id(),
                    anchor: sprite.anchor.as_vec(),
                    original_entity: Some(original_entity),
+                    scaling_mode: sprite.image_mode.scale(),


I'd prefer it if the sprite geometry was calculated during extraction rather than in prepare.

All the geometry logic happens in prepare for now. I am going with less resistance and fewer changes in the codebase to achieve the necessary functionality.

ickshonpe · 2025-01-18T00:41:26Z

crates/bevy_sprite/src/sprite.rs

+pub enum ScalingMode {
+    /// Scale the texture uniformly (maintain the texture's aspect ratio)
+    /// so that both dimensions (width and height) of the texture will be equal
+    /// to or larger than the corresponding dimension of the rect.


I guess you mean the rect field of the sprite? Needs to be clearer I think.

ickshonpe

This seems like a good start but looks like it still needs some work. It took me a while to understand the API and the docs aren't very clear. It probably doesn't make much that much impact but I'd like to see some sprite benchmarks as well.

Maybe there needs to be some sort of scale with overflow option as well, but I'm not really sure and that could be added in a followup.

ickshonpe · 2025-01-18T01:05:59Z

crates/bevy_sprite/src/sprite.rs

+/// Can be used in [`SpriteImageMode::Scale`].
+#[derive(Debug, Clone, Copy, PartialEq, Default, Reflect)]
+#[reflect(Debug)]
+pub enum ScalingMode {


I think maybe this type might be better split up into different two enums, one Fill/Fit and the other Start/Center/End.

I think maybe this type might be better split up into different two enums, one Fill/Fit and the other Start/Center/End.

I don't think that will be convenient for the end user. There are only six variants and no more are planned to add I guess. That led to the single field in Sprite that corresponds to scaling, adding one more enum adds more complexity.

Then SpriteImageMode::Scale needs to be a struct enum variant with two fields, one for Fill/Fit and the second one for direction Start/Center/End. In my humble opinion, it will not bring convenience for the current API.

…Fill, Fit)

silvestrpredko · 2025-01-20T20:02:12Z

I've been considering how to effectively apply scaling to a specific rectangle within a texture. My approach involves summing the scaling factors and then appropriately adjusting the offsets to accommodate the various scaling options. This way, I can ensure that the scaling is applied uniformly and maintains the correct alignment within the texture.

Please take a look. @alice-i-cecile @ickshonpe @BenjaminBrienen

Screen.Recording.2025-01-20.at.21.54.54.mov

silvestrpredko · 2025-01-23T17:57:39Z

@ickshonpe just a gentle ping to review the latest changes.

silvestrpredko force-pushed the silvestr/fit-sprite-to-quad branch from 68bd63f to 0e7ca6f Compare January 9, 2025 13:47

silvestrpredko added 3 commits January 9, 2025 21:00

Add sprite_scale.rs example to demonstrate the new functionality

baf755f

Update `Cargo.toml` accordingly.

Update examples/README.md

296174f

silvestrpredko force-pushed the silvestr/fit-sprite-to-quad branch from 49186a3 to 296174f Compare January 9, 2025 19:00

Merge branch 'main' into silvestr/fit-sprite-to-quad

22879d4

tbillington reviewed Jan 13, 2025

View reviewed changes

examples/2d/sprite_scale.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jan 14, 2025

View reviewed changes

crates/bevy_sprite/src/texture_slice/computed_slices.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jan 14, 2025

View reviewed changes

crates/bevy_sprite/src/sprite.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jan 14, 2025

View reviewed changes

crates/bevy_sprite/src/sprite.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jan 14, 2025

View reviewed changes

crates/bevy_sprite/src/render/mod.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jan 14, 2025

View reviewed changes

crates/bevy_sprite/src/render/mod.rs Outdated Show resolved Hide resolved

silvestrpredko and others added 2 commits January 15, 2025 16:19

Merge branch 'main' into silvestr/fit-sprite-to-quad

2672332

silvestrpredko requested review from alice-i-cecile and tbillington January 15, 2025 14:54

alice-i-cecile approved these changes Jan 15, 2025

View reviewed changes

alice-i-cecile requested review from BenjaminBrienen and removed request for tbillington January 15, 2025 18:36

kristoff3r approved these changes Jan 17, 2025

View reviewed changes

ickshonpe suggested changes Jan 17, 2025

View reviewed changes

ickshonpe suggested changes Jan 18, 2025

View reviewed changes

ickshonpe reviewed Jan 18, 2025

View reviewed changes

alice-i-cecile added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jan 18, 2025

Update documentation for the sprite scale

dbfa421

silvestrpredko requested a review from ickshonpe January 18, 2025 22:39

silvestrpredko and others added 2 commits January 19, 2025 00:47

Fix formatting

6fda406

Merge branch 'main' into silvestr/fit-sprite-to-quad

954fead

BenjaminBrienen added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jan 18, 2025

silvestrpredko and others added 3 commits January 20, 2025 21:50

Implement scaling for TextureAtlas or rect of the texture

bea348f

Add animated sprite sheet examples with various scaling modes (Auto, …

bf1b769

…Fill, Fit)

Merge branch 'main' into silvestr/fit-sprite-to-quad

a876f00

Improve naming for sprites created from a texture atlas

837e0f7

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

silvestrpredko and others added 2 commits January 24, 2025 19:20

Merge branch 'main' into silvestr/fit-sprite-to-quad

9a2329e

Remove few trailing zeros, make example more consistent

75176c8

alice-i-cecile added the M-Needs-Release-Note Work that should be called out in the blog due to impact label Jan 24, 2025

alice-i-cecile added this pull request to the merge queue Jan 24, 2025

Merged via the queue into bevyengine:main with commit deb135c Jan 24, 2025
33 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proportional scaling for the sprite's texture. #17258

Proportional scaling for the sprite's texture. #17258

silvestrpredko commented Jan 9, 2025

alice-i-cecile commented Jan 14, 2025 •

edited

Loading

kristoff3r Jan 17, 2025

kristoff3r Jan 17, 2025

kristoff3r Jan 17, 2025

silvestrpredko Jan 18, 2025

ickshonpe Jan 17, 2025

ickshonpe Jan 17, 2025

ickshonpe Jan 17, 2025

ickshonpe Jan 17, 2025

ickshonpe Jan 17, 2025

ickshonpe Jan 18, 2025

silvestrpredko Jan 18, 2025

silvestrpredko Jan 18, 2025

ickshonpe Jan 18, 2025

ickshonpe Jan 18, 2025

ickshonpe Jan 18, 2025

silvestrpredko Jan 18, 2025

ickshonpe Jan 18, 2025

ickshonpe left a comment •

edited

Loading

ickshonpe Jan 18, 2025

silvestrpredko Jan 18, 2025

silvestrpredko commented Jan 20, 2025

silvestrpredko commented Jan 23, 2025

	description = "Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio"
	description = "Shows how a sprite can be scaled into a rectangle while keeping the aspect ratio"

	[Sprite Scale](../examples/2d/sprite_scale.rs) \| Shows how a sprite could be scaled into a rectangle while keeping the aspect ratio
	[Sprite Scale](../examples/2d/sprite_scale.rs) \| Shows how a sprite can be scaled into a rectangle while keeping the aspect ratio

	/// Scale the texture to fill the rect with a start of the texture,
	/// Scale the texture to fill the rect with the start of the texture,

	/// At least one axis (X or Y) will fit exactly. The result is centered inside the rect.
	/// At least one axis (x or y) will fit exactly. The result is centered inside the rect.


		let square = asset_server.load("textures/slice_square_2.png");
		let banner = asset_server.load("branding/banner.png");

	unreachable!("Slices should not be computed for SpriteImageMode::Stretch")
	unreachable!("Slices can not be computed for SpriteImageMode::Auto")

Proportional scaling for the sprite's texture. #17258

Proportional scaling for the sprite's texture. #17258

Conversation

silvestrpredko commented Jan 9, 2025

Objective

Solution

Testing

Showcase

alice-i-cecile commented Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ickshonpe left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

silvestrpredko commented Jan 20, 2025

silvestrpredko commented Jan 23, 2025

alice-i-cecile commented Jan 14, 2025 •

edited

Loading

ickshonpe left a comment •

edited

Loading