scena 1.1.0

A Rust-native scene-graph renderer with typed scene state, glTF assets, and explicit prepare/render lifecycles.
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

#![cfg(not(target_arch = "wasm32"))]

#[test]
fn first_render_gltf_headless_loads_frames_prepares_and_renders() {
    let first = pollster::block_on(scena::first_render_gltf_headless(
        "tests/assets/gltf/mesh_material_vertex_color_scene.gltf",
        64,
        64,
    ))
    .expect("first render helper loads and renders glTF");

    assert_eq!(first.outcome().width, 64);
    assert_eq!(first.outcome().height, 64);
    assert!(first.outcome().draw_calls > 0);
    assert!(!first.import().roots().is_empty());
    assert!(first.scene().active_camera().is_some());
    assert!(
        first
            .renderer()
            .screenshot_rgba8()
            .rgba8()
            .chunks_exact(4)
            .any(|pixel| pixel[0] != 0 || pixel[1] != 0 || pixel[2] != 0),
        "first render helper produces visible pixels"
    );
}

#[test]
fn headless_gltf_viewer_builder_loads_frames_lights_and_renders() {
    let first = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(80, 48)
            .with_default_light()
            .render(),
    )
    .expect("builder renders the first glTF frame");

    assert_eq!(first.outcome().width, 80);
    assert_eq!(first.outcome().height, 48);
    assert!(first.outcome().draw_calls > 0);
    assert!(first.scene().active_camera().is_some());
    assert!(
        first
            .renderer()
            .screenshot_rgba8()
            .rgba8()
            .chunks_exact(4)
            .any(|pixel| pixel[0] != 0 || pixel[1] != 0 || pixel[2] != 0),
        "viewer builder should produce visible pixels without user-authored matrix math"
    );
}

#[test]
fn headless_gltf_viewer_builder_can_attach_environment_and_report_diagnostics() {
    let first = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(80, 48)
            .with_default_environment()
            .render(),
    )
    .expect("builder renders with a default environment");

    assert_eq!(
        first.renderer().environment(),
        Some(first.assets().default_environment())
    );
    assert_eq!(first.renderer().stats().environments, 1);
    assert_eq!(first.diagnostics(), first.renderer().diagnostics());
}

#[test]
fn headless_gltf_viewer_builder_can_build_on_change_render_loop() {
    let mut viewer = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(80, 48)
            .with_default_light()
            .on_change()
            .build(),
    )
    .expect("builder creates a prepared viewer loop");

    assert_eq!(viewer.renderer().render_mode(), scena::RenderMode::OnChange);
    assert!(viewer.scene().active_camera().is_some());

    let first = viewer
        .render_next_frame()
        .expect("first viewer-loop frame renders");
    assert!(!first.skipped);
    assert!(first.draw_calls > 0);

    let idle = viewer
        .render_next_frame()
        .expect("unchanged viewer-loop frame skips");
    assert!(idle.skipped);
    assert_eq!(idle.draw_calls, 0);
    assert_eq!(viewer.renderer().stats().skipped_frames, 1);

    assert!(
        viewer
            .renderer()
            .screenshot_rgba8()
            .rgba8()
            .chunks_exact(4)
            .any(|pixel| pixel[0] != 0 || pixel[1] != 0 || pixel[2] != 0),
        "viewer loop should keep the first rendered frame visible across idle skips"
    );
}

#[test]
fn headless_gltf_viewer_builder_with_environment_loads_explicit_path() {
    // Phase 5B step 1: `with_environment(path)` accepts an explicit asset
    // path and overrides the default-environment toggle. Loading the
    // bundled neutral-studio fixture should attach an environment handle
    // distinct from `Assets::default_environment` only when the path is
    // different from the bundled one — for the same path it returns the
    // cached default handle, which is still a positive signal that the
    // override path took.
    let first = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(48, 32)
            .with_environment("tests/assets/environment/neutral-studio.fixture.txt")
            .render(),
    )
    .expect("builder accepts explicit environment paths");

    assert!(
        first.renderer().environment().is_some(),
        "with_environment must attach an environment handle to the renderer"
    );
    assert_eq!(first.renderer().stats().environments, 1);
}

#[test]
fn headless_gltf_viewer_with_environment_overrides_default_environment_call_order() {
    // Phase 5B step 1: setting `with_default_environment` then
    // `with_environment(path)` must end up using the explicit path —
    // confirming the override semantics documented on the builder.
    let first = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(32, 32)
            .with_default_environment()
            .with_environment("tests/assets/environment/neutral-studio.fixture.txt")
            .render(),
    )
    .expect("builder accepts explicit environment after default toggle");

    assert!(first.renderer().environment().is_some());
}

#[test]
fn headless_gltf_viewer_snapshot_rgba8_and_capabilities_accessors_match_renderer() {
    // Phase 5B step 1: `snapshot_rgba8` and `capabilities` are convenience
    // accessors that forward to the renderer; their results must match
    // `renderer.frame_rgba8()` / `renderer.capabilities()` so callers can
    // skip the indirection in screenshot + capability-gate code paths.
    let viewer = pollster::block_on(
        scena::headless_gltf_viewer("tests/assets/gltf/mesh_material_vertex_color_scene.gltf")
            .size(16, 16)
            .with_default_light()
            .build(),
    )
    .expect("viewer builder produces a prepared viewer");

    let mut viewer = viewer;
    viewer.render_next_frame().expect("first frame renders");

    assert_eq!(viewer.snapshot_rgba8(), viewer.renderer().frame_rgba8());
    assert_eq!(viewer.capabilities(), viewer.renderer().capabilities());
}