Lib.rs

Astrelis Text - Text rendering with cosmic-text

This crate provides modular text rendering capabilities:

• Font management with system fonts and custom fonts
• Text builder with styling (size, color, alignment, etc.)
• GPU-accelerated text rendering with zero-cost backend selection
• Signed Distance Field (SDF) rendering for scalable text and effects

Zero-Cost Renderer Selection

Choose the renderer that fits your memory budget:

Memory can be further reduced with TextRendererConfig:

• small(): 512x512 atlas (~1 MB per renderer)
• medium(): 1024x1024 atlas (~4 MB per renderer)
• large(): 2048x2048 atlas (~8 MB per renderer, default)

Quick Start

use astrelis_text::{FontSystem, FontRenderer, Text, Color};
use astrelis_render::GraphicsContext;
use astrelis_core::math::Vec2;

let context = GraphicsContext::new_owned_sync().expect("Failed to create graphics context");
let font_system = FontSystem::with_system_fonts();
let mut renderer = FontRenderer::new(context, font_system);

// Create styled text with builder pattern
let text = Text::new("Hello, World!")
    .size(24.0)
    .color(Color::WHITE)
    .bold();

// Prepare and draw
let mut buffer = renderer.prepare(&text);
renderer.draw_text(&mut buffer, Vec2::new(100.0, 100.0));

// Render to a render pass
// renderer.render(render_pass, viewport_size);

Features

• System Fonts: Automatically loads all system fonts
• Custom Fonts: Load .ttf and .otf files from disk or memory
• Rich Styling: Font size, weight, style, color, alignment, wrapping
• Builder Pattern: Fluent API for text configuration
• GPU Accelerated: WGPU-based rendering with texture atlas
• Text Layout: Multi-line text with automatic wrapping
• Asset Integration: Load fonts through the asset system (with asset feature)
• SDF Rendering: Resolution-independent text scaling and effects
• Text Effects: Shadows, outlines, glows, and more

SDF (Signed Distance Field) Rendering

SDF rendering enables sharp text at any scale and high-quality effects. The renderer uses a hybrid approach for optimal quality:

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

When to Use SDF

SDF rendering is automatically enabled for:

• Large text (24px and above)
• Text with effects (shadows, outlines, glows)
• Text that needs to scale dynamically

Basic SDF Usage

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

// Text with a drop shadow
let text = Text::new("Hello")
    .size(32.0)
    .with_shadow(Vec2::new(2.0, 2.0), Color::rgba(0.0, 0.0, 0.0, 0.5));

// Text with an outline
let text = Text::new("Bold")
    .size(48.0)
    .with_outline(2.0, Color::BLACK);

// Combine multiple effects
let text = Text::new("Glowing")
    .size(36.0)
    .with_shadow(Vec2::new(1.0, 1.0), Color::BLACK)
    .with_outline(1.5, Color::WHITE)
    .with_glow(4.0, Color::BLUE, 0.8);

Force SDF Mode

You can force SDF rendering for better scalability:

use astrelis_text::Text;

let text = Text::new("Scalable")
    .size(16.0)
    .sdf();  // Force SDF even for small text

Examples

Run the examples to see text rendering in action:

cargo run --package astrelis-text --example text_demo
cargo run --package astrelis-text --example text_effects
cargo run --package astrelis-text --example rich_text_demo