UI content transform

[ickshonpe]

Objective

Allow limited rotation and flipping of a UI node's content without modifying its Transform component or breaking the UI layout and clipping.

Fixes #8998

Solution

Generalization of #6688.

UI nodes have a UiContentTransform component, with identity, flip_x, flip_y, rotate_left and rotate_right methods which you can compose to get whatever orientation you want.

Notes:

• The API is a bit mathy and might be quite counterintuitive for some users, particularly when working with text.

• I really hate the naming scheme using cardinal directions for the variants of UiContentTransform. There is a long discussion about this at UI Image Rotation #6688. All the other ideas were terrible too.

• Probably still got a few bugs but it all seems to work mostly. Needs some refactoring and more doc comments.

• In the original design widgets didn't need to be aware of the content transform and layout handled everything. But I realised it wasn't going to work without changes to Taffy (probably coming in Taffy 0.4).

• You can still use the regular Transform component to rotate and scale UI elements as before.

• This is a relatively large PR but it doesn't make too many changes, most of the code is examples and helper methods.

---

Changelog

• Removed the flip_x and flip_y from the UiImage and UiTextureAtlasImage components.
• Added the UiContentTransform enum component.
• Added ui_image_symmetries and text_transformed examples.
• Implemented From<UiContentOrientation> for Mat4
• Added a content_transform: UiContentTransform field to all UI node bundles.

Migration Guide

The flip_x and flip_y fields have been removed from the UiImage and UiTextureAtlasImage components. The flip_x() and flip_y() methods of the UiContentTransform component now control image flipping.

[alice-i-cecile]

I prefer this to the linked PR.

[alice-i-cecile]

I wish we could call this Orientation or something, but it's a) currently UI specific and b) also includes flipping. Hmm.

[mogambro]

What about UiOrientation for now then? And if we get to a point where it can be more generalized, we rename it.

UiOrientation may not sound better than UiContentTransform but I personally prefer Orientation to Transform because Orientation has more meaning and is less abstract (After all, in the end about everything we do in CS is transforming some input to some output ;))

Maybe UiContentOrientation or ContentOrientation?

[nicoburns]

This seems like a good direction.

@ickshonpe A few questions:

• Does this work with container nodes (to transform the entire sub-tree)?
• How does this interact with layout (CSS transforms for example happen after layout - so layout is entirely unaffected)?
• What is the difference between this and a regular Transform?

[ickshonpe]

This seems like a good direction.

@ickshonpe A few questions:

• Does this work with container nodes (to transform the entire sub-tree)?

No that changes are only applied to single nodes. I'm not keen on allowing transformations of sub-trees. I'd prefer to simulate it by spawning a second layout tree with a transformation that is applied globally to all nodes in the tree.

• How does this interact with layout (CSS transforms for example happen after layout - so layout is entirely unaffected)?

The layout is unaffected, only the content within the node is transformed respecting the node's boundaries.

• What is the difference between this and a regular Transform?

The regular Transform doesn't respect the layout. This adjusts the size of the content after the transformation so it still fits the node.

The regular Transform allows arbitrary scaling and rotation of content, but it's not very useful usually as it breaks the layout and clipping results in a distorted mess.

[upsuper]

I saw that this PR is said to fix #8998 which is about vertical text support like CSS's writing-mode and text-orientation, but the screenshots included in the description don't really seem to demonstrate such support. Need of vertical text mainly originates from CJK scripts, in which the orientation of individual characters are usually unchanged, but they are laid in different direction as shown below.

However, all the examples shown in the PR description is about rotating the whole text piece, which can't really be called vertical text support. If the only thing this PR does is to support such rotation, I would suggest either it should not mark that issue as fixed, or that issue should be updated to a narrower scope. But maybe I'm missing something?

[ickshonpe]

However, all the examples shown in the PR description is about rotating the whole text piece, which can't really be called vertical text support. If the only thing this PR does is to support such rotation, I would suggest either it should not mark that issue as fixed, or that issue should be updated to a narrower scope. But maybe I'm missing something?

Yeah I should I have been clearer maybe, the vertical text support I'm talking about here is for tasks like labelling the vertical axis of a graph. This PR is mainly about changing the orientation of content and negotiating with Taffy to find the ideal size to fit the reorientated content into the UI node layout. It's meant to be content agnostic as far as possible.

The layout of glyphs into rows for languages that can be written vertically like Japanese is something separate and would be handled by bevy_text. @tjamaan has been working on improving bevy's bidi support I think, might have an opinon.

[upsuper]

In that case, would it be better removing the "Fixes #8998" from this PR description? Or if the intention of #8998 is actually just this, then removing the mention of writing mode and text orientation from that issue to avoid causing confusion?

[BenjaminBrienen]

triage: still up for adoption with some nasty merge conflicts