Struct Text 

pub struct Text { /* private fields */ }

Text builder for creating styled text.

Text positioning uses a top-left coordinate system where (0, 0) is the top-left corner and Y increases downward, consistent with UI layout systems like CSS and Flutter.

SDF Effects

Text supports effects like shadows, outlines, and glows via SDF (Signed Distance Field) rendering. When effects are present, the text automatically uses SDF mode:

let text = Text::new("Hello")
    .size(24.0)
    .with_shadow(Vec2::new(2.0, 2.0), 2.0, Color::rgba(0.0, 0.0, 0.0, 0.5))
    .with_outline(1.5, Color::BLACK);

Implementations

impl Text

pub fn new(content: impl Into<String>) -> Self

Create a new text instance.

pub fn size(self, size: f32) -> Self

Set the font size in pixels.

pub fn line_height(self, height: f32) -> Self

Set the line height multiplier.

pub fn font(self, family: impl Into<String>) -> Self

Set the font family.

pub fn weight(self, weight: FontWeight) -> Self

Set the font weight.

pub fn style(self, style: FontStyle) -> Self

Set the font style.

pub fn stretch(self, stretch: FontStretch) -> Self

Set the font stretch.

pub fn font_attrs(self, attrs: FontAttributes) -> Self

Set font attributes.

pub fn color(self, color: Color) -> Self

Set the text color.

pub fn align(self, align: TextAlign) -> Self

Set the text alignment (horizontal).

pub fn vertical_align(self, vertical_align: VerticalAlign) -> Self

Set the vertical alignment.

pub fn wrap(self, wrap: TextWrap) -> Self

Set the text wrapping mode.

pub fn line_break(self, config: LineBreakConfig) -> Self

Set line breaking configuration for advanced control.

This provides more control than .wrap() alone, allowing configuration of hyphen breaks and future UAX#14 options.

Arguments

• config - The line break configuration

Example

use astrelis_text::{Text, LineBreakConfig, TextWrap};

let text = Text::new("Long text with a-very-long-hyphenated-word")
    .line_break(
        LineBreakConfig::new(TextWrap::WordOrGlyph)
            .with_hyphen_breaks(true)
    )
    .max_width(200.0);

pub fn max_width(self, width: f32) -> Self

Set the maximum width for text wrapping.

pub fn max_height(self, height: f32) -> Self

Set the maximum height for text.

pub fn letter_spacing(self, spacing: f32) -> Self

Set letter spacing in pixels.

pub fn word_spacing(self, spacing: f32) -> Self

Set word spacing in pixels.

pub fn bold(self) -> Self

Make the text bold.

pub fn italic(self) -> Self

Make the text italic.

pub fn get_content(&self) -> &str

pub fn get_font_size(&self) -> f32

pub fn get_line_height(&self) -> f32

pub fn get_font_attrs(&self) -> &FontAttributes

pub fn get_color(&self) -> Color

pub fn get_align(&self) -> TextAlign

pub fn get_vertical_align(&self) -> VerticalAlign

pub fn get_wrap(&self) -> TextWrap

pub fn get_max_width(&self) -> Option<f32>

pub fn get_max_height(&self) -> Option<f32>

pub fn get_letter_spacing(&self) -> f32

pub fn get_word_spacing(&self) -> f32

pub fn get_break_at_hyphens(&self) -> bool

Check if hyphen breaks are enabled.

pub fn with_effect(self, effect: TextEffect) -> Self

Add a single text effect.

Effects are rendered using SDF (Signed Distance Field) rendering, which enables high-quality shadows, outlines, and glows at any scale.

Multiple effects can be combined by chaining calls. Effects are rendered in priority order: shadows first (background), then outlines (foreground).

Arguments

• effect - The text effect to add

Example

use astrelis_text::{Text, TextEffect, Color};
use astrelis_core::math::Vec2;

// Single shadow effect
let text = Text::new("Hello")
    .size(32.0)
    .with_effect(TextEffect::shadow(
        Vec2::new(2.0, 2.0),
        Color::rgba(0.0, 0.0, 0.0, 0.5)
    ));

// Combine shadow and outline
let text = Text::new("Bold")
    .size(48.0)
    .with_effect(TextEffect::shadow(
        Vec2::new(2.0, 2.0),
        Color::BLACK
    ))
    .with_effect(TextEffect::outline(
        2.0,
        Color::WHITE
    ));

pub fn with_effects(self, effects: TextEffects) -> Self

Add multiple text effects at once.

pub fn with_shadow(self, offset: Vec2, color: Color) -> Self

Add a shadow effect.

Creates a drop shadow behind the text. This is the most commonly used effect for improving text readability on varied backgrounds.

Arguments

• offset - Shadow offset in pixels (x, y). Positive values offset down and right.
• color - Shadow color (typically semi-transparent black)

Example

use astrelis_text::{Text, Color};
use astrelis_core::math::Vec2;

// Standard drop shadow (2px right and down)
let text = Text::new("Readable")
    .size(24.0)
    .with_shadow(Vec2::new(2.0, 2.0), Color::rgba(0.0, 0.0, 0.0, 0.5));

pub fn with_shadow_blurred( self, offset: Vec2, blur_radius: f32, color: Color, ) -> Self

Add a blurred shadow effect for softer appearance.

Creates a drop shadow with a blur radius, producing a softer, more natural shadow that’s useful for headings and titles.

Arguments

• offset - Shadow offset in pixels (x, y)
• blur_radius - Blur radius in pixels (0 = hard edge, 2-5 = soft shadow)
• color - Shadow color (typically semi-transparent)

Example

use astrelis_text::{Text, Color};
use astrelis_core::math::Vec2;

// Soft shadow for a heading
let text = Text::new("Title")
    .size(48.0)
    .with_shadow_blurred(
        Vec2::new(3.0, 3.0),
        4.0,  // 4px blur radius
        Color::rgba(0.0, 0.0, 0.0, 0.6)
    );

pub fn with_outline(self, width: f32, color: Color) -> Self

Add an outline effect around the text.

Creates a stroke around text characters, useful for making text stand out against complex backgrounds or creating stylized text.

Arguments

• width - Outline width in pixels (typically 1-3px)
• color - Outline color (often contrasting with text color)

Example

use astrelis_text::{Text, Color};

// White text with black outline (classic game text style)
let text = Text::new("Game Text")
    .size(32.0)
    .color(Color::WHITE)
    .with_outline(2.0, Color::BLACK);

// Bold outline for emphasis
let text = Text::new("Important!")
    .size(40.0)
    .color(Color::YELLOW)
    .with_outline(3.0, Color::RED);

pub fn with_glow(self, radius: f32, color: Color, intensity: f32) -> Self

Add a glow effect around the text.

Creates a soft luminous halo around text, useful for magical, sci-fi, or neon-style text effects.

Arguments

• radius - Glow radius in pixels (typically 3-10px)
• color - Glow color (often bright, saturated colors)
• intensity - Glow intensity multiplier (0.5 to 1.0 for subtle, > 1.0 for intense)

Example

use astrelis_text::{Text, Color};

// Neon blue glow
let text = Text::new("Cyber")
    .size(36.0)
    .color(Color::CYAN)
    .with_glow(6.0, Color::BLUE, 0.8);

// Intense magical glow
let text = Text::new("Magic")
    .size(40.0)
    .color(Color::WHITE)
    .with_glow(8.0, Color::rgba(1.0, 0.0, 1.0, 1.0), 1.2);

pub fn render_mode(self, mode: TextRenderMode) -> Self

Set the render mode (Bitmap or SDF).

By default, render mode is auto-selected based on font size and effects:

• Bitmap for small text (< 24px) without effects - sharper at small sizes
• SDF for large text (>= 24px) or text with effects - scalable and smooth

Use this method to override the automatic selection.

Arguments

• mode - The render mode to use:
  • TextRenderMode::Bitmap - Traditional rasterized glyphs
  • TextRenderMode::SDF { spread } - Distance field rendering

Example

use astrelis_text::{Text, TextRenderMode};

// Force bitmap even for large text
let text = Text::new("Large but Sharp")
    .size(48.0)
    .render_mode(TextRenderMode::Bitmap);

// Force SDF with custom spread
let text = Text::new("Custom SDF")
    .size(20.0)
    .render_mode(TextRenderMode::SDF { spread: 6.0 });

pub fn sdf(self) -> Self

Force SDF rendering mode with default spread.

Useful for text that needs to scale smoothly or maintain quality at various sizes. Equivalent to .render_mode(TextRenderMode::SDF { spread: 4.0 }).

When to Use

• Text that will be animated or scaled
• Text in UI elements that change size
• High-DPI displays where extra sharpness helps
• When preparing text for future effects

Example

use astrelis_text::Text;

// Small text that will be scaled up smoothly
let text = Text::new("UI Label")
    .size(14.0)
    .sdf();  // Force SDF for smooth scaling

pub fn get_effects(&self) -> Option<&TextEffects>

Get the text effects, if any.

pub fn get_render_mode(&self) -> Option<TextRenderMode>

Get the render mode, if explicitly set.

pub fn has_effects(&self) -> bool

Check if this text has any effects configured.

pub fn with_decoration(self, decoration: TextDecoration) -> Self

Set text decoration (underline, strikethrough, background).

Text decorations are rendered separately from the text glyphs:

• Background: colored quad behind text (rendered first)
• Underline: line below the text baseline
• Strikethrough: line through the middle of text

Arguments

• decoration - The decoration configuration

Example

use astrelis_text::{Text, TextDecoration, UnderlineStyle, Color};

let decoration = TextDecoration::new()
    .underline(UnderlineStyle::solid(Color::BLUE, 1.0))
    .background(Color::YELLOW);

let text = Text::new("Important text")
    .with_decoration(decoration);

pub fn underline(self, color: Color) -> Self

Add a solid underline with the specified color.

Convenience method for adding a simple solid underline. For more control (thickness, offset, style), use with_decoration().

Arguments

• color - The underline color

Example

use astrelis_text::{Text, Color};

let text = Text::new("Underlined")
    .underline(Color::BLUE);

pub fn strikethrough(self, color: Color) -> Self

Add a solid strikethrough with the specified color.

Convenience method for adding a simple solid strikethrough. For more control (thickness, offset, style), use with_decoration().

Arguments

• color - The strikethrough color

Example

use astrelis_text::{Text, Color};

let text = Text::new("Deleted")
    .strikethrough(Color::RED);

pub fn background_color(self, color: Color) -> Self

Add a background highlight color.

Convenience method for adding a simple background highlight. For more control (padding), use with_decoration().

Arguments

• color - The background highlight color

Example

use astrelis_text::{Text, Color};

let text = Text::new("Highlighted")
    .background_color(Color::YELLOW);

pub fn get_decoration(&self) -> Option<&TextDecoration>

Get the text decoration, if any.

pub fn has_decoration(&self) -> bool

Check if this text has any decoration configured.

pub fn effective_render_mode(&self) -> TextRenderMode

Determine the appropriate render mode for this text.

Returns the explicitly set mode via .render_mode() or .sdf(), or auto-selects based on font size and effects using the hybrid rendering strategy.

Auto-Selection Logic

If no explicit mode is set:

• Font size >= 24px → SDF (better scaling for large text)
• Has effects → SDF (required for shadows, outlines, glows)
• Otherwise → Bitmap (sharper for small UI text)

Returns

The render mode that will be used when this text is rendered

Example

use astrelis_text::{Text, TextRenderMode};

let text = Text::new("Hello").size(32.0);
assert!(text.effective_render_mode().is_sdf());  // Auto-selected SDF for 32px

let text = Text::new("Small").size(14.0);
assert!(!text.effective_render_mode().is_sdf());  // Auto-selected Bitmap for 14px

let text = Text::new("Effects").size(16.0).with_shadow(...);
assert!(text.effective_render_mode().is_sdf());  // Auto-selected SDF for effects

Trait Implementations

impl Default for Text

fn default() -> Self

Returns the “default value” for a type.