valo 0.2.1

A 2D render engine on wgpu: display lists, planned GPU passes, and a Skia-shaped text stack
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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

//! Paragraph recording lowers the current layout into independent display-list
//! operations. The list owns the resolved fonts, positions, and paints rather
//! than retaining the paragraph, so later paragraph changes cannot mutate it.

use std::sync::Arc;

use valo_dl::{DisplayListBuilder, GlyphPos, Paint};
use valo_geometry::{Point, Rect};
use valo_text::{DecorationKind, FaceSet, Line, Paragraph, PlacedRun};

/// `DrawParagraphExt` adds paragraph recording to [`DisplayListBuilder`].
pub trait DrawParagraphExt {
    /// `draw_paragraph` records the paragraph's current layout and span styles.
    ///
    /// The paragraph is lowered into glyph runs, shadows, and decorations at
    /// its top-left `origin`. Later layout or style changes do not affect the
    /// recorded display list.
    fn draw_paragraph(&mut self, paragraph: &Paragraph, origin: impl Into<Point>);
}

/// `DrawGlyphRunExt` adds paragraph recording with an explicit fill paint.
///
/// Use it for gradient or blended text. Shadows and decorations continue to
/// use the paragraph's span styles.
pub trait DrawGlyphRunExt {
    /// `draw_paragraph_with` records the current layout with one fill paint.
    ///
    /// `paint` replaces every span's fill, while shadows and decorations retain
    /// their span styles. Later paragraph changes do not affect the display list.
    fn draw_paragraph_with(
        &mut self,
        paragraph: &Paragraph,
        origin: impl Into<Point>,
        paint: &Paint,
    );
}

impl DrawGlyphRunExt for DisplayListBuilder {
    fn draw_paragraph_with(
        &mut self,
        paragraph: &Paragraph,
        origin: impl Into<Point>,
        paint: &Paint,
    ) {
        let origin = origin.into();
        for line in paragraph.lines() {
            for run in &line.runs {
                draw_shadows(self, paragraph, run, origin);
                draw_run(self, paragraph.faces(), run, origin, paint);
                draw_decoration(self, paragraph, line, run, origin);
            }
        }
    }
}

impl DrawParagraphExt for DisplayListBuilder {
    fn draw_paragraph(&mut self, paragraph: &Paragraph, origin: impl Into<Point>) {
        let origin = origin.into();
        for line in paragraph.lines() {
            for run in &line.runs {
                draw_shadows(self, paragraph, run, origin);
                draw_run(
                    self,
                    paragraph.faces(),
                    run,
                    origin,
                    &Paint::from_color(run.color),
                );
                draw_decoration(self, paragraph, line, run, origin);
            }
        }
    }
}

/// `draw_shadows` records styled shadows beneath their source glyph run.
///
/// Recording them first preserves the paragraph's back-to-front shadow order.
fn draw_shadows(b: &mut DisplayListBuilder, paragraph: &Paragraph, run: &PlacedRun, origin: Point) {
    for shadow in &run.shadows {
        let paint = Paint {
            color: shadow.color,
            mask_blur: (shadow.blur > 0.0).then(|| valo_dl::MaskBlur::new(shadow.blur)),
            ..Default::default()
        };
        b.save();
        b.translate(shadow.offset.x, shadow.offset.y);
        draw_run(b, paragraph.faces(), run, origin, &paint);
        b.restore();
    }
}

/// `draw_run` snapshots a placed glyph run into the display list.
///
/// It copies glyph positions and retains the resolved font so future paragraph
/// layout cannot affect the recorded run.
fn draw_run(
    b: &mut DisplayListBuilder,
    fonts: &FaceSet,
    run: &PlacedRun,
    origin: Point,
    paint: &Paint,
) {
    let glyphs: Vec<GlyphPos> = run
        .glyphs
        .iter()
        .map(|g| GlyphPos {
            id: g.id,
            x: g.x + origin.x,
            y: g.y + origin.y,
        })
        .collect();
    // Ink bounds, not the advance box: the record-time oracle culls,
    // sizes layers, and proves elision disjointness with these.
    let bounds = Rect::new(
        run.ink.x + origin.x,
        run.ink.y + origin.y,
        run.ink.width,
        run.ink.height,
    );
    b.draw_glyph_run(
        fonts.get_arc(run.font),
        run.size,
        paint,
        Arc::new(glyphs),
        bounds,
    );
}

/// `draw_decoration` records a run's decoration as geometry.
///
/// Glyph runs contain no decoration data, so font metrics position the geometry
/// against the resolved face and line baseline.
fn draw_decoration(
    b: &mut DisplayListBuilder,
    paragraph: &Paragraph,
    line: &Line,
    run: &PlacedRun,
    origin: Point,
) {
    let Some(decoration) = run.decoration else {
        return;
    };
    let font = paragraph.faces().get(run.font);
    let (offset, thickness) = match decoration.kind {
        DecorationKind::Underline => font.underline_px(run.size),
        DecorationKind::LineThrough => font.strikeout_px(run.size),
        DecorationKind::Overline => (font.ascent_px(run.size), font.underline_px(run.size).1),
    };
    let y = line.baseline - offset;
    let thickness = thickness * decoration.thickness;
    b.draw_rect(
        Rect::new(
            run.bounds.x + origin.x,
            y - thickness * 0.5 + origin.y,
            run.bounds.width,
            thickness,
        ),
        &Paint::from_color(decoration.color.unwrap_or(run.color)),
    );
}