# Cosmic-text vs parley

## The text stack

Text is a shockingly complex subject.
In order to get from "font" to "pixel on screen", a number of key steps must be performed.
These are roughly ordered, although the whole process is non-linear and earlier steps sometimes need to coordinate with later ones in an iterative process.

1. Font loading: getting the font files from the disk into a Rust struct that we can work with
- `bevy_asset`
- Note that system fonts should probably be mmap'd to avoid duplicating memory across processes.
- Linebender has been considering trying to get the ecosystem to standardise on something like:

        struct Font {
            // Raw file data of a font/collection
            data: Arc<dyn AsRef<[T]> + Send + Sync>,
            // Index of the font within a file containing a collection of fonts
            index: u32, 
        }

as a representation for fonts. Would this work for Bevy? (EDIT: looks like fontdb uses an almost indentical representation which is convenient)
2. Font enumeration: listing and working with the available system fonts
- Bevy 0.13: none
- Cosmic Text: [`font-db`](https://github.com/RazrFalcon/fontdb)
- Parley: [`fontique`](https://github.com/linebender/parley/tree/main/fontique)
- [`font-kit`](https://github.com/pcwalton/font-kit) is another prominent option in this space
3. Font selection: selecting a font to use based on the developer's request
- Bevy 0.13: none
- On some level, this is fundamentally Bevy's problem: it needs to play nice with loaded fonts, support fallbacks, [abstract over font variants](https://github.com/bevyengine/bevy/issues/9725)...
- However both `cosmic-text` and `parley` handle this already: we may be able to hook in
4. Font parsing: making sense of font data
- Bevy 0.13: [`abglyph`](https://docs.rs/ab_glyph/latest/ab_glyph/)
- Cosmic Text: [`ttf-parser`](https://github.com/RazrFalcon/ttf-parser)
- Parley: [`read-fonts`](https://crates.io/crates/read-fonts)
5. Text processing: choosing which string to display. This may involve localization, handling of control characters and so on.
- effectively ommitted, although [`fluent`](https://github.com/projectfluent/fluent-rs) is the de facto standard localization tool
6. Font shaping: combining characters via ligatures, subsituting characters based on context and more
- Bevy 0.13: ommitted
- Cosmic Text: [`rustybuzz`](https://github.com/RazrFalcon/rustybuzz)
- Parley: [`swash`](https://github.com/dfrg/swash)
- Bindings to C++ Harfbuzz (`rust_harfbuzz` or `harfbuzz_rs`) should also be considered.
7. Line breaking: determining where lines should be split based on word boundaries and the available space
- Bevy 0.13: [`glyph_brush_layout`](https://docs.rs/glyph_brush_layout/latest/glyph_brush_layout/)
- Cosmic Text: first-party code
- Parley: first-party code
8. Position adjustment: finalizing kerning and other positioning to ensure an aesthetic result
- Bevy 0.13: `glyph_brush_layout`
- Cosmic Text: first-party code
- Parley: first-party code
9. Rasterization: turning the procedural instructions in the font files into pixels for each character. Note that this can be replaced with other forms of rendering, such as SDF-based approaches
- Bevy 0.13: `ab_glyph`
- Cosmic Text: `swash`
- Parley: `swash`
- `skrifa` is a newer option here being developed to replace `freetype` in Chromium. It is a bit early, but will be able to be dropped in wherever swash is currently used.
- Makepad has some cool SDF code which could be adapted.
10. UI node layout: text elements must be positioned within their UI nodes and the UI nodes must be positioned relative to each other
- `taffy` and `bevy_ui`
11. Rendering: using a camera to turn the objects into pixels on the screen
- `bevy_ui` and `bevy_render`

For a more comprehensive and expert overview of this process, please read [Text Rendering Hates You](https://faultlore.com/blah/text-hates-you/).

Nicoburns has prepared an excellent [resource on text handling](https://docs.google.com/document/d/1jDX1KtqjmLHOAXGhzbgOzIin-YMpXGxRjJLcVLYnwX0/edit#heading=h.7wzc3121454) for Linebender: please take a look at this for additional

## Motivation

Bevy's current solution for font loading and rasterization is `ab_glyph`.
It functions, but doesn't handle complex features very well and there doesn't seem to be any appetite to expand its scope.
Notably missing:

- [variable weight fonts](https://fonts.google.com/knowledge/introducing_type/introducing_variable_fonts): these embed information about a continuous spectrum of weights (light to bold) and styles (italic, normal) into a single font file
- [bidirectional text support](https://www.unicode.org/faq/bidi.html): handles languages that are not written left-to-right, and what happens when you mix them
- [system font loading](https://practicaltypography.com/system-fonts.html): every user will have their own set of installed fonts. Using these can be valuable for reducing binary size (especially on the web), but they can also make reasonable fallbacks if something goes wrong or could be used to customize tools like the Bevy Editor
- text input and editing: this is notoriously hard once edge cases get involved, and we still don't have a functioning text input widget
- font shaping is completely ommitted, making it completely unsuitable for many non-Latin alphabet languages (and ugly even for those)

In addition, there are several outstanding bugs and limitations resulting in [ugly results](https://github.com/bevyengine/bevy/issues/2404).

Others in the Rust ecosystem have noticed these deficiencies, and created their own solutions to meet more sophisticated needs.
As [previously discussed](https://github.com/bevyengine/bevy/issues/7616), we should follow suit and migrate away from `ab_glyph`.

[`allsorts`](https://github.com/yeslogic/allsorts) is another competent, profesionally made alternative in this space, but is explicitly not suited to dynamic text handling as needed by Bevy and other GUI crates. As a result, it's not under consideration.

## User-Level Font API Requirements

To the extent possible, the Bevy APIs should not expose details of which font backend is being used. In an ideal world, one could switch between backends via a feature flag, however it may not be that easy in practice.

Many details of the font system can be hidden from Bevy users - for example, the specifics of glyph caching might be different for different backends. But there are several key APIs which will need to be exposed to users:

* Loading font collections that are stored as Bevy assets.
* Loading system fonts
* Rendering and layout (creating entities which produce rendered text, both for 2d bevy_ui and 3d world-space text).
* Text editing methods: picking & selection rects, possibly cursor movement (e.g. advance to next character, end of line, and so on).

We will need suitable abstractions for each of these.

## `cosmic-text`

[`cosmic-text`](https://github.com/pop-os/cosmic-text) is maintained by PopOS, a relatively new, commercial Linux distribution. It generally seems well-made, and they have expressed openness to feedback and collaboration.

There were difficulties during [previous](https://github.com/bevyengine/bevy/pull/8808) [attempts](https://github.com/bevyengine/bevy/pull/10193) to migrate: it does not support multiple fonts of different sizes within a line. This was a regression from Bevy's current feature set, which was deemed unacceptable.
The [PR to fix that](https://github.com/pop-os/cosmic-text/pull/235) was open since November 2023, but is now merged thanks to the help of Jeremy Soller, the lead `cosmic-text` maintainer once the importance was brought to his attention.

In addition to PopOS's own projects, `cosmic-text` is currently used by:

- [`iced`](https://crates.io/crates/iced)
- [`basalt`](https://crates.io/crates/basalt)
- [`zed`/`gpui`](https://github.com/zed-industries/zed)
- [`lapce`/`floem`](https://github.com/lapce/floem)

Additionally:
- Graphite (a Rust-based vector graphic editing tool) is considering using `cosmic-text` but [appears to be blocked](https://github.com/GraphiteEditor/Graphite/pull/1589) on the same issue as us.
- [`egui-cosmic-text`](https://crates.io/crates/egui_cosmic_text) is a working third-party extension to `egui` which uses `cosmic-text`
- [`bevy_cosmic_edit`](https://github.com/Dimchikkk/bevy_cosmic_edit) is a third-party integration of Bevy and `cosmic-text` to provide complex text input support

### Why we should use `cosmic-text`

- `cosmic-text` is used in production and seems to largely work well
- this is true both for System76's own projects and also for other major projects
- [`glyphon`](https://lib.rs/crates/glyphon) could be integrated as well, allowing us to replace `bevy_text`
- this might reduce our maintanence burden, but would also fragment Bevy's rendering
- backed by System76, which is a stable, open-source-first company
- `cosmic-text`'s lead maintainer, Jeremy Soller, has been very communicative and helpful

### Why we shouldn't use `cosmic-text`

- `cosmic-text` is using `rustybuzz`, which is [fighting an uphill battle](https://github.com/RazrFalcon/rustybuzz/issues/74) trying to keep up with the C code (`harfbuzz`) that is the de facto moving standard for font shaping

## Background on `parley`

[`parley`](https://crates.io/crates/parley) is a young project created as part of [Linebender](https://github.com/linebender), a UI group funded by Google Fonts, led by Raph Levien that is working to create [Xilem](https://github.com/linebender/xilem), a new GUI framework.

Linebender is explicitly collaborative (go [talk to them](https://xi.zulipchat.com/#narrow/stream/147921-general)), and working to create solid stand-alone crates that can be shared across the ecosystem.

`parley` is currently relatively young and not particularly thoroughly documented.

Several members of their team are well-known to the Bevy community: both Nico Burns and DJMcNab are notable Bevy alumni / collaborators.

`parley` is used by:

- [`blitz`](https://github.com/DioxusLabs/blitz), a lightweight, modular, extensible web renderer by the Dioxus team
- [`xilem`](https://github.com/linebender/xilem0), Linebender's flagship GUI project

### Why we should use `parley`

- `parley` is actively developed, by engineers that we know, trust and have strong relationships with
- `swash`'s approach to font shaping shows more promise and is likely to be more future-proof
- `parley` is backed by Google Fonts, and has a wealth of expertise to draw on
- `parley` is deliberately designed as a ecosystem building block and welcomes collaboration
- Linebender's experimental perfectionism is a good cultural fit for the Bevy project
- [`vello`](https://github.com/linebender/vello) is designed for use with `parley`, which would allow us to replace Bevy's UI rendering
- like with `glyphon`, this trades off control and uniformity for faster access to features and more collaboration

### Why we shouldn't use `parley`

- `parley` is young, and as a result is not particularly mature, stable, well-tested or well-documented
- Google has a history of suddenly killing projects
- Linebender (and Raph) have a desire for getting things just right, which can lead to some NIH and extended prototyping

## Recommendation

In summary, both `cosmic-text` and `parley` are reasonable options for Bevy's needs.
Both are featureful, well-maintained and open to collaboration on problems we encounter.

`cosmic-text` is a profesionally-made, pragmatic crate that's designed to get something decent working *today*.
`parley` is a principled, bubbling research project aiming to be the best possible text handling crate.

We've had difficulties integrating `cosmic-text` in the past, but with thanks to [some communication]((https://discord.com/channels/691052431525675048/1248074018612051978/1248311012411707392)) with the maintainers, that has been resolved.

`parley` is still young, but its rate of development is likely to outstrip Bevy's needs regardless: we're starting from a very poor foundation and so even buggy or limited functionality is dramatically better than what currently exists.

TBD!

## Migration strategy

TBD! Depends on the crate chosen.

## Relevant Issues

### Layout Bugs

* [#13063 `TextLayoutInfo` doesn't contain every processed glyph](https://github.com/bevyengine/bevy/issues/13063)
* [#13036 Words that are wider than its container are not wrapped](https://github.com/bevyengine/bevy/issues/13036)
* [#12319 Line Break doesn't clear trailing whitespace](https://github.com/bevyengine/bevy/issues/12319)
* [#12098 Ui Text does not word wrap if next "word" begins with a dot](https://github.com/bevyengine/bevy/issues/12098)
* [#12085 Text Overflow Bug](https://github.com/bevyengine/bevy/issues/12085)
* [#11589 fix text height calc](https://github.com/bevyengine/bevy/pull/11589)
* [#11542 wrapped text measure doesn't propagate up correctly](https://github.com/bevyengine/bevy/issues/11542)
* [#11375 Text is cut off in render_ui_to_texture example with high scale factors.](https://github.com/bevyengine/bevy/issues/11375)
* [#11359 JustifyText::Right behaves badly](https://github.com/bevyengine/bevy/issues/11359)
* [#8525 UI text is sometimes shifted to the left of where it should be](https://github.com/bevyengine/bevy/issues/8525)
* [#8518 Squeezed text nodes early text wrap](https://github.com/bevyengine/bevy/issues/8518)

### Rendering

* [#13010 Indic font rendering incorrectly](https://github.com/bevyengine/bevy/issues/13010)
* [#10720 Pixelated text font is blurry](https://github.com/bevyengine/bevy/issues/10720)
* [#2404 Replace the font renderer with one without the issues of anti-aliasing/hinting/subpixel/baseline](https://github.com/bevyengine/bevy/issues/2404)

### Feature Requests / Other

* [#12194 Support for WOFF2 compressed font files](https://github.com/bevyengine/bevy/issues/12194)
* [#11593 Add support for bitmap glyphs in OTF fonts](https://github.com/bevyengine/bevy/issues/11593)
* [#9944 Mixing Text and non-Text content in UIs](https://github.com/bevyengine/bevy/issues/9944)
* [#9761 `\t` tab escape sequence support in text](https://github.com/bevyengine/bevy/issues/9761)
* [#9725 Better abstraction for dealing with font styles and variants](https://github.com/bevyengine/bevy/issues/9725)
* [#9280 Add option to allow UI text to scale with parent.](https://github.com/bevyengine/bevy/issues/9280)
* [#9278 Text sections with the same font should be batched together](https://github.com/bevyengine/bevy/issues/9278)
* [#8998 Vertical Text](https://github.com/bevyengine/bevy/issues/8998)
* [#8781 Support line-height / letter-spacing in bevy_text](https://github.com/bevyengine/bevy/issues/8781)
* [#7714 Text should not store a flat list of sections](https://github.com/bevyengine/bevy/issues/7714)
* [#7616 Migrate to cosmic-text](https://github.com/bevyengine/bevy/issues/7616)
* [#6967 Changing the color of a TextSection triggers a redraw of the full Text](https://github.com/bevyengine/bevy/issues/6967)
* [#5667 Some unicode characters are not rendered correctly](https://github.com/bevyengine/bevy/issues/5667)
* [#1890 Text rasterization is based on world units instead of pixels](https://github.com/bevyengine/bevy/issues/1890)
* [#1325 Support using system fonts](https://github.com/bevyengine/bevy/issues/1325)