Implements text align and optional width for VelloTextSection (#137)

RobertBrewitz · web-flow · commit dc313c0631f7 · 2025-04-03T18:19:38.000Z
Should close one of or both of the following issues: - #50 - #51 Updates the example to demonstrate `VelloTextAlign::Justified` as well. ![image](https://github.com/user-attachments/assets/f14365e0-1c15-4bcf-b583-f2c869bee27a)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,8 @@ This release supports Bevy version 0.15 and has an [MSRV][] of 1.85.
 - A `parley::FontContext` and `parley::LayoutContext` has been added in a lazy load multi threaded capacity.
 - Replaces `Rubik-Medium.ttf` from the `text` example with variable font `RobotoFlex-VariableFont_GRAD,XOPQ,XTRA,YOPQ,YTAS,YTDE,YTFI,YTLC,YTUC,opsz,slnt,wdth,wght.ttf`.
 - Updates the `text` example with an interactive, keyboard controlled, variable font example.
+- Adds `text_align` and `width` to `VelloTextSection` for controlling text alignment and width.
+- Adds `VelloTextAlign` enum for controlling text alignment.
 
 ## [0.7.1] - 2025-03-12
 
diff --git a/examples/text/src/main.rs b/examples/text/src/main.rs
@@ -3,7 +3,11 @@ use bevy::{
     prelude::*,
     ui::ContentSize,
 };
-use bevy_vello::{VelloPlugin, prelude::*, text::VelloTextAnchor};
+use bevy_vello::{
+    VelloPlugin,
+    prelude::*,
+    text::{VelloTextAlign, VelloTextAnchor},
+};
 
 const EMBEDDED_FONT: &str = "embedded://text/assets/RobotoFlex-VariableFont_GRAD,XOPQ,XTRA,YOPQ,YTAS,YTDE,YTFI,YTLC,YTUC,opsz,slnt,wdth,wght.ttf";
 
@@ -32,35 +36,61 @@ fn setup_camera(mut commands: Commands) {
 }
 
 fn setup_worldspace_text(mut commands: Commands, asset_server: ResMut<AssetServer>) {
+    let brush = vello::peniko::Brush::Solid(vello::peniko::Color::WHITE);
+
+    commands.spawn((
+        VelloTextBundle {
+            text: VelloTextSection {
+                value: "bevy_vello using RobotoFlex-VariableFont".to_string(),
+                style: VelloTextStyle {
+                    font: asset_server.load(EMBEDDED_FONT),
+                    brush: brush.clone(),
+                    line_height: 1.5,
+                    word_spacing: 2.0,
+                    letter_spacing: 2.0,
+                    font_size: 32.0,
+                    ..default()
+                },
+                ..default()
+            },
+            text_anchor: VelloTextAnchor::Center,
+            transform: Transform::from_xyz(0.0, 150.0, 0.0),
+            ..default()
+        },
+        WithAnimatedFont,
+    ));
+
     commands.spawn(VelloTextBundle {
         text: VelloTextSection {
             value: "bevy_vello using Bevy's default font".to_string(),
             style: VelloTextStyle {
                 font_size: 24.0,
                 ..default()
             },
+            ..default()
         },
         text_anchor: VelloTextAnchor::Center,
-        transform: Transform::from_xyz(0.0, -100.0, 0.0),
+        transform: Transform::from_xyz(0.0, 40.0, 0.0),
         ..default()
     });
 
-    let brush = vello::peniko::Brush::Solid(vello::peniko::Color::WHITE);
-
     commands.spawn(VelloTextBundle {
         text: VelloTextSection {
-            value: "bevy_vello using RobotoFlex-VariableFont".to_string(),
+            value: "Justified text along a width\nbut the last line is not justified".to_string(),
+            text_align: VelloTextAlign::Justified,
+            width: Some(720.0),
             style: VelloTextStyle {
                 font: asset_server.load(EMBEDDED_FONT),
                 brush,
                 line_height: 1.5,
                 word_spacing: 2.0,
                 letter_spacing: 2.0,
-                font_size: 48.0,
+                font_size: 32.0,
                 ..default()
             },
         },
         text_anchor: VelloTextAnchor::Center,
+        transform: Transform::from_xyz(0.0, -100.0, 0.0),
         ..default()
     });
 }
@@ -121,9 +151,12 @@ fn toggle_animations(
 
 const ANIMATION_SPEED: f32 = 5.0;
 
+#[derive(Component)]
+struct WithAnimatedFont;
+
 fn animate_axes(
     time: Res<Time>,
-    mut query: Query<&mut VelloTextSection>,
+    mut text_section: Single<&mut VelloTextSection, With<WithAnimatedFont>>,
     animation_toggles: Res<AnimationToggles>,
 ) {
     let sin_time = (time.elapsed_secs() * ANIMATION_SPEED)
@@ -144,54 +177,52 @@ fn animate_axes(
     let descender_depth = sin_time.remap(0., 1., -98., -305.);
     let figure_height = sin_time.remap(0., 1., 560., 788.);
 
-    for mut text_section in query.iter_mut() {
-        if animation_toggles.weight {
-            text_section.style.font_axes.weight = Some(font_weight);
-        }
+    if animation_toggles.weight {
+        text_section.style.font_axes.weight = Some(font_weight);
+    }
 
-        if animation_toggles.width {
-            text_section.style.font_axes.width = Some(font_width);
-        }
+    if animation_toggles.width {
+        text_section.style.font_axes.width = Some(font_width);
+    }
 
-        if animation_toggles.slant {
-            text_section.style.font_axes.slant = Some(slant);
-        }
+    if animation_toggles.slant {
+        text_section.style.font_axes.slant = Some(slant);
+    }
 
-        if animation_toggles.grade {
-            text_section.style.font_axes.grade = Some(grade);
-        }
+    if animation_toggles.grade {
+        text_section.style.font_axes.grade = Some(grade);
+    }
 
-        if animation_toggles.thick_stroke {
-            text_section.style.font_axes.thick_stroke = Some(thick_stroke);
-        }
+    if animation_toggles.thick_stroke {
+        text_section.style.font_axes.thick_stroke = Some(thick_stroke);
+    }
 
-        if animation_toggles.thin_stroke {
-            text_section.style.font_axes.thin_stroke = Some(thin_stroke);
-        }
+    if animation_toggles.thin_stroke {
+        text_section.style.font_axes.thin_stroke = Some(thin_stroke);
+    }
 
-        if animation_toggles.counter_width {
-            text_section.style.font_axes.counter_width = Some(counter_width);
-        }
+    if animation_toggles.counter_width {
+        text_section.style.font_axes.counter_width = Some(counter_width);
+    }
 
-        if animation_toggles.uppercase_height {
-            text_section.style.font_axes.uppercase_height = Some(uppercase_height);
-        }
+    if animation_toggles.uppercase_height {
+        text_section.style.font_axes.uppercase_height = Some(uppercase_height);
+    }
 
-        if animation_toggles.lowercase_height {
-            text_section.style.font_axes.lowercase_height = Some(lowercase_height);
-        }
+    if animation_toggles.lowercase_height {
+        text_section.style.font_axes.lowercase_height = Some(lowercase_height);
+    }
 
-        if animation_toggles.ascender_height {
-            text_section.style.font_axes.ascender_height = Some(ascender_height);
-        }
+    if animation_toggles.ascender_height {
+        text_section.style.font_axes.ascender_height = Some(ascender_height);
+    }
 
-        if animation_toggles.descender_depth {
-            text_section.style.font_axes.descender_depth = Some(descender_depth);
-        }
+    if animation_toggles.descender_depth {
+        text_section.style.font_axes.descender_depth = Some(descender_depth);
+    }
 
-        if animation_toggles.figure_height {
-            text_section.style.font_axes.figure_height = Some(figure_height);
-        }
+    if animation_toggles.figure_height {
+        text_section.style.font_axes.figure_height = Some(figure_height);
     }
 }
 
diff --git a/src/text/font.rs b/src/text/font.rs
@@ -67,9 +67,21 @@ impl VelloFont {
                 )));
 
                 let mut layout = builder.build(&text_section.value);
-                layout.break_all_lines(None);
-
-                Vec2::new(layout.width(), layout.height())
+                let max_advance = text_section.width;
+                layout.break_all_lines(max_advance);
+                layout.align(
+                    max_advance,
+                    text_section.text_align.into(),
+                    parley::AlignmentOptions::default(),
+                );
+
+                let width = if text_section.width.is_some() {
+                    text_section.width.unwrap()
+                } else {
+                    layout.width()
+                };
+
+                Vec2::new(width, layout.height())
             })
         })
     }
@@ -100,9 +112,20 @@ impl VelloFont {
                 )));
 
                 let mut layout = builder.build(&text_section.value);
-                layout.break_all_lines(None);
+                let max_advance = text_section.width;
+                layout.break_all_lines(max_advance);
+                layout.align(
+                    max_advance,
+                    text_section.text_align.into(),
+                    parley::AlignmentOptions::default(),
+                );
+
+                let width = if text_section.width.is_some() {
+                    text_section.width.unwrap()
+                } else {
+                    layout.width()
+                } as f64;
 
-                let width = layout.width() as f64;
                 let height = layout.height() as f64;
 
                 // NOTE: Parley aligns differently than our previous skrifa implementation
diff --git a/src/text/mod.rs b/src/text/mod.rs
@@ -7,4 +7,4 @@ mod vello_text;
 
 pub use font::VelloFont;
 pub(crate) use font_loader::{VelloFontLoader, load_into_font_context};
-pub use vello_text::{VelloTextAnchor, VelloTextSection, VelloTextStyle};
+pub use vello_text::{VelloTextAlign, VelloTextAnchor, VelloTextSection, VelloTextStyle};
diff --git a/src/text/vello_text.rs b/src/text/vello_text.rs
@@ -7,6 +7,8 @@ use vello::peniko::{self, Brush};
 pub struct VelloTextSection {
     pub value: String,
     pub style: VelloTextStyle,
+    pub text_align: VelloTextAlign,
+    pub width: Option<f32>,
 }
 
 #[derive(Clone)]
@@ -140,6 +142,43 @@ pub enum VelloTextAnchor {
     TopRight,
 }
 
+/// Alignment of a parley layout.
+#[derive(Default, Clone, Copy, PartialEq, Eq)]
+pub enum VelloTextAlign {
+    /// This is [`parley::Alignment::Left`] for LTR text and [`parley::Alignment::Right`] for RTL text.
+    #[default]
+    Start,
+    /// This is [`parley::Alignment::Right`] for LTR text and [`parley::Alignment::Left`] for RTL text.
+    End,
+    /// Align content to the left edge.
+    ///
+    /// For alignment that should be aware of text direction, use [`parley::Alignment::Start`] or
+    /// [`parley::Alignment::End`] instead.
+    Left,
+    /// Align each line centered within the container.
+    Middle,
+    /// Align content to the right edge.
+    ///
+    /// For alignment that should be aware of text direction, use [`parley::Alignment::Start`] or
+    /// [`parley::Alignment::End`] instead.
+    Right,
+    /// Justify each line by spacing out content, except for the last line.
+    Justified,
+}
+
+impl From<VelloTextAlign> for parley::Alignment {
+    fn from(value: VelloTextAlign) -> Self {
+        match value {
+            VelloTextAlign::Start => parley::Alignment::Start,
+            VelloTextAlign::End => parley::Alignment::End,
+            VelloTextAlign::Left => parley::Alignment::Left,
+            VelloTextAlign::Middle => parley::Alignment::Middle,
+            VelloTextAlign::Right => parley::Alignment::Right,
+            VelloTextAlign::Justified => parley::Alignment::Justified,
+        }
+    }
+}
+
 impl VelloTextSection {
     /// Returns the bounding box in world space
     pub fn bb_in_world_space(&self, font: &VelloFont, gtransform: &GlobalTransform) -> Rect {
