unlit3d_examples/scenes/

transparent.rs

//! The transparent, z-sorted scene: overlapping translucent panes composite in
//! draw order.
//!
//! The other scenes draw opaque geometry, so the only blending they exercise is
//! the UI's own. This scene is the one that pins the unlit pipeline's
//! transparent path: three translucent panes overlap, and what the middle of
//! that overlap looks like depends on two things at once — that the draws are
//! ordered back to front, and that the blend state frames the shader's
//! straight-alpha output correctly. Either one wrong changes the pixels, which
//! is what the snapshot freezes.
//!
//! The panes carry [`ZSortedDrawing`], so the renderer draws them after the
//! opaque cubes and sorts them by camera distance rather than by registration
//! order. They are spawned in an order that is deliberately *not* their draw
//! order, so a scene that lost the sort would composite them the other way
//! round and fail the snapshot rather than happening to look right.

use super::{SceneControl, SceneDef, SceneOptions, TEST_SIZE, camera_looking_at};
use unlit_ecs::{Bundle, DynamicBundle, bundle};
use unlit3d::prelude::*;

/// How far in front of the panes the camera sits.
///
/// The panes are spread along the view direction, so their camera distances
/// differ by enough that the sort is unambiguous.
const CAMERA_EYE: glam::Vec3 = glam::Vec3::new(0.0, 0.6, 3.2);

/// The point the camera looks at.
const CAMERA_TARGET: glam::Vec3 = glam::Vec3::new(0.0, 0.0, 0.0);

/// The tint of one pane, where it sits, and how far along the view direction.
///
/// The panes are offset sideways as well as in depth, so they overlap in
/// bands: one region shows each pane alone, another two of them, and the
/// middle all three. That is what makes the snapshot discriminate — a wrong
/// sort or a wrong blend state changes the tint of the overlap bands, not just
/// the overall brightness.
///
/// The order of this table is the order the panes are drawn in after the sort
/// — farthest first — so drawing them as declared, or reversed, would disagree
/// with it.
const PANES: [(glam::Vec4, f32, f32); 3] = [
    // Farthest: red.
    (glam::Vec4::new(1.0, 0.1, 0.1, 0.6), -0.85, -0.7),
    // Middle: green.
    (glam::Vec4::new(0.1, 1.0, 0.15, 0.6), 0.0, 0.0),
    // Nearest: blue.
    (glam::Vec4::new(0.15, 0.3, 1.0, 0.6), 0.85, 0.7),
];

/// The opaque cube behind the panes, tinted so the composite has something to
/// blend against that is not the clear colour alone.
const BACKDROP_TINT: glam::Vec4 = glam::Vec4::new(0.85, 0.8, 0.35, 1.0);

/// The opaque cube the panes composite over.
///
/// It is drawn with depth writes, so it sits behind the panes rather than
/// blending with them.
struct Backdrop {
    mesh: GpuMesh,
    pipeline: GpuRenderPipeline,
}

impl Bundle for Backdrop {
    fn into_bundle(self) -> DynamicBundle {
        bundle![
            Transform {
                translation: glam::Vec3::new(0.0, 0.0, -1.6),
                scale: glam::Vec3::splat(1.1),
                ..Default::default()
            },
            InstanceColor::new(BACKDROP_TINT),
            self.mesh,
            self.pipeline,
        ]
    }
}

/// One translucent pane: the shared mesh, tinted and placed where it blends.
///
/// The pane is sorted by camera distance, which is what [`ZSortedDrawing`] asks
/// for; without it the panes would composite in registration order.
struct Pane {
    tint: glam::Vec4,
    translation: glam::Vec3,
    mesh: GpuMesh,
    pipeline: GpuRenderPipeline,
}

impl Bundle for Pane {
    fn into_bundle(self) -> DynamicBundle {
        bundle![
            Transform {
                translation: self.translation,
                rotation: glam::Quat::from_rotation_y(0.35),
                scale: glam::Vec3::new(1.05, 1.05, 0.05),
            },
            InstanceColor::new(self.tint),
            self.mesh,
            self.pipeline,
            ZSortedDrawing,
        ]
    }
}

/// The scene: opaque cubes behind three overlapping translucent panes.
pub static SCENE: SceneDef = SceneDef {
    id: "transparent",
    title: "Transparent z-sorted panes",
    description: "translucent panes composited back to front over opaque cubes",
    size: TEST_SIZE,
    baseline: Some(TEST_SIZE),
    clear: None,
    frames: 1,
    step_seconds: None,
    samples: 1,
    depth: true,
    ui: false,
    reproducible_ui: false,
    build,
};

/// Build the transparent scene's world content.
fn build(
    world: &mut World,
    context: RenderContext,
    pass: Entity,
    _ui: Option<Entity>,
    size: (u32, u32),
    _options: SceneOptions,
) -> SceneControl {
    let mut source = MeshSource::new(&world.root_scope(), context);
    source.register_lit_family(&world.root_scope());

    // Two variants of the same unlit pipeline: the opaque one every other
    // scene draws with, and a translucent one that blends straight-alpha
    // output over the target without writing depth.
    //
    // Depth writes are off because a blended pane must not hide the pane
    // behind it, but depth *testing* stays on: the panes are composited among
    // themselves by their draw order, and an opaque cube in front of them must
    // still occlude them.
    // Both variants read the instance tint: the backdrop is tinted through it,
    // and every pane's tint is its own.
    let opaque_key = LitPipelineKey::new(super::default_options());
    let mut translucent = super::default_options();
    translucent.blend = Some(wgpu::BlendState {
        color: wgpu::BlendComponent {
            src_factor: wgpu::BlendFactor::SrcAlpha,
            dst_factor: wgpu::BlendFactor::OneMinusSrcAlpha,
            operation: wgpu::BlendOperation::Add,
        },
        alpha: wgpu::BlendComponent {
            src_factor: wgpu::BlendFactor::One,
            dst_factor: wgpu::BlendFactor::OneMinusSrcAlpha,
            operation: wgpu::BlendOperation::Add,
        },
    });
    // A pane is seen from the front, so culling its back face keeps it to one
    // blended layer; drawing both faces of the thin slab would blend it twice.
    translucent.primitive.cull_mode = Some(wgpu::Face::Back);
    // Depth *testing* stays on, so an opaque cube in front still occludes a
    // pane; writes are off because a blended pane must not hide the pane
    // behind it. The panes are composited among themselves by draw order.
    translucent.depth_stencil.depth_write_enabled = false;
    // The pane mesh carries positions and indices only: no UV, no color. The
    // draw derives exactly those channels back off the mesh, and each pane's
    // tint is its own instance colour, so one mesh serves all of them.
    let translucent_key = LitPipelineKey::new(translucent);

    let source_entity = world
        .scope_mut(pass)
        .expect("the pass is alive")
        .spawn(bundle![Source::new(source)]);

    let (positions, uvs, colors, indices) = super::cube();

    // The backdrop the panes composite over: an opaque cube drawn with depth
    // writes, so it also occludes nothing that should be in front of it.
    let backdrop = super::with_mesh_source(world, source_entity, |source, world| {
        source.allocate_lit_mesh(
            world,
            &opaque_key.options,
            LitMeshDesc {
                positions: &positions,
                uvs: Some(&uvs),
                colors: Some(&colors),
                indices: Some(&indices),
                ..Default::default()
            },
        )
    });

    // The panes: one mesh, three instances, each tinted and placed by its
    // instance stream.
    let pane_mesh = super::with_mesh_source(world, source_entity, |source, world| {
        source.allocate_lit_mesh(
            world,
            &translucent_key.options,
            LitMeshDesc {
                positions: &positions,
                uvs: None,
                colors: None,
                indices: Some(&indices),
                ..Default::default()
            },
        )
    });

    let camera_entity = super::spawn_in(
        world,
        source_entity,
        bundle![camera_looking_at(CAMERA_EYE, CAMERA_TARGET, size)],
    );

    super::spawn_in(
        world,
        source_entity,
        Backdrop {
            mesh: backdrop,
            pipeline: GpuRenderPipeline::new(opaque_key),
        },
    );

    // Spawned nearest-first on purpose: registration order is not draw order
    // for a z-sorted entity, so only a correct sort composites them red,
    // green, blue from back to front.
    for (tint, x, z) in PANES.iter().rev() {
        super::spawn_in(
            world,
            source_entity,
            Pane {
                tint: *tint,
                translation: glam::Vec3::new(*x, 0.0, *z),
                mesh: pane_mesh.clone(),
                pipeline: GpuRenderPipeline::new(translucent_key.clone()),
            },
        );
    }

    SceneControl {
        // A single frame: the composite is static, so only the camera's aspect
        // is advanced, keeping a resized window from stretching the panes.
        advance: Box::new(move |world, _frame, _delta, frame_size| {
            super::aim_camera(
                world,
                source_entity,
                camera_entity,
                CAMERA_EYE,
                CAMERA_TARGET,
                frame_size,
            );
        }),
        // The first frame is the snapshot; whichever frame is drawn, the
        // picture is the same.
        snapshot: Box::new(|frame| (frame == 0).then(|| "transparent.webp".to_owned())),
    }
}