Struct SoundCue 

pub struct SoundCue<S: Sounds> { /* private fields */ }

A sound and how to play it.

Every knob has a default, so a bare vocabulary value plays as it was loaded.

Implementations

impl<S: Sounds> SoundCue<S>

pub const DEFAULT_RANGE: f32

Range a placed sound is heard at when no call sets it: 50 meters.

pub const DEFAULT_REFERENCE: f32

Distance a placed sound holds its full level within when no call sets it: 1 meter.

pub const DEFAULT_FADE: Duration

Fade a voice takes to come up and go down when no call sets it: as short as it can be without a click.

pub const DEFAULT_GLIDE: Duration = GLIDE

Span a change of gain or position slides over when no call sets it: short enough to follow a moving source, long enough not to click.

pub fn gain(self, gain: f32) -> Self

Plays at gain, a fraction of the level the sound was loaded at; 1.0 as loaded, never less than nothing.

Examples found in repository

examples/sound-lab.rs (line 366)

    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

    /// Declares [`RING_COUNT`] sustains on a ring, each less loud than the
    /// one before it, so the engine's cap plays the loudest of them and the
    /// rest hold no voice while their playback goes on.
    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

    fn sustain_cues(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        let fade = Duration::from_secs_f32(self.cue_fade);
        if self.theme_on {
            ctx.sustain(Sound::Theme.gain(0.5).fade(fade));
        }
        if self.menu_on {
            ctx.sustain(Sound::MenuTheme.gain(0.5).fade(fade));
        }
        if self.pulse_on {
            ctx.sustain(Sound::Pulse.gain(0.3).fade(fade));
        }
    }
}

/// Where the `nth` sustain of the ring stands: around the room, starting
/// behind the listener's back.
fn ring_place(nth: u32) -> Vec3 {
    let turn = TAU * nth as f32 / RING_COUNT as f32;

    Vec3::new(
        turn.sin() * RING_RADIUS,
        SOURCE_HEIGHT,
        turn.cos() * RING_RADIUS,
    )
}

/// The direction the ear pair is offset along — the same side the
/// engine's own pan reads.
fn listener_right(view: View) -> Vec3 {
    (view.target() - view.eye())
        .normalize_or_zero()
        .cross(view.up())
}

/// The clip's duration, with two trim handles and a loop marker, each moved
/// by the pointer's own place rather than by a moving total.
fn duration_bar(
    ui: &mut egui::Ui,
    duration: f32,
    trim_start: &mut f32,
    trim_end: &mut f32,
    loop_from: &mut f32,
) {
    let size = egui::vec2(ui.available_width().min(420.0), 28.0);
    let (rect, _response) = ui.allocate_exact_size(size, egui::Sense::hover());
    let painter = ui.painter();
    painter.rect_filled(rect, 3.0, egui::Color32::from_gray(35));

    let x_of = |seconds: f32| rect.left() + (seconds / duration).clamp(0.0, 1.0) * rect.width();
    let seconds_of = |x: f32| ((x - rect.left()) / rect.width()).clamp(0.0, 1.0) * duration;

    let span = egui::Rect::from_min_max(
        egui::pos2(x_of(*trim_start), rect.top()),
        egui::pos2(x_of(*trim_end), rect.bottom()),
    );
    painter.rect_filled(span, 3.0, egui::Color32::from_rgb(70, 120, 95));

    let start_x = x_of(*trim_start);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "trim-start",
        start_x,
        egui::Color32::from_rgb(230, 200, 80),
    ) {
        *trim_start = seconds_of(x).min(*trim_end);
    }
    let end_x = x_of(*trim_end);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "trim-end",
        end_x,
        egui::Color32::from_rgb(230, 200, 80),
    ) {
        *trim_end = seconds_of(x).max(*trim_start);
    }
    let loop_x = x_of(*loop_from);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "loop-from",
        loop_x,
        egui::Color32::from_rgb(90, 170, 230),
    ) {
        *loop_from = seconds_of(x).clamp(*trim_start, *trim_end);
    }
}

/// One round handle at `x`. Returns the pointer's `x` while a drag holds
/// it.
fn drag_handle(
    ui: &mut egui::Ui,
    bar: egui::Rect,
    salt: &str,
    x: f32,
    color: egui::Color32,
) -> Option<f32> {
    let radius = 6.0;
    let center = egui::pos2(x, bar.center().y);
    let sense_rect = egui::Rect::from_center_size(center, egui::Vec2::splat(radius * 2.5));
    let id = ui.id().with(salt);
    let response = ui.interact(sense_rect, id, egui::Sense::drag());
    ui.painter().circle_filled(center, radius, color);

    response
        .dragged()
        .then(|| response.interact_pointer_pos())
        .flatten()
        .map(|pos| pos.x)
}

impl Game for SoundCheck {
    type Meshes = Shape;
    type Sounds = Sound;
    type InputActions = Controls;
    type Skyboxes = Sky;
    type SurfaceStyles = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    fn tick(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.handle_walk(ctx);
        self.handle_drag(ctx);
    }

    fn frame(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.set_volume(self.master_volume);

        let player = self.player_prev.lerp(self.player, ctx.alpha());
        let ear = Vec3::new(player.x, EYE_HEIGHT, player.y);
        let listener = View::look_at(ear, ear + Vec3::NEG_Z);
        ctx.set_listener(listener);

        ctx.set_camera(Self::camera(player));
        ctx.set_skybox(Sky::Room);
        ctx.set_bloom(0.2);
        ctx.light(Light::directional(Vec3::new(-0.4, -1.0, -0.5), SUN_COLOR).shadow());

        self.draw_room(ctx);
        self.draw_sources(ctx);
        self.draw_listener(ctx, listener);
        self.draw_merge_markers(ctx);
        self.draw_ring(ctx);

        self.sustain_cues(ctx);
        for (index, source) in self.sources.iter().enumerate() {
            if source.enabled {
                ctx.sustain(source.cue().instance(index as u32));
            }
        }
        if self.merge_demo {
            ctx.sustain(Sound::Click.at(MERGE_POS_A).gain(MERGE_GAIN));
            ctx.sustain(Sound::Click.at(MERGE_POS_B).gain(MERGE_GAIN));
        }
        self.sustain_ring(ctx);

        self.side_panel(ctx);
        let (play_once, play_many) = self.one_shot_panel(ctx);

        if play_once {
            ctx.play(self.one_shot_cue());
        }
        if play_many {
            for _ in 0..32 {
                ctx.play(self.one_shot_cue());
            }
        }
    }

pub fn pitch(self, pitch: f32) -> Self

Plays at pitch, a fraction of the rate the sound was loaded at, which moves pitch and speed together; clamped to never go below 0.01 of that rate.

Examples found in repository

examples/sound-lab.rs (line 369)

    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

pub fn at(self, position: Vec3) -> Self

Places the sound at position, which pans it and fades it with distance from the listener.

A sound with no position is heard the same in both ears, however the listener moves.

pub fn range(self, range: f32) -> Self

Fades a placed sound to nothing range meters from the listener; SoundCue::DEFAULT_RANGE until set.

The reference never lies past the range, so a smaller range holds it there.

Examples found in repository

examples/sound-lab.rs (line 368)

    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

    /// Declares [`RING_COUNT`] sustains on a ring, each less loud than the
    /// one before it, so the engine's cap plays the loudest of them and the
    /// rest hold no voice while their playback goes on.
    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

pub fn reference(self, reference: f32) -> Self

Holds a placed sound at full level within reference meters of the listener, past which it falls by the inverse of the distance to nothing at the range; SoundCue::DEFAULT_REFERENCE until set.

A reference past the range is held at the range. One at or under zero is held just above zero.

Examples found in repository

examples/sound-lab.rs (line 367)

    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

    /// Declares [`RING_COUNT`] sustains on a ring, each less loud than the
    /// one before it, so the engine's cap plays the loudest of them and the
    /// rest hold no voice while their playback goes on.
    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

examples/breakout-game.rs (line 522)

    fn bounce_bricks(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        let reach_x = BRICK_HALF_WIDTH + BALL_RADIUS;
        let reach_z = BRICK_HALF_DEPTH + BALL_RADIUS;
        let mut broken = None;

        for brick in self
            .bricks
            .iter_mut()
            .filter(|brick| brick.hits_remaining > 0)
        {
            let dx = self.ball_pos.x - brick.position.x;
            let dz = self.ball_pos.z - brick.position.z;
            if dx.abs() > reach_x || dz.abs() > reach_z {
                continue;
            }

            if reach_x - dx.abs() < reach_z - dz.abs() {
                self.ball_vel.x = if dx < 0.0 {
                    -self.ball_vel.x.abs()
                } else {
                    self.ball_vel.x.abs()
                };
            } else {
                self.ball_vel.z = if dz < 0.0 {
                    -self.ball_vel.z.abs()
                } else {
                    self.ball_vel.z.abs()
                };
            }

            brick.hits_remaining -= 1;
            self.score += 10 * (BRICK_ROWS - brick.row) as u32;
            ctx.play(Sound::Bounce.pitch(BRICK_BOUNCE_PITCH));
            if brick.hits_remaining == 0 {
                ctx.play(
                    Sound::BrickBreak
                        .at(brick.position)
                        .reference(BRICK_BREAK_REFERENCE),
                );
                self.brick_flash = BRICK_FLASH;
                broken = Some((brick.position, BRICK_ROW_COLORS[brick.row]));
            }
            break;
        }

        if let Some((position, color)) = broken {
            self.spawn_sparks(position, color);
        }

        if self.bricks.iter().all(|brick| brick.hits_remaining == 0) {
            self.phase = Phase::Won;
            ctx.play(Sound::LevelClear);
        }
    }

pub fn fade(self, fade: Duration) -> Self

Takes fade to come up at the start and to go down when a sustain ends; SoundCue::DEFAULT_FADE until set.

A loop wrap is never faded.

Examples found in repository

examples/sound-lab.rs (line 825)

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

    /// Declares [`RING_COUNT`] sustains on a ring, each less loud than the
    /// one before it, so the engine's cap plays the loudest of them and the
    /// rest hold no voice while their playback goes on.
    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

    fn sustain_cues(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        let fade = Duration::from_secs_f32(self.cue_fade);
        if self.theme_on {
            ctx.sustain(Sound::Theme.gain(0.5).fade(fade));
        }
        if self.menu_on {
            ctx.sustain(Sound::MenuTheme.gain(0.5).fade(fade));
        }
        if self.pulse_on {
            ctx.sustain(Sound::Pulse.gain(0.3).fade(fade));
        }
    }

examples/breakout-game.rs (line 882)

    fn sustain_music(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let playing = !self.paused && matches!(self.phase, Phase::Serving | Phase::Playing);
        let gain = |wanted: bool| match wanted {
            true => MUSIC_GAIN,
            false => 0.0,
        };

        ctx.sustain(
            Sound::Music
                .gain(gain(playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MUSIC_LOOP_FROM),
        );
        ctx.sustain(
            Sound::MenuMusic
                .gain(gain(!playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MENU_MUSIC_LOOP_FROM),
        );
    }

pub fn glide(self, glide: Duration) -> Self

Slides over glide every later change of gain or position; SoundCue::DEFAULT_GLIDE until set.

A crossfade over seconds states its span here: the gain a frame declares is the level the voice slides to, never a step.

Examples found in repository

examples/breakout-game.rs (line 883)

    fn sustain_music(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let playing = !self.paused && matches!(self.phase, Phase::Serving | Phase::Playing);
        let gain = |wanted: bool| match wanted {
            true => MUSIC_GAIN,
            false => 0.0,
        };

        ctx.sustain(
            Sound::Music
                .gain(gain(playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MUSIC_LOOP_FROM),
        );
        ctx.sustain(
            Sound::MenuMusic
                .gain(gain(!playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MENU_MUSIC_LOOP_FROM),
        );
    }

pub fn trim_to(self, start: Duration, end: Duration) -> Self

Plays only what lies between start and end of the sound’s own timeline.

Both clamp to the sound; a window with nothing in it plays nothing, with a debug log.

Examples found in repository

examples/sound-lab.rs (lines 826-829)

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

pub fn loop_from(self, at: Duration) -> Self

Comes back to at every time a sustain plays to the end of its window, so that what lies before it is heard once.

In the sound’s own timeline, clamped into the window with a debug log. A one-shot never loops, so play ignores this with a debug log.

Examples found in repository

examples/sound-lab.rs (line 371)

    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

    fn draw_room(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    ROOM_HALF * 2.0,
                    1.0,
                    ROOM_HALF * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
        let end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

examples/breakout-game.rs (line 884)

    fn sustain_music(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let playing = !self.paused && matches!(self.phase, Phase::Serving | Phase::Playing);
        let gain = |wanted: bool| match wanted {
            true => MUSIC_GAIN,
            false => 0.0,
        };

        ctx.sustain(
            Sound::Music
                .gain(gain(playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MUSIC_LOOP_FROM),
        );
        ctx.sustain(
            Sound::MenuMusic
                .gain(gain(!playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MENU_MUSIC_LOOP_FROM),
        );
    }

pub fn instance(self, nth: u32) -> Self

Sustains the sound as the nth of the places it sounds at, so one value is heard at more than one place at once; 0 until set.

A sustain is kept alive by its value and its instance together, and each instance is a voice with knobs of its own. A one-shot is a voice of its own already, so play ignores this with a debug log.

Examples found in repository

examples/sound-lab.rs (line 848)

    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

    fn sustain_cues(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        let fade = Duration::from_secs_f32(self.cue_fade);
        if self.theme_on {
            ctx.sustain(Sound::Theme.gain(0.5).fade(fade));
        }
        if self.menu_on {
            ctx.sustain(Sound::MenuTheme.gain(0.5).fade(fade));
        }
        if self.pulse_on {
            ctx.sustain(Sound::Pulse.gain(0.3).fade(fade));
        }
    }
}

/// Where the `nth` sustain of the ring stands: around the room, starting
/// behind the listener's back.
fn ring_place(nth: u32) -> Vec3 {
    let turn = TAU * nth as f32 / RING_COUNT as f32;

    Vec3::new(
        turn.sin() * RING_RADIUS,
        SOURCE_HEIGHT,
        turn.cos() * RING_RADIUS,
    )
}

/// The direction the ear pair is offset along — the same side the
/// engine's own pan reads.
fn listener_right(view: View) -> Vec3 {
    (view.target() - view.eye())
        .normalize_or_zero()
        .cross(view.up())
}

/// The clip's duration, with two trim handles and a loop marker, each moved
/// by the pointer's own place rather than by a moving total.
fn duration_bar(
    ui: &mut egui::Ui,
    duration: f32,
    trim_start: &mut f32,
    trim_end: &mut f32,
    loop_from: &mut f32,
) {
    let size = egui::vec2(ui.available_width().min(420.0), 28.0);
    let (rect, _response) = ui.allocate_exact_size(size, egui::Sense::hover());
    let painter = ui.painter();
    painter.rect_filled(rect, 3.0, egui::Color32::from_gray(35));

    let x_of = |seconds: f32| rect.left() + (seconds / duration).clamp(0.0, 1.0) * rect.width();
    let seconds_of = |x: f32| ((x - rect.left()) / rect.width()).clamp(0.0, 1.0) * duration;

    let span = egui::Rect::from_min_max(
        egui::pos2(x_of(*trim_start), rect.top()),
        egui::pos2(x_of(*trim_end), rect.bottom()),
    );
    painter.rect_filled(span, 3.0, egui::Color32::from_rgb(70, 120, 95));

    let start_x = x_of(*trim_start);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "trim-start",
        start_x,
        egui::Color32::from_rgb(230, 200, 80),
    ) {
        *trim_start = seconds_of(x).min(*trim_end);
    }
    let end_x = x_of(*trim_end);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "trim-end",
        end_x,
        egui::Color32::from_rgb(230, 200, 80),
    ) {
        *trim_end = seconds_of(x).max(*trim_start);
    }
    let loop_x = x_of(*loop_from);
    if let Some(x) = drag_handle(
        ui,
        rect,
        "loop-from",
        loop_x,
        egui::Color32::from_rgb(90, 170, 230),
    ) {
        *loop_from = seconds_of(x).clamp(*trim_start, *trim_end);
    }
}

/// One round handle at `x`. Returns the pointer's `x` while a drag holds
/// it.
fn drag_handle(
    ui: &mut egui::Ui,
    bar: egui::Rect,
    salt: &str,
    x: f32,
    color: egui::Color32,
) -> Option<f32> {
    let radius = 6.0;
    let center = egui::pos2(x, bar.center().y);
    let sense_rect = egui::Rect::from_center_size(center, egui::Vec2::splat(radius * 2.5));
    let id = ui.id().with(salt);
    let response = ui.interact(sense_rect, id, egui::Sense::drag());
    ui.painter().circle_filled(center, radius, color);

    response
        .dragged()
        .then(|| response.interact_pointer_pos())
        .flatten()
        .map(|pos| pos.x)
}

impl Game for SoundCheck {
    type Meshes = Shape;
    type Sounds = Sound;
    type InputActions = Controls;
    type Skyboxes = Sky;
    type SurfaceStyles = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    fn tick(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.handle_walk(ctx);
        self.handle_drag(ctx);
    }

    fn frame(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        ctx.set_volume(self.master_volume);

        let player = self.player_prev.lerp(self.player, ctx.alpha());
        let ear = Vec3::new(player.x, EYE_HEIGHT, player.y);
        let listener = View::look_at(ear, ear + Vec3::NEG_Z);
        ctx.set_listener(listener);

        ctx.set_camera(Self::camera(player));
        ctx.set_skybox(Sky::Room);
        ctx.set_bloom(0.2);
        ctx.light(Light::directional(Vec3::new(-0.4, -1.0, -0.5), SUN_COLOR).shadow());

        self.draw_room(ctx);
        self.draw_sources(ctx);
        self.draw_listener(ctx, listener);
        self.draw_merge_markers(ctx);
        self.draw_ring(ctx);

        self.sustain_cues(ctx);
        for (index, source) in self.sources.iter().enumerate() {
            if source.enabled {
                ctx.sustain(source.cue().instance(index as u32));
            }
        }
        if self.merge_demo {
            ctx.sustain(Sound::Click.at(MERGE_POS_A).gain(MERGE_GAIN));
            ctx.sustain(Sound::Click.at(MERGE_POS_B).gain(MERGE_GAIN));
        }
        self.sustain_ring(ctx);

        self.side_panel(ctx);
        let (play_once, play_many) = self.one_shot_panel(ctx);

        if play_once {
            ctx.play(self.one_shot_cue());
        }
        if play_many {
            for _ in 0..32 {
                ctx.play(self.one_shot_cue());
            }
        }
    }

Trait Implementations

impl<S: Sounds> Clone for SoundCue<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug + Sounds> Debug for SoundCue<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Sounds> From<S> for SoundCue<S>

fn from(sound: S) -> Self

Converts to this type from the input type.