klyff 0.1.3

Text rendering library for games with MSDF support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# Klyff text rendering


<img src="https://img.shields.io/badge/min%20rust-1.91-green.svg" alt="Minimum Rust Version">
<a href="https://docs.rs/klyff"><img src="https://docs.rs/klyff/badge.svg" alt="docs.rs"></a>
<a href="https://crates.io/crates/klyff"><img src="https://img.shields.io/crates/v/klyff.svg?label=klyff" alt="crates.io"></a>

Klyff is a text rendering library designed for games with high customization needs, built on [cosmic_text](https://crates.io/crates/cosmic_text) and [wgpu](https://crates.io/crates/wgpu). 

It uses a technique called MSDF (Multi-channel Signed Distance Field), which supports infinite scaling while still retaining sharp corners (as opposed to SDF). MSDF generation is reimplemented in 100% pure Rust, instead of binding to the original [msdfgen](https://github.com/Chlumsky/msdfgen) C++ library.

## Features


- **MSDF-based rendering** - Glyphs scale infinitely without losing sharpness
- **Rich text styling** - Supports outline, glow (inner/outer), and shadow effects
- **Gradient support** - Linear gradients for text fill and effects
- **GPU-accelerated MSDF generation** - Generate distance fields directly on the GPU
- **Rasterized glyph fallback** - Colored emoji and bitmap glyphs render correctly
- **Custom glyphs** - Inject application-defined glyphs into text layout
- **Atlas baking** - Pre-generate glyph atlases offline for faster startup
- **Pure Rust** - No C/C++ dependencies for MSDF generation

## Quick Start


```rust
use klyff::{
    EncoderContext, Rect, StyledTextBuilder, TextRenderer, TextStyle, TextureAtlas,
    TextureAtlasDescriptor,
    cosmic_text::{Attrs, Family, FontSystem, Metrics},
};

// One-time setup
let mut renderer = TextRenderer::new(&device, surface_format);
let mut atlas = TextureAtlas::new(&device, TextureAtlasDescriptor::default());

// Build styled text
let attrs = Attrs::new().family(Family::Name("Open Sans"));
let mut text_builder = StyledTextBuilder::new(
    Rect::from_xywh(0.0, 0.0, 800.0, 600.0),
    &mut font_system,
    Metrics::new(48.0, 60.0));
text_builder.push_text("Hello, world!", &attrs, TextStyle::default());
let text = text_builder.finish(&mut font_system, &attrs);

// Per frame: prepare and render
renderer.prepare(
    EncoderContext {
        atlas: &mut atlas,
        device: &device,
        queue: &queue,
        cmd_encoder: &mut encoder,
        font_system: &mut font_system
    },
    (width, height),
    std::slice::from_ref(&text),
);

let mut pass = encoder.begin_render_pass(&render_pass_descriptor);
renderer.render(&mut pass, &atlas);
```

## API Layers


### High-level API


Use `TextRenderer` and `StyledText` for quick setup with built-in styling support. Each styling effect (shadow, outline, glow) is rendered as a separate draw call in back-to-front order.

### Low-level API


For custom shaders or advanced use cases:

- `MeshEncoder` - Decodes text into vertex/index buffers and records per-glyph metadata
- `MaterialEncoder` - Produces per-glyph material data (colors, distance ranges, offsets)
- `MsdfTextPipeline` / `RasterizedTextPipeline` - Built-in render pipelines

## License


All source code is licensed under the MIT License.