Crate astrelis_text 

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:

Renderer	Memory	Use Case
BitmapTextRenderer	~8 MB	Small text, UI labels, no effects needed
SdfTextRenderer	~8 MB	Large text, titles, needs shadows/outlines/glows
FontRenderer	~16 MB	Mixed usage, backwards compatibility (default)

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

Re-exports

pub use cache::ShapeKey;

pub use cache::ShapedTextData;

pub use cache::TextShapeCache;

pub use decoration::BackgroundGeometry;

pub use decoration::DecorationGeometry;

pub use decoration::DecorationQuad;

pub use decoration::DecorationQuadType;

pub use decoration::LineStyle;

pub use decoration::StrikethroughStyle;

pub use decoration::TextBounds;

pub use decoration::TextDecoration;

pub use decoration::UnderlineStyle;

pub use decoration::generate_decoration_geometry;

pub use decoration::generate_decoration_quads;

pub use editor::TextCursor;

pub use editor::TextEditor;

pub use editor::TextSelection;

pub use effects::EffectRenderConfig;

pub use effects::TextEffect;

pub use effects::TextEffectType;

pub use effects::TextEffects;

pub use effects::TextEffectsBuilder;

pub use error::TextError;

pub use error::TextResult;

pub use font::FontAttributes;

pub use font::FontDatabase;

pub use font::FontStretch;

pub use font::FontStyle;

pub use font::FontSystem;

pub use font::FontWeight;

pub use pipeline::RequestId;

pub use pipeline::ShapedTextResult as PipelineShapedTextResult;

pub use pipeline::SyncTextShaper;

pub use pipeline::TextPipeline;

pub use pipeline::TextShapeRequest;

pub use pipeline::TextShaper;

pub use renderer::AtlasEntry;

pub use renderer::BitmapTextRenderer;

pub use renderer::DecorationRenderer;

pub use renderer::DecorationVertex;

pub use renderer::FontRenderer;

pub use renderer::GlyphPlacement;

pub use renderer::SdfAtlasEntry;

pub use renderer::SdfCacheKey;

pub use renderer::SdfParams;

pub use renderer::SdfTextRenderer;

pub use renderer::SharedContext;

pub use renderer::TextBuffer;

pub use renderer::TextRender;

pub use renderer::TextRendererConfig;

pub use renderer::TextVertex;

pub use rich_text::RichText;

pub use rich_text::RichTextBuilder;

pub use rich_text::TextSpan;

pub use rich_text::TextSpanStyle;

pub use sdf::SdfConfig;

pub use sdf::TextRenderMode;

pub use sdf::generate_sdf;

pub use sdf::generate_sdf_smooth;

pub use shaping::ShapedGlyph;

pub use shaping::ShapedTextResult;

pub use shaping::extract_glyphs_from_buffer;

pub use shaping::measure_text_fast;

pub use shaping::shape_text;

pub use text::LineBreakConfig;

pub use text::Text;

pub use text::TextAlign;

pub use text::TextMetrics;

pub use text::TextWrap;

pub use text::VerticalAlign;

pub use asset::FontAsset;

pub use asset::FontFormat;

pub use asset::FontLoader;

Modules

asset

Asset integration for font loading.

cache

Text shaping cache for performance optimization.

decoration

Text decoration - underline, strikethrough, and background highlighting.

editor

Text editor with selection and cursor management.

effects

Text effects including shadows, outlines, and glows.

error

font

pipeline

Text shaping pipeline for deferred/async text processing.

renderer

Modular text rendering system with zero-cost abstraction.

rich_text

Rich text formatting with styled spans.

sdf

Signed Distance Field (SDF) text rendering.

shaping

Text shaping integration with cosmic-text.

text

Structs

CacheKey

Key for building a glyph cache

Color

An RGBA color with f32 components in the 0.0..=1.0 range.

Vec2

A 2-dimensional vector.