Migrate to `cosmic-text` #8808

tigregalis · 2023-06-10T15:40:26Z

Objective

Solution

Migrate to cosmic_text, simplifying and enhancing Bevy's text rendering implementation
Provide APIs that take advantage of the newly available features

Changelog

Changed

TextStyle::font is no longer a Handle, but a FontRef. From<Handle> is implemented for FontRef, so in your existing code, you can call .into() on the Handle to convert it into a FontRef.

The definition of the font size has changed with the migration to cosmic text. The behavior is now consistent with other platforms (e.g. the web), where the font size in pixels measures the height of the font (the distance between the top of the highest ascender and the bottom of the lowest descender). Font sizes in your app need to be rescaled to approximately 1.2x smaller; for example, if you were using a font size of 60.0, you should now use a font size of 50.0.

Added

You can now query loaded fonts by family and style using FontQuery. From<FontQuery> is implemented for FontRef, so you can call .into() on the FontQuery to convert it into a FontRef.

You can now load system fonts using TextPipeline::load_system_fonts. These fonts can then be queried by a FontQuery.

Emojis and bidirectional text are now supported, provided fonts have been loaded that support them (for example, via TextPipeline::load_system_fonts).

Check out the new system_fonts example in the Bevy repo.

Migration Guide

The definition of the font size has changed with the migration to cosmic text. Font sizes in your app need to be rescaled to approximately 1.2x smaller; for example, if you were using a font size of 60.0, you should now use a font size of 50.0..

TextStyle::font is no longer a Handle, but a FontRef. In each TextStyle, call .into() on the Handle to convert it into a FontRef.

Notes

To do

This is a draft, and there's still quite a bit of work to do. I've (liberally) peppered the code with TODOs but here is a collection:

At a high level this is what was done and still (perhaps) needs doing:

Future Work

Preferably done now:

(tidy up) text sections renamed to text spans (since we're making breaking changes already)
(tidy up) simplify implementation based on upstream changes or issues addressed, when landed:
- Replace per-node measure functions with a single measure function + per-node context DioxusLabs/taffy#490 (remove Mutex used for TextMeasure purposes)
- Upgrade to fontdb 0.14 pop-os/cosmic-text#125 / bump fontdb to 0.14.1 pop-os/cosmic-text#128 (take ID when loading font)
- Allow creating a Buffer with no FontSystem pop-os/cosmic-text#127 (cache buffer / store buffer(s) on Text component)
- Replace use of str::Lines with unicode-bidi-based iterator pop-os/cosmic-text#124 (remove own BidiParagraphs iterator)
- Incorrect alignment when using Wrap::None pop-os/cosmic-text#130 / Fix alignment when using Wrap::None pop-os/cosmic-text#131
- don't reimplement determining locale (no issue/PR yet)
- Let a Buffer figure out its height during set_size pop-os/cosmic-text#70 (simpler buffer size calculation)
(feature) support specifying the line height

For future PRs, or should any of these be done in this PR?

(feature) text spans as entities
(feature) editor support
(feature) editor widget
(feature) configurable font fallback, provided Allow setting the fallback fonts pop-os/cosmic-text#126
(feature) inline widgets, provided Request: The ability to layout arbitrary boxes in line with text pop-os/cosmic-text#80
(fix) will we ever address window-independent scaling: Support window independent UI scaling #5621

Guidance needed

I've tried to "slip under the radar" as much as possible when it comes to the API, but in some cases user-facing API changes were unavoidable. Please consider and advise how best to design and expose these APIs.

Of particular note is the new FontQuery, and TextPipeline::load_system_fonts (which probably needs to run in a parallel async task).

We also need to consider re-exports.

As far as implementation goes:

I'm not so confident on the Arc/Mutex I've introduced and how best to handle errors there.
Loading fonts are currently "infallible": ab_glyph used to parse the font when it loaded it into memory as a FontVec, but fontdb (via cosmic_text) doesn't (parsing is a separate step, and we'd have to introduce ttf-parser), so currently font data is simply a Vec<u8>.
I've no idea how to handle Reflect.

I think that about covers it. Have at it.

crates/bevy_text/src/font_atlas_set.rs

crates/bevy_text/src/text.rs

alice-i-cecile · 2023-06-10T18:56:26Z

crates/bevy_text/src/text.rs

+}
+
+#[derive(Clone, Debug)]
+pub struct FontQuery {


Definitely needs doc strings. I also think we should really try and avoid the Query name if possible, since this doesn't seem to use bevy_ecs::Query, which is going to be a source of a lot of confusion.

Looking at this more, I think that "system font" is probably a better way to describe this functionality?

SystemFont doesn't quite capture the idea as you can actually use a FontQuery to refer to a font you loaded as an asset (since it's always loaded into the Database), which I've confirmed works (but I probably need to test for edge cases). *Query better captures the idea, and it's the terminology used by fontdb, but FontSearch could maybe work.

examples/ui/system_fonts.rs

crates/bevy_text/src/font_atlas.rs

TotalKrill · 2023-10-19T16:24:43Z

was this abandoned, and in that case, how would anyone pick this up?

alice-i-cecile · 2023-10-19T17:42:01Z

Not fully abandoned, but like I said in this comment, the author has been busy and would appreciate some assistance.

If I was tackling this, I would personally start by creating a branch, and attempting to recreate these changes with the latest versions of both Bevy and cosmic-text. Given the level of merge conflicts, I think that doing so manually, rather than attempting to rebase these commits is likely going to be happier.

Once you have something to show (it doesn't need to be complete), open up a new PR and link this one in the description.

TotalKrill · 2023-10-19T22:03:14Z

Okay so basically, I took and did the quickest way I could figure out, and that was to just squash all the commits by @tigregalis and then merge that one large commit into a new branch, and then do a PR.

I probably messed something up, but at least I got the examples/ui/text.rs to run, and show similar text.

You can see that PR here: #10193

alice-i-cecile · 2023-10-19T23:05:38Z

Adopted in #10193. Please follow (and chime in) there!

# Objective - Enables support for `Display::Block` - Enables support for `Overflow::Hidden` - Allows for cleaner integration with text, image and other content layout. - Unblocks #8104 - Unlocks the possibility of Bevy creating a custom layout tree over which Taffy operates. - Enables #8808 / #10193 to remove a Mutex around the font system. ## Todo - [x] ~Fix rendering of text/images to account for padding/border on nodes (should size/position to content box rather than border box)~ In order get this into a mergeable state this PR instead zeroes out padding/border when syncing leaf node styles into Taffy to preserve the existing behaviour. #6879 can be fixed in a followup PR. ## Solution - Update the version of Taffy - Update code to work with the new version Note: Taffy 0.4 has not yet been released. This PR is being created in advance of the release to ensure that there are no blockers to upgrading once the release occurs. --- ## Changelog - Bevy now supports the `Display::Block` and `Overflow::Hidden` styles.

# Replace ab_glyph with the more capable cosmic-text Fixes #7616. Cosmic-text is a more mature text-rendering library that handles scripts and ligatures better than ab_glyph, it can also handle system fonts which can be implemented in bevy in the future Rebase of #8808 ## Changelog Replaces text renderer ab_glyph with cosmic-text The definition of the font size has changed with the migration to cosmic text. The behavior is now consistent with other platforms (e.g. the web), where the font size in pixels measures the height of the font (the distance between the top of the highest ascender and the bottom of the lowest descender). Font sizes in your app need to be rescaled to approximately 1.2x smaller; for example, if you were using a font size of 60.0, you should now use a font size of 50.0. ## Migration guide - `Text2dBounds` has been replaced with `TextBounds`, and it now accepts `Option`s to the bounds, instead of using `f32::INFINITY` to inidicate lack of bounds - Textsizes should be changed, dividing the current size with 1.2 will result in the same size as before. - `TextSettings` struct is removed - Feature `subpixel_alignment` has been removed since cosmic-text already does this automatically - TextBundles and things rendering texts requires the `CosmicBuffer` Component on them as well ## Suggested followups: - TextPipeline: reconstruct byte indices for keeping track of eventual cursors in text input - TextPipeline: (future work) split text entities into section entities - TextPipeline: (future work) text editing - Support line height as an option. Unitless `1.2` is the default used in browsers (1.2x font size). - Support System Fonts and font families - Example showing of animated text styles. Eg. throbbing hyperlinks --------- Co-authored-by: tigregalis <anak.harimau@gmail.com> Co-authored-by: Nico Burns <nico@nicoburns.com> Co-authored-by: sam edelsten <samedelsten1@gmail.com> Co-authored-by: Dimchikkk <velo.app1@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com>

# Replace ab_glyph with the more capable cosmic-text Fixes bevyengine#7616. Cosmic-text is a more mature text-rendering library that handles scripts and ligatures better than ab_glyph, it can also handle system fonts which can be implemented in bevy in the future Rebase of bevyengine#8808 ## Changelog Replaces text renderer ab_glyph with cosmic-text The definition of the font size has changed with the migration to cosmic text. The behavior is now consistent with other platforms (e.g. the web), where the font size in pixels measures the height of the font (the distance between the top of the highest ascender and the bottom of the lowest descender). Font sizes in your app need to be rescaled to approximately 1.2x smaller; for example, if you were using a font size of 60.0, you should now use a font size of 50.0. ## Migration guide - `Text2dBounds` has been replaced with `TextBounds`, and it now accepts `Option`s to the bounds, instead of using `f32::INFINITY` to inidicate lack of bounds - Textsizes should be changed, dividing the current size with 1.2 will result in the same size as before. - `TextSettings` struct is removed - Feature `subpixel_alignment` has been removed since cosmic-text already does this automatically - TextBundles and things rendering texts requires the `CosmicBuffer` Component on them as well ## Suggested followups: - TextPipeline: reconstruct byte indices for keeping track of eventual cursors in text input - TextPipeline: (future work) split text entities into section entities - TextPipeline: (future work) text editing - Support line height as an option. Unitless `1.2` is the default used in browsers (1.2x font size). - Support System Fonts and font families - Example showing of animated text styles. Eg. throbbing hyperlinks --------- Co-authored-by: tigregalis <anak.harimau@gmail.com> Co-authored-by: Nico Burns <nico@nicoburns.com> Co-authored-by: sam edelsten <samedelsten1@gmail.com> Co-authored-by: Dimchikkk <velo.app1@gmail.com> Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com>

tigregalis added 24 commits June 10, 2023 21:20

make text update lazier in tonemapping example

c2b47f7

implemented cosmic_text side-by-side

c6c49aa

make text update lazier in tonemapping ex. try 2

643fc6a

introduce BidiParagraphs iterator

9118acc

update FontAtlasSet iter, has_glyph methods

fbba4c7

collect positioned glyphs rather than push vec

7036d05

remove unnecessary position calcs

6c5b506

implement horizontal text alignment

b759c85

split up TextPipeline::queue_text

aa37e0d

implement text measure

1cf10ae

remove old implementation, dependencies

ff2aeab

tidy up

79632d6

fix tonemapping example layout bug

85063cf

update todos

86a90b3

implement font query

da8cb97

add system fonts example

297a7a5

promote GlyphAtlasInfoNew to sole GlyphAtlasInfo

02e317e

fix crash from dropped Handle<FontAtlasSet>

8694d48

expand FontRef-related APIs

a424110

improve system_fonts example

ff1590a

update examples with FontRef not Handle

193611d

fix lines not breaking when sections end with \n

cbfbfdf

enhance system_fonts example

4b1f6f1

fix extra line bug

d8b1afe

alice-i-cecile added C-Enhancement A new feature C-Dependencies A change to the crates that Bevy depends on A-UI Graphical user interfaces, styles, layouts, and widgets C-Breaking-Change A breaking change to Bevy's public API that needs to be noted in a migration guide labels Jun 10, 2023

alice-i-cecile added this to the 0.12 milestone Jun 10, 2023

alice-i-cecile reviewed Jun 10, 2023

View reviewed changes

crates/bevy_text/src/font_atlas_set.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Jun 10, 2023

View reviewed changes

crates/bevy_text/src/text.rs Show resolved Hide resolved

alice-i-cecile reviewed Jun 10, 2023

View reviewed changes

examples/ui/system_fonts.rs Outdated Show resolved Hide resolved

alice-i-cecile added D-Complex Quite challenging from either a design or technical perspective. Ask for help! X-Controversial There is active debate or serious implications around merging this PR labels Jun 10, 2023

alice-i-cecile reviewed Jun 10, 2023

View reviewed changes

crates/bevy_text/src/font_atlas.rs Outdated Show resolved Hide resolved

tigregalis added 8 commits June 11, 2023 09:53

replace (i32, i32, u32, u32) with Placement

ce44ab4

extract (glyph_index, placement) to *Location

ab8df89

replace Placement with IVec2 offset

117b6c3

extract and use acquire_font_system

8696b4e

reorganize code and add more docs

ab56e13

renamed cosmic text re-exports

b25d8e7

incorporate docs suggestions

da0a81f

fix doctests

0e59b11

nicopap self-requested a review July 27, 2023 08:59

nicoburns mentioned this pull request Aug 13, 2023

Editor-Ready UI #254

Open

jackpot51 mentioned this pull request Sep 7, 2023

Identify projects using cosmic-text pop-os/cosmic-text#177

Open

JMS55 removed this from the 0.12 milestone Sep 28, 2023

alice-i-cecile added the S-Adopt-Me The original PR author has no intent to complete this work. Pick me up! label Oct 19, 2023

alice-i-cecile mentioned this pull request Oct 19, 2023

Migrate to cosmic-text #7616

Closed

TotalKrill mentioned this pull request Oct 19, 2023

Cosmic text #10193

Merged

alice-i-cecile closed this Oct 19, 2023

nicoburns mentioned this pull request Nov 23, 2023

Upgrade to Taffy 0.4 #10690

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate to `cosmic-text` #8808

Migrate to `cosmic-text` #8808

tigregalis commented Jun 10, 2023 •

edited

Loading

alice-i-cecile Jun 10, 2023

alice-i-cecile Jun 10, 2023

tigregalis Jun 11, 2023 •

edited

Loading

TotalKrill commented Oct 19, 2023

alice-i-cecile commented Oct 19, 2023

TotalKrill commented Oct 19, 2023

alice-i-cecile commented Oct 19, 2023

Migrate to cosmic-text #8808

Migrate to cosmic-text #8808

Conversation

tigregalis commented Jun 10, 2023 • edited Loading

Objective

Solution

Changelog

Changed

Added

Migration Guide

Notes

To do

Future Work

Guidance needed

alice-i-cecile Jun 10, 2023

Choose a reason for hiding this comment

alice-i-cecile Jun 10, 2023

Choose a reason for hiding this comment

tigregalis Jun 11, 2023 • edited Loading

Choose a reason for hiding this comment

TotalKrill commented Oct 19, 2023

alice-i-cecile commented Oct 19, 2023

TotalKrill commented Oct 19, 2023

alice-i-cecile commented Oct 19, 2023

Migrate to `cosmic-text` #8808

Migrate to `cosmic-text` #8808

tigregalis commented Jun 10, 2023 •

edited

Loading

tigregalis Jun 11, 2023 •

edited

Loading