valo 0.2.0

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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229

//! The persistent canvas backing: pixels survive between frames, the work per
//! frame stays flat, and the restore that makes both true is pixel-exact.

use std::sync::Arc;

use valo::{Color, Context, DisplayList, DisplayListBuilder, Paint, PersistentCanvas, Rect};

const FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;

fn dot(x: f32, y: f32, color: Color) -> Arc<DisplayList> {
    let mut builder = DisplayListBuilder::new();
    builder.draw_rect(Rect::new(x, y, 8.0, 8.0), &Paint::from_color(color));
    Arc::new(builder.build())
}

/// The backing's raw PREMULTIPLIED bytes — what is actually stored, which is
/// what a drift check has to compare.
fn read(gpu: &(wgpu::Device, wgpu::Queue), canvas: &PersistentCanvas) -> Vec<u8> {
    valo_harness::read_texture_rgba(&gpu.0, &gpu.1, canvas.front().texture(), canvas.size())
}

fn pixel(pixels: &[u8], width: u32, x: u32, y: u32) -> [u8; 4] {
    let start = ((y * width + x) * 4) as usize;
    [
        pixels[start],
        pixels[start + 1],
        pixels[start + 2],
        pixels[start + 3],
    ]
}

/// The guarantee the whole design exists for: draw, present, draw again
/// WITHOUT clearing, and the first drawing is still there.
#[test]
fn pixels_survive_across_presents() {
    let Some((device, queue)) = valo_harness::headless_device() else {
        eprintln!("SKIP pixels_survive_across_presents");
        return;
    };
    let gpu = (device.clone(), queue.clone());
    let mut context = Context::new(device, queue);
    let mut canvas = PersistentCanvas::new(&mut context, [64, 64], FORMAT);

    canvas.draw(
        &mut context,
        &dot(8.0, 8.0, Color::rgb(1.0, 0.0, 0.0)),
        None,
    );
    canvas.draw(
        &mut context,
        &dot(40.0, 40.0, Color::rgb(0.0, 1.0, 0.0)),
        None,
    );

    let pixels = read(&gpu, &canvas);
    assert_eq!(
        pixel(&pixels, 64, 12, 12),
        [255, 0, 0, 255],
        "the first frame's ink must survive the second frame"
    );
    assert_eq!(pixel(&pixels, 64, 44, 44), [0, 255, 0, 255]);
    assert_eq!(pixel(&pixels, 64, 32, 32), [0, 0, 0, 0], "nothing else");
}

/// A clear DISCARDS what was there — the `reset` / `beginFrame` /
/// full-surface-clearRect path, and the one case that must skip the restore.
#[test]
fn a_clear_discards_what_came_before() {
    let Some((device, queue)) = valo_harness::headless_device() else {
        eprintln!("SKIP a_clear_discards_what_came_before");
        return;
    };
    let gpu = (device.clone(), queue.clone());
    let mut context = Context::new(device, queue);
    let mut canvas = PersistentCanvas::new(&mut context, [64, 64], FORMAT);

    canvas.draw(
        &mut context,
        &dot(8.0, 8.0, Color::rgb(1.0, 0.0, 0.0)),
        None,
    );
    canvas.draw(
        &mut context,
        &dot(40.0, 40.0, Color::rgb(0.0, 1.0, 0.0)),
        Some(Color::TRANSPARENT),
    );

    let pixels = read(&gpu, &canvas);
    assert_eq!(
        pixel(&pixels, 64, 12, 12),
        [0, 0, 0, 0],
        "the cleared frame must not restore the old ink"
    );
    assert_eq!(pixel(&pixels, 64, 44, 44), [0, 255, 0, 255]);
}

/// The failure mode that would otherwise surface months later as "the canvas
/// looks blurry": any resampling in the restore compounds every frame.
///
/// 60 presents of an empty delta means 60 round trips through the restore. A
/// half-texel offset, a linear filter, or a premultiply round trip would each
/// leave a visible trail by then; exact restore leaves the buffer bit-identical.
#[test]
fn the_restore_does_not_drift_over_many_presents() {
    let Some((device, queue)) = valo_harness::headless_device() else {
        eprintln!("SKIP the_restore_does_not_drift_over_many_presents");
        return;
    };
    let gpu = (device.clone(), queue.clone());
    let mut context = Context::new(device, queue);
    let mut canvas = PersistentCanvas::new(&mut context, [64, 64], FORMAT);

    // Content that reaches the CANVAS EDGE on all four sides, plus hard
    // interior edges and a translucent block.
    //
    // The edge coverage is the part that matters: a sub-pixel translation in
    // the restore erodes whatever sits against the boundary, and interior-only
    // content hides that completely — the eroded columns are transparent
    // either way. A translucent block catches a premultiply round trip going
    // wrong, and the interior edges catch a scale error.
    let mut builder = DisplayListBuilder::new();
    builder.draw_rect(
        Rect::new(0.0, 0.0, 64.0, 2.0),
        &Paint::from_color(Color::rgb(1.0, 1.0, 0.0)),
    );
    builder.draw_rect(
        Rect::new(0.0, 62.0, 64.0, 2.0),
        &Paint::from_color(Color::rgb(0.0, 1.0, 1.0)),
    );
    builder.draw_rect(
        Rect::new(0.0, 0.0, 2.0, 64.0),
        &Paint::from_color(Color::rgb(1.0, 0.0, 1.0)),
    );
    builder.draw_rect(
        Rect::new(62.0, 0.0, 2.0, 64.0),
        &Paint::from_color(Color::rgb(0.5, 0.5, 1.0)),
    );
    builder.draw_rect(
        Rect::new(3.0, 5.0, 17.0, 23.0),
        &Paint::from_color(Color::rgb(1.0, 0.25, 0.5)),
    );
    builder.draw_rect(
        Rect::new(30.0, 12.0, 21.0, 19.0),
        &Paint::from_color(Color::rgba(0.2, 0.9, 0.4, 0.6)),
    );
    canvas.draw(&mut context, &Arc::new(builder.build()), None);
    let first = read(&gpu, &canvas);

    let empty = Arc::new(DisplayListBuilder::new().build());
    for _ in 0..60 {
        canvas.draw(&mut context, &empty, None);
    }
    let after = read(&gpu, &canvas);

    assert_eq!(
        first, after,
        "60 restores must be bit-identical; any filtering compounds forever"
    );
}

/// The reason for the whole change: N incremental frames must cost O(N), not
/// O(N²).
///
/// The old model replayed every list ever recorded, so frame N encoded N
/// draws and the total was 1+2+…+N. Here each frame encodes its own delta
/// plus one restore, so the per-frame cost is FLAT and the total is linear.
/// Asserting on encoded draws rather than wall-clock keeps this a regression
/// test rather than a benchmark.
#[test]
fn per_frame_cost_stays_flat_as_the_canvas_accumulates() {
    let Some((device, queue)) = valo_harness::headless_device() else {
        eprintln!("SKIP per_frame_cost_stays_flat_as_the_canvas_accumulates");
        return;
    };
    let mut context = Context::new(device, queue);
    let mut canvas = PersistentCanvas::new(&mut context, [128, 128], FORMAT);

    let mut draws = Vec::new();
    for frame in 0..24u32 {
        let x = (frame % 12) as f32 * 10.0;
        let y = (frame / 12) as f32 * 10.0;
        let stats = canvas.draw(&mut context, &dot(x, y, Color::rgb(1.0, 1.0, 1.0)), None);
        draws.push(stats.draws);
    }

    // Frame 0 has nothing to restore; every frame after is one restore plus
    // one delta draw, forever.
    assert_eq!(draws[0], 1, "the first frame restores nothing");
    assert!(
        draws[1..].iter().all(|&count| count == 2),
        "every later frame is restore + delta, got {draws:?}"
    );

    let total: u32 = draws.iter().sum();
    let quadratic = 24 * 25 / 2;
    assert!(
        total < quadratic / 4,
        "total work {total} should be linear, not the {quadratic} of cumulative replay"
    );
}

/// A resize reallocates rather than rescaling — scaling old pixels would be
/// the one place resampling could sneak back in.
#[test]
fn a_resize_starts_from_a_clear_canvas() {
    let Some((device, queue)) = valo_harness::headless_device() else {
        eprintln!("SKIP a_resize_starts_from_a_clear_canvas");
        return;
    };
    let gpu = (device.clone(), queue.clone());
    let mut context = Context::new(device, queue);
    let mut canvas = PersistentCanvas::new(&mut context, [64, 64], FORMAT);
    canvas.draw(
        &mut context,
        &dot(8.0, 8.0, Color::rgb(1.0, 0.0, 0.0)),
        None,
    );

    canvas.resize(&mut context, [96, 48]);
    assert_eq!(canvas.size(), [96, 48]);

    let empty = Arc::new(DisplayListBuilder::new().build());
    canvas.draw(&mut context, &empty, None);
    let pixels = read(&gpu, &canvas);
    assert!(
        pixels.chunks_exact(4).all(|pixel| pixel[3] == 0),
        "a resized canvas starts empty"
    );
}