ImageMode::KeepAspect interacts in a confusing way with AlignItems

[bzm3r]

Bevy version

0.9

What user did

Programmer is working with bevy_ui ImageBundle and spawned a ImageBundle as a child of a NodeBundle. The NodeBundle is a fixed size, 100px by 100px. The image that they want to show is a pixel art image that is 64px width by 32px tall. They set the ImageMode explicitly to KeepAspect, which they assume to mean is the Aspect Ratio of the image, in this case 2x1 (and this is confirmed by the docs for ImageMode).

What went wrong

The image stretches to fit the 100px by 100px parent, it does not keep the aspect ratio.

Additional information

From the following Bevy Discord question: https://discord.com/channels/691052431525675048/1042098354735300658

[frederickjjoubert]

Thank you @bzm3r for creating this issue, I am said user :)

[ickshonpe]

Thought about this some more, and I don't think it's a bug, just confusing.

ImageMode::KeepAspect tells the UI to store the image size so it can draw the image with the correct aspect ratio.
The NodeBundle defaults are FlexDirection::Row and AlignItems::Stretch.
FlexDirection::Row means the x-axis is the main-axis and the y-axis is the cross-axis.
AlignItems::Stretch tells the UI to stretch items to fill the entire cross-axis of the Node.
The image height is 32 pixels and the Node's height (the cross-axis) is 100 pixels, so the image height is stretched to 100 pixels.
But with a height of 100 pixels, in order to preserve the aspect ratio the image would have to have a width of 200 pixels.
That won't fit inside the Node, so the image is drawn squashed into a 100x100 square.

To get the image to display correctly, change the flex-direction to FlexDirection::Column. Then the cross-axis will be the x-axis, the image width will be stretched to 100 pixels, and the height will be scaled according to the image's aspect ratio, 100 / 64 * 32 = 50, as desired.

[bzm3r]

@ickshonpe Any recommendations on what can be done in terms of documentation to make this less confusing?

My guess:

• the interaction between KeepAspect and AlignItems should be clarified?

Or do we have to go farther than documentation, and rework some of the API? How is this sort of interaction handled in other UI toolkits?

[ickshonpe]

I'm putting in a PR that deletes ImageMode. It's confusing and doesn't serve any purpose.

[ickshonpe]

Or do we have to go farther than documentation, and rework some of the API? How is this sort of interaction handled in other UI toolkits?

I think making image aspect ratios independent of flex should work, and be ergonomic and foolproof. Might be a bit hacky though. Implementing it now.

[bzm3r]

Closed by: #6674