unlit3d_examples/scenes/

mod.rs

//! The example's selectable scenes.
//!
//! A scene is a [`SceneDef`]: the fixed size and frame count its snapshots
//! were captured at, what offscreen target it draws into, and a
//! [`build`](SceneDef::build) that populates an ECS world. The world it builds is the ordinary one every
//! frame loop drives — the frame's context and [`Renderer`] are already in it
//! — so the windowed run and the snapshot tests differ only in what they bind
//! they do with the result.
//!
//! A scene's [`SceneControl`] carries the per-frame behaviour (an animated
//! sequence, the orbit of the camera) and the snapshot each frame verifies
//! against in the snapshot tests. Scenes without snapshots — the windowed
//! example's own — report none.
//!
//! Every scene here is ported from a GPU snapshot test that used to live in
//! `crates/unlit3d/tests`, which is why its size, frame count and content are
//! exactly what that test froze: the stored snapshots in the
//! `unlit3d_asset_files` submodule still verify them.

pub mod animated;
pub mod custom_pipeline;
pub mod gltf;
pub mod instanced_skinned_morph;
pub mod lit;
pub mod lit_clusters;
pub mod mesh_and_ui;
pub mod mesh_topologies;
pub mod morphed;
pub mod outline;
pub mod skinned;
pub mod spin_cube;
pub mod transparent;
pub mod ui_only;

use unlit_ecs::{Bundle, DynamicBundle, bundle};
use unlit_wgpu::pipeline::{DepthStencilPolicy, LitOptions};
use unlit_wgpu::scene::ViewportRect;
use unlit3d::prelude::*;

/// Advances a scene's behaviour by one frame.
///
/// `frame` counts the frames the scene has drawn; the scenes that animate
/// through a fixed sequence loop it, so a windowed scene keeps moving after
/// the sequence that produced its snapshots ends. `delta` is the seconds since
/// the previous frame. `size` is the render target's size in physical pixels,
/// which a scene reads here rather than capturing the size it was built at: a
/// camera whose projection has to follow the target's aspect is re-aimed from
/// this every frame, so a window that changes shape never stretches the scene.
pub type Advance = Box<dyn FnMut(&mut World, u32, f32, (u32, u32))>;

/// Names the snapshot a frame verifies against, if it has one.
pub type Snapshot = Box<dyn Fn(u32) -> Option<String>>;

/// Builds a scene's world content and returns its per-frame behaviour.
///
/// The pass is the frame pass the scene draws through: its sources hang in the
/// pass's scope, so what they own is what the pass records.
pub type Build =
    fn(&mut World, RenderContext, Entity, Option<Entity>, (u32, u32), SceneOptions) -> SceneControl;

/// How the example's runner drives one scene.
///
/// The two closures are what remains of the scene once its world is built: the
/// behaviour that advances every frame, and the snapshot the scene's test
/// compares each frame against.
pub struct SceneControl {
    /// Advance the scene's behaviour by `delta` seconds.
    pub advance: Advance,
    /// The snapshot the scene's test compares frame `frame` against, if any.
    ///
    /// The name is relative to the snapshot directory, exactly as the test the
    /// scene was ported from stored it.
    pub snapshot: Snapshot,
}

/// One selectable scene.
///
/// The fields the snapshot tests draw the scene at — [`Self::size`],
/// [`Self::frames`], [`Self::samples`] and [`Self::depth`] — reproduce the
/// test the scene came from, so a captured frame is comparable with the
/// snapshot it was stored against. The windowed path draws at the window's own
/// size instead, and only [`Self::build`] is shared.
pub struct SceneDef {
    /// The scene's stable id, used by `--scene <ID>`.
    pub id: &'static str,
    /// A short title for the GUI and the scene list.
    pub title: &'static str,
    /// What the scene shows, one line for the GUI.
    pub description: &'static str,
    /// The render target size the scene's snapshots were captured at.
    pub size: (u32, u32),
    /// The aspect the windowed path keeps the scene's 3D content at, as a
    /// reference resolution, or `None` for a scene that draws no 3D content and
    /// so has an aspect to keep.
    ///
    /// A scene that declares one is drawn through the largest rectangle of that
    /// aspect that fits the window, so a wide window and a narrow one show the
    /// same picture — the wide one larger — instead of the wide one showing
    /// more. The snapshot tests ignore this and draw at [`Self::size`], which
    /// the snapshots were captured at.
    ///
    /// A UI-only scene declares none: an interface belongs on the whole window,
    /// and letterboxing it would put bars around a panel that has no aspect of
    /// its own.
    pub baseline: Option<(u32, u32)>,
    /// The colour the scene's pass clears to, or `None` to clear to the default.
    ///
    /// A scene whose picture is painted over a particular backdrop declares
    /// one; every other scene leaves its pass at the default clear.
    pub clear: Option<wgpu::Color>,
    /// How many frames the snapshot tests draw before finishing.
    pub frames: u32,
    /// How long each frame stays on screen in the windowed loop, in seconds,
    /// or `None` for a scene that animates continuously from the frame delta.
    ///
    /// The snapshot tests ignore this and draw the frames back to back, so a
    /// capture stays reproducible; the windowed path uses it so a scene whose
    /// frames were frozen as a sequence plays at a watchable pace rather than
    /// as fast as the display refreshes.
    pub step_seconds: Option<f32>,
    /// The sample count of the offscreen target the snapshot tests bind.
    pub samples: u32,
    /// Whether that offscreen target carries a depth-stencil attachment.
    pub depth: bool,
    /// Whether the scene draws UI panels of its own.
    ///
    /// The snapshot tests mount a UI source to drive them; the windowed path
    /// always mounts one, for the scene selector.
    pub ui: bool,
    /// Whether the scene's UI animates against egui's clock.
    ///
    /// A scene whose snapshots were captured with the clock suppressed — the
    /// example's own, whose panels live in egui windows — declares `true`, so
    /// the snapshot tests zero egui's animation time for it. The ported test
    /// scenes were captured with the clock live, and declare `false`.
    pub reproducible_ui: bool,
    /// Build the scene's world content and return its per-frame behaviour.
    ///
    /// The world already holds the frame's context, the renderer resource
    /// entity and the pass the scene draws through; the scene spawns its
    /// sources, meshes, camera and entities, sources inside the pass.
    ///
    /// The entity is the UI source the shell mounted for the scene, when the
    /// run has one: a panel the scene draws hangs in that source's scope, so
    /// the scene spawns it there rather than at the root — a source draws the
    /// subtree it owns and nothing beside it.
    pub build: Build,
}

/// Every selectable scene, in the order the GUI lists and `--scene all` runs
/// them.
pub static SCENES: &[&SceneDef] = &[
    &spin_cube::SCENE,
    &ui_only::SCENE,
    &mesh_and_ui::SCENE,
    &animated::SCENE,
    &skinned::SCENE,
    &morphed::SCENE,
    &instanced_skinned_morph::SCENE,
    &lit::SCENE,
    &lit_clusters::CLUSTER_SCENE,
    &gltf::SCENE,
    &mesh_topologies::SCENE,
    &transparent::SCENE,
    &custom_pipeline::SCENE,
    &outline::SCENE,
    &outline::MSAA_SCENE,
];

/// The scene whose id is `id`, if any.
pub fn by_id(id: &str) -> Option<&'static SceneDef> {
    SCENES.iter().copied().find(|scene| scene.id == id)
}

/// The scene the example runs when none is asked for.
pub fn default() -> &'static SceneDef {
    &spin_cube::SCENE
}

/// A table of every scene, for `--list-scenes` and `--help`.
pub fn list_text() -> String {
    let mut text = String::from("Scenes:\n");
    for scene in SCENES {
        text.push_str(&format!("  {:<22} {}\n", scene.id, scene.description));
    }
    text
}

/// What a scene is built with.
#[derive(Clone, Copy)]
pub struct SceneOptions {
    /// Mount the scene's own UI panels.
    pub ui: bool,
    /// Mount the windowed shell's scene-selector panel.
    pub selector: bool,
    /// Suppress everything egui animates against the clock, so a captured
    /// frame does not depend on when it was drawn.
    pub reproducible: bool,
    /// Keep the scene's declared [`SceneDef::baseline`] aspect by drawing its
    /// content into the largest region of that aspect the target fits.
    ///
    /// The windowed path sets this so a window of any shape shows the same
    /// picture, larger or smaller. The snapshot tests clear it: a capture draws
    /// at the scene's own size, which its snapshots were taken at.
    pub letterbox: bool,
    /// Seconds each frame of a fixed-sequence scene stays on screen, or `None`
    /// to advance the sequence once per drawn frame.
    ///
    /// A test passes `None` so it draws exactly the frames the snapshots
    /// froze; a windowed run passes the scene's own [`SceneDef::step_seconds`]
    /// so the sequence plays at a watchable pace.
    pub sequence_step: Option<f32>,
}

// ---------------------------------------------------------------------------
// Shared geometry and camera helpers
//
// These are the fixtures the ported tests shared, restated here because the
// example cannot reach into a test crate.
// ---------------------------------------------------------------------------

/// The size the ported test scenes draw at, matching their snapshots.
pub const TEST_SIZE: (u32, u32) = (256, 192);

/// The aspect the windowed example keeps its 3D content to, as a reference
/// resolution.
///
/// Whatever the window's shape, a scene that declares this baseline is drawn
/// through the largest rectangle of this aspect that fits the target, so a wide
/// screen and a narrow one show the same picture — the wide one larger — rather
/// than the wide one showing more and the narrow one cropping it.
///
/// The resolution itself is only the reference the aspect comes from; the
/// content is scaled to whatever the target allows. It matches the default
/// window's size and the 4:3 ratio every scene's snapshots were captured at.
pub const BASELINE_SIZE: (u32, u32) = (960, 720);

/// The format the test scenes render into: sRGB, like the example's window.
pub const TEST_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8UnormSrgb;

/// Seconds each frame of a fixed-sequence scene stays on screen in the
/// windowed loop.
///
/// The ported test scenes froze an animation as a handful of frames, so
/// playing them one per displayed frame would flash past in a fraction of a
/// second. The snapshot tests ignore this and draw the frames back to back.
pub const SEQUENCE_STEP: f32 = 0.5;

/// The raw channels of one mesh: `(positions, uvs, colors, indices)`.
pub type RawMesh = (Vec<[f32; 3]>, Vec<[f32; 2]>, Vec<[u8; 4]>, Vec<u32>);

/// A unit cube centred at the origin, returned as
/// `(positions, uvs, colors, indices)`.
///
/// The colors are quantized to the `Unorm8x4` width the vertex stream stores,
/// exactly as the tests uploaded them.
pub fn cube() -> RawMesh {
    cube_with_normals().0
}

/// The same cube, beside one outward normal per vertex.
///
/// A lit pipeline shades with the normal, and the unlit one derives the
/// normal it draws with from the fragment's derivatives, so only the scenes
/// that shade need to carry one.
pub fn cube_with_normals() -> (RawMesh, Vec<[f32; 3]>) {
    let faces = [
        ([-1.0f32, 0.0, 0.0], [0.0f32, 0.0, 1.0]),
        ([1.0, 0.0, 0.0], [0.0, 0.0, -1.0]),
        ([0.0, -1.0, 0.0], [1.0, 0.0, 0.0]),
        ([0.0, 1.0, 0.0], [1.0, 0.0, 0.0]),
        ([0.0, 0.0, -1.0], [-1.0, 0.0, 0.0]),
        ([0.0, 0.0, 1.0], [1.0, 0.0, 0.0]),
    ];

    let mut positions = Vec::new();
    let mut uvs = Vec::new();
    let mut colors = Vec::new();
    let mut normals = Vec::new();
    let mut indices = Vec::new();

    for (face_normal, tangent) in faces {
        let base = positions.len() as u32;
        let face_normal = glam::Vec3::from(face_normal);
        let tangent = glam::Vec3::from(tangent);
        let bitangent = face_normal.cross(tangent);
        for (u, v) in [(-1.0f32, -1.0f32), (1.0, -1.0), (1.0, 1.0), (-1.0, 1.0)] {
            let position = face_normal + tangent * u + bitangent * v;
            positions.push(position.to_array());
            normals.push(face_normal.to_array());
            uvs.push([(u + 1.0) * 0.5, (v + 1.0) * 0.5]);
            let color = (position + 1.0) * 0.5;
            colors.push([color.x, color.y, color.z, 1.0]);
        }
        indices.extend([base, base + 1, base + 2, base, base + 2, base + 3]);
    }

    // The stream stores colors as `Unorm8x4`, so quantize once here rather
    // than carrying a float copy through the scene.
    let colors = unlit_wgpu::mesh::quantize_colors(&colors).collect();
    ((positions, uvs, colors, indices), normals)
}

/// A rectangle as the mesh allocator takes it.
pub struct Grid {
    /// One position per vertex.
    pub positions: Vec<[f32; 3]>,
    /// Per-vertex normals, or `None` for a surface the fragment shades from the
    /// normals its own positions give it.
    pub normals: Option<Vec<[f32; 3]>>,
    /// One texture coordinate per vertex.
    pub uvs: Vec<[f32; 2]>,
    /// The one color every vertex of the surface carries.
    pub albedo: unlit_wgpu::mesh::CompressedColor,
    /// Triangles over the vertices, three indices each.
    pub indices: Vec<u32>,
}

/// A rectangle centred on `origin`, `right` wide and `up` tall, split into
/// `segments` quads along each of them, wound so its front face is the side
/// the cross product of `right` and `up` points at.
pub fn grid(
    origin: glam::Vec3,
    right: glam::Vec3,
    up: glam::Vec3,
    size: (f32, f32),
    segments: (u32, u32),
) -> Grid {
    let (columns, rows) = (segments.0.max(1), segments.1.max(1));
    let mut positions = Vec::with_capacity(((columns + 1) * (rows + 1)) as usize);
    let mut uvs = Vec::with_capacity(positions.capacity());
    for row in 0..=rows {
        let v = row as f32 / rows as f32;
        for column in 0..=columns {
            let u = column as f32 / columns as f32;
            positions.push(
                (origin + right * (size.0 * (u - 0.5)) + up * (size.1 * (v - 0.5))).to_array(),
            );
            uvs.push([u, 1.0 - v]);
        }
    }
    let mut indices = Vec::with_capacity((columns * rows * 6) as usize);
    let stride = columns + 1;
    for row in 0..rows {
        for column in 0..columns {
            let corner = row * stride + column;
            // Wound right then up, which is the order the cross product of
            // `right` and `up` puts on the front face.
            indices.extend([
                corner,
                corner + 1,
                corner + stride + 1,
                corner,
                corner + stride + 1,
                corner + stride,
            ]);
        }
    }
    // White rather than a tint: these surfaces are coloured by the light that
    // reaches them, and a tinted albedo would be read as the lighting itself.
    Grid {
        positions,
        normals: None,
        uvs,
        albedo: unlit_wgpu::mesh::quantize_colors(&[[1.0f32, 1.0, 1.0, 1.0]])
            .next()
            .expect("one color is quantized"),
        indices,
    }
}

/// Upload a rectangle and return its mesh.
pub fn allocate_surface(
    world: &mut World,
    source_entity: Entity,
    key: &unlit3d::lit::LitPipelineKey,
    grid: &Grid,
) -> GpuMesh {
    let colors = vec![grid.albedo; grid.positions.len()];
    with_mesh_source(world, source_entity, |source, world| {
        source.allocate_lit_mesh(
            world,
            &key.options,
            LitMeshDesc {
                positions: &grid.positions,
                uvs: Some(&grid.uvs),
                colors: Some(&colors),
                normals: grid.normals.as_deref(),
                indices: Some(&grid.indices),
                ..Default::default()
            },
        )
    })
}

/// One surface of the scene: the mesh and the pipeline it is drawn with.
pub struct LitSurface {
    /// The mesh this surface draws.
    pub mesh: GpuMesh,
    /// The pipeline its instances are drawn with.
    pub pipeline: GpuRenderPipeline,
}

impl Bundle for LitSurface {
    fn into_bundle(self) -> DynamicBundle {
        bundle![Transform::default(), self.mesh, self.pipeline]
    }
}

/// A light and the transform it shines from.
///
/// The light reads nothing of the transform but its own packing, so the two are
/// spawned together: a light without one shines from the origin along the
/// world's negative z.
pub struct PlacedLight {
    /// The light itself, of whichever kind it is.
    pub light: LightSource,
    /// Where the light sits, which a directional light ignores.
    pub translation: glam::Vec3,
    /// The orientation the light shines along.
    pub rotation: glam::Quat,
}

impl PlacedLight {
    /// A light at `translation` aimed at `target`.
    ///
    /// Every built-in light shines along its transform's negative z, so aiming
    /// one is turning that axis onto the direction it has to shine in.
    pub fn aiming(light: LightSource, translation: glam::Vec3, target: glam::Vec3) -> Self {
        Self {
            light,
            translation,
            rotation: glam::Quat::from_rotation_arc(
                glam::Vec3::NEG_Z,
                (target - translation).normalize(),
            ),
        }
    }
}

impl Bundle for PlacedLight {
    fn into_bundle(self) -> DynamicBundle {
        bundle![
            Transform {
                translation: self.translation,
                rotation: self.rotation,
                scale: glam::Vec3::ONE,
            },
            self.light,
        ]
    }
}
/// The aspect ratio of a `size`-pixel render target.
///
/// Every camera in the example takes its aspect from here rather than from the
/// size its scene was built at, so a target whose shape changes — a browser
/// window being stretched — re-aims instead of stretching.
pub fn aspect_of(size: (u32, u32)) -> f32 {
    size.0 as f32 / size.1.max(1) as f32
}

/// The region of a `target`-pixel render target a `baseline`-aspect scene draws
/// into: the largest rectangle of that aspect that fits, centred.
///
/// The content is scaled to this region instead of to the target, so the target
/// only ever adds bars around the picture — a wide window shows the same view a
/// narrow one does, larger, rather than more of it. A scene whose camera is
/// built for the region's aspect draws undistorted inside it.
pub fn baseline_viewport(baseline: (u32, u32), target: (u32, u32)) -> ViewportRect {
    ViewportRect::fit_aspect(aspect_of(baseline), target.0.max(1), target.1.max(1))
}

/// The size a scene's camera should be built for when its content is drawn into
/// the `baseline`-aspect part of a `target`-pixel render target.
///
/// This is the letterboxed region's own size, in whole pixels, so a camera
/// taking its aspect from it matches what the viewport scales into place: the
/// two agree exactly rather than approximately, which is what keeps a cube
/// cubic. A camera built for the target's own size would shear the picture
/// back out to the target's aspect.
pub fn content_size(baseline: (u32, u32), target: (u32, u32)) -> (u32, u32) {
    let viewport = baseline_viewport(baseline, target);
    (viewport.width as u32, viewport.height as u32)
}

/// The eye [`camera_view`] looks from.
pub const DEFAULT_EYE: glam::Vec3 = glam::Vec3::new(0.0, 1.2, 3.2);
/// The point [`camera_view`] looks at.
pub const DEFAULT_TARGET: glam::Vec3 = glam::Vec3::new(0.0, 0.2, 0.0);

/// Camera looking at [`DEFAULT_TARGET`] from [`DEFAULT_EYE`].
///
/// Uses reverse-z infinite perspective matching the built-in pipeline's
/// `CompareFunction::Greater` and `depth_clear = 0.0`.
pub fn camera_view(size: (u32, u32)) -> Camera {
    camera_looking_at(DEFAULT_EYE, DEFAULT_TARGET, size)
}

/// A camera at `eye` looking at `target`, with the same reverse-z infinite
/// perspective as [`camera_view`].
pub fn camera_looking_at(eye: glam::Vec3, target: glam::Vec3, size: (u32, u32)) -> Camera {
    let projection = glam::camera::rh::proj::directx::perspective_infinite_reverse(
        60f32.to_radians(),
        aspect_of(size),
        0.1,
    );
    let view = glam::camera::rh::view::look_at_mat4(eye, target, glam::Vec3::Y);
    Camera {
        view_from_world: view,
        clip_from_view: projection,
        active: true,
    }
}

/// Re-aim `entity`'s camera at `target` from `eye` for a frame of `size`.
///
/// The camera hangs in `scope`, the source that draws it, so the view is its
/// own. The scenes whose camera never moves still call this every frame,
/// so their projection keeps the frame's own aspect. It is what a scene does in
/// [`SceneControl::advance`](SceneControl) instead of capturing the size it was
/// built at.
pub fn aim_camera(
    world: &mut World,
    scope: Entity,
    entity: Entity,
    eye: glam::Vec3,
    target: glam::Vec3,
    size: (u32, u32),
) {
    let mut camera = camera_looking_at(eye, target, size);
    world
        .scope(scope)
        .expect("the scope is alive")
        .query_one::<&mut Camera>(entity)
        .map(|mut current| {
            camera.active = current.get().active;
            *current.get() = camera;
        })
        .expect("the entity carries a camera");
}

/// Default options for the ported ECS scenes: per-instance transform and tint,
/// no texture, no MSAA, with reverse-z depth.
///
/// The options are pure policy, so they say nothing about the geometry a draw
/// carries: which vertex channels a mesh packs follows the slices its caller
/// uploads, and which of them a draw reads follows the mesh it draws. The tint
/// rides the same per-instance record as the transform, so a draw that reads
/// instances reads the tint too.
pub fn default_options() -> LitOptions {
    LitOptions {
        primitive: wgpu::PrimitiveState {
            cull_mode: Some(wgpu::Face::Back),
            ..Default::default()
        },
        depth_stencil: DepthStencilPolicy::default(),
        blend: None,
        write_mask: wgpu::ColorWrites::ALL,
        // These scenes state no lights, so their variants draw their base
        // colour unchanged.
        unlit: true,
        ..LitOptions::standard()
    }
}

/// A rig of `joint_count` joints, all at rest, returned as joint matrices.
///
/// The identity pose deforms nothing: a vertex's weights sum to one, so the
/// weighted sum of identity matrices is the vertex itself.
pub fn rest_pose(joint_count: usize) -> Vec<JointMatrix> {
    vec![glam::Mat4::IDENTITY; joint_count]
}

/// A two-joint skin that bends a mesh about its own base.
///
/// The lower joint is the base and stays at rest; the upper one rotates about
/// the mesh's lowest point, and every vertex is weighted between them by how
/// high it sits, so the mesh bends rather than shears. The weights exercise the
/// four-lane weighted sum the shader computes.
///
/// The joint stream and weights are what a mesh is uploaded with; the matrices
/// are the pose an entity carries, which [`Self::pose`] builds.
pub struct BendSkin {
    /// Four joint indices per vertex: the base and the bending joint.
    pub joints: Vec<[u16; 4]>,
    /// Four weights per vertex, summing to one.
    pub weights: Vec<[f32; 4]>,
    /// The angle the bending joint is rotated by.
    angle: f32,
    /// The height the bending joint pivots about, in the mesh's own space.
    pivot: f32,
}

impl BendSkin {
    /// Skin `positions` to two joints, splitting each vertex by its height.
    pub fn new(positions: &[[f32; 3]], angle: f32) -> Self {
        let (min, max) = positions.iter().fold(
            (f32::INFINITY, f32::NEG_INFINITY),
            |(min, max), position| (min.min(position[1]), max.max(position[1])),
        );
        let height = (max - min).max(f32::EPSILON);
        let (joints, weights) = positions
            .iter()
            .map(|position| {
                let t = ((position[1] - min) / height).clamp(0.0, 1.0);
                ([0u16, 1, 0, 0], [1.0 - t, t, 0.0, 0.0])
            })
            .unzip();
        Self {
            joints,
            weights,
            angle,
            pivot: min,
        }
    }

    /// Replace the bending joint's rotation, which pivots about the mesh's
    /// lowest point rather than its origin.
    pub fn set_angle(&mut self, angle: f32) {
        self.angle = angle;
    }

    /// The pose the two joints are at, ready to attach to an entity.
    pub fn pose(&self) -> SkinPose {
        let mut matrices = rest_pose(2);
        matrices[1] = glam::Mat4::from_translation(glam::Vec3::Y * self.pivot)
            * glam::Mat4::from_rotation_z(self.angle)
            * glam::Mat4::from_translation(glam::Vec3::Y * -self.pivot);
        SkinPose { matrices }
    }
}

/// The displacement of the two morph targets the deformed scenes use, packed
/// the way a mesh stores it: per vertex, one target after the other, three
/// components each.
///
/// The first target tapers the cube's top to a point, the second widens its
/// base.
pub fn morph_deltas(positions: &[[f32; 3]]) -> MorphDeltas {
    let mut deltas = Vec::with_capacity(positions.len() * 2 * 3);
    for position in positions {
        let height = (position[1] + 1.0) * 0.5;
        deltas.extend_from_slice(&[
            -position[0] * height * 0.7,
            0.0,
            -position[2] * height * 0.7,
        ]);
        let height = (1.0 - position[1]) * 0.5;
        deltas.extend_from_slice(&[position[0] * height * 0.6, 0.0, position[2] * height * 0.6]);
    }
    MorphDeltas {
        deltas,
        target_count: 2,
    }
}

/// Spawn `bundle` into `scope`'s subtree.
///
/// A scene's content hangs under the source that draws it: a source renders
/// the subtree it owns, so an entity spawned beside the source is one no frame
/// of it shows.
pub fn spawn_in<B: unlit_ecs::Bundle>(world: &mut World, scope: Entity, bundle: B) -> Entity {
    world
        .scope_mut(scope)
        .expect("the scope is alive")
        .spawn(bundle)
}

/// Spawn `bundle` into the world's shared subtree.
///
/// State every source of a scene reads — the input batches — belongs here: a
/// source's own scope holds what it draws, and one beside it would hold what
/// the other cannot see.
pub fn spawn_shared<B: unlit_ecs::Bundle>(world: &mut World, bundle: B) -> Entity {
    let shared = world.shared();
    world
        .scope_mut(shared)
        .expect("the shared scope exists")
        .spawn(bundle)
}

/// Despawn `entity` and its subtree, through the scope that owns it.
pub fn despawn_in(world: &mut World, scope: Entity, entity: Entity) {
    world
        .scope_mut(scope)
        .expect("the scope named in the scene")
        .despawn(entity)
        .expect("the scene owns the entity it despawns");
}

/// Run `f` on the world's `MeshSource`, which lives on the source entity.
///
/// A shared-world entry point, so the scene's own `&mut World` can
/// reborrow it next to the mutable borrow of the source.
pub fn with_mesh_source<R>(
    world: &World,
    source_entity: Entity,
    f: impl FnOnce(&mut MeshSource, &Scope<'_>) -> R,
) -> R {
    // The scope is the source's own, so what its closure reads is the subtree
    // the source draws.
    let scope = world
        .scope(source_entity)
        .expect("the source entity is alive");
    let mut source = scope
        .query_one::<&mut Source>(source_entity)
        .expect("the source entity exists");
    let mesh = source
        .get()
        .as_mut::<MeshSource>()
        .expect("the source is a MeshSource");
    f(mesh, &scope)
}

/// Allocate the unit cube through the source, its vertices offset by `offset`
/// in mesh space.
///
/// The offset is baked into the vertices, so two cubes allocated from
/// different offsets draw differently even at the same transform — which is
/// what tells a mesh apart from the one whose pool range it sits next to.
pub fn allocate_offset_cube_mesh(
    world: &World,
    source_entity: Entity,
    key: &LitPipelineKey,
    offset: glam::Vec3,
) -> GpuMesh {
    let (positions, uvs, colors, indices) = cube();
    let positions = positions
        .into_iter()
        .map(|position| {
            [
                position[0] + offset.x,
                position[1] + offset.y,
                position[2] + offset.z,
            ]
        })
        .collect::<Vec<_>>();
    with_mesh_source(world, source_entity, |source, world| {
        source.allocate_lit_mesh(
            world,
            &key.options,
            LitMeshDesc {
                positions: &positions,
                uvs: Some(&uvs),
                colors: Some(&colors),
                indices: Some(&indices),
                ..Default::default()
            },
        )
    })
}

/// Free `mesh` through the source, releasing its pool ranges.
pub fn remove_mesh(world: &World, source_entity: Entity, mesh: GpuMesh) {
    with_mesh_source(world, source_entity, |source, _| source.remove_mesh(mesh));
}