Skip to content
Merged
66 changes: 63 additions & 3 deletions rust-modules/gfx/src/gfx.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4029,6 +4029,12 @@ impl Drop for RegionTarget {
/// the picture the texture holds. Both Under posters pages ask for the SAME picture (a page whose art
/// is still dissolving has no key and draws live, it never asks for a different one), so one slot
/// serves a push and a pop; a picture that changes is a new key and one fill.
///
/// **One slot means one picture on screen at a time, by design.** The two callers never stand on the
/// same frame: the Under posters preview (a 668x564 rect, 1.4 MiB) is Settings', and Home's parked
/// backdrop (the whole canvas, 1928x1088, 8.0 MiB: `Painter::cached_ground`) is Home's, drawn under
/// nothing that asks for the preview. A page that did ask for both in one frame would refill the
/// texture, at its other size, on each ask: correct, and dearer than drawing live.
#[derive(Clone, Copy, Debug, Default)]
pub struct RegionSlot {
key: Option<u64>,
Expand Down Expand Up @@ -4112,6 +4118,30 @@ fn region_mix(key: u64, extent: [c_int; 4]) -> u64 {
extent.iter().fold(key, |h, v| (h ^ (*v as u32 as u64)).wrapping_mul(0x0000_0100_0000_01b3))
}

/// **A cached GROUND's name, with the renderer's own state folded in.** A caller names a picture by
/// what IT holds (`Painter::cached_ground` hands over the name and the texture ids the picture
/// samples); what only the renderer knows is added here, where it is held:
/// each texture's revision ([`tex_ledger::revision`]: a texture re-specified under the same name is
/// another picture) and the two program switches the ground's paths read ([`art_wash_ok`] and
/// [`wash_ink_ok`]: which of the one-pass or layered draws the picture is made of). A screen reads
/// none of them, so its name holds only the screen's own state.
pub fn region_ground_key(key: u64, textures: &[c_uint]) -> u64 {
ground_key_of(key, textures, art_wash_ok(), wash_ink_ok())
}

/// [`region_ground_key`] over the switches it was handed (the pure part: a host build has neither
/// program, so the one rule that reads them is pinned with them as arguments).
fn ground_key_of(key: u64, textures: &[c_uint], art_wash: bool, wash_ink: bool) -> u64 {
use std::hash::{Hash, Hasher};
let mut h = std::collections::hash_map::DefaultHasher::new();
key.hash(&mut h);
for tex in textures {
(*tex, tex_ledger::revision(*tex)).hash(&mut h);
}
(art_wash, wash_ink).hash(&mut h);
h.finish()
}

/// **Paint a rect of the page once, then serve it as one textured quad.** `key` names the picture:
/// it must change with everything `paint` draws (`None`: the picture is not settled, draw it live).
/// `rect` is where the picture stands on the PAGE (`x, y, w, h` logical px), `shift` the painter's
Expand Down Expand Up @@ -4187,9 +4217,12 @@ pub fn region_paint(
}

/// A frame ended: if no page asked for the region during it, the texture goes back to the driver
/// (1.4 MiB that nothing is showing), and the next ask fills again. Called once per presented frame,
/// beside the other frame-end hooks. A push, a pop and a transition between the two pages ask on every
/// frame (one page or the other always draws), so it never frees mid-transition.
/// (1.4 MiB for the Under posters preview, 8.0 MiB for Home's backdrop, that nothing is showing), and
/// the next ask fills again. Called once per presented frame,
/// beside the other frame-end hooks. A push, a pop and a transition between the two Under posters pages
/// ask on every frame (one page or the other always draws), so the preview never frees mid-transition.
/// Home's backdrop asks only through a plain painter (`Painter::is_plain`), so a Home dip or slide frame
/// does not ask and the texture goes back until the first plain frame fills it again.
pub fn region_frame_end() {
REGION.with(|cell| {
let Ok(mut set) = cell.try_borrow_mut() else { return };
Expand Down Expand Up @@ -8402,6 +8435,33 @@ pub fn draw_field_panel(
mod tests {
use super::*;

/// **A cached ground is named by what its caller holds AND by what only the renderer knows**
/// ([`region_ground_key`]): each texture's revision (one re-specified under the same name is
/// another picture) and the two program switches the ground's paths read. Every one of them
/// changes the name, and nothing else does.
#[test]
fn a_ground_key_folds_in_the_renderers_own_state() {
let tex = 9_101;
tex_ledger::specified(tex, 16, 9);
let base = ground_key_of(7, &[tex], true, true);
assert_eq!(ground_key_of(7, &[tex], true, true), base, "the same inputs, the same name");
assert_eq!(region_ground_key(7, &[tex]), ground_key_of(7, &[tex], art_wash_ok(), wash_ink_ok()));
let mut seen = vec![base];
let mut differs = |what: &str, key: u64| {
assert!(!seen.contains(&key), "{what}: the name did not change");
seen.push(key);
};
differs("the caller's own name", ground_key_of(8, &[tex], true, true));
differs("another texture", ground_key_of(7, &[tex + 1], true, true));
differs("no texture", ground_key_of(7, &[], true, true));
differs("the art-in-wash program missing", ground_key_of(7, &[tex], false, true));
differs("the wash's ink program missing", ground_key_of(7, &[tex], true, false));
tex_ledger::specified(tex, 16, 9);
differs("the same texture name re-specified with other pixels", ground_key_of(7, &[tex], true, true));
tex_ledger::deleted(tex);
differs("the texture freed", ground_key_of(7, &[tex], true, true));
}

/// **[`enc_u8`] is `(enc(v).clamp(0, 1) * 255 + 0.5) as u8` to the bit, without a `powf`.**
/// Every threshold is checked from both sides (the last float below it and the threshold
/// itself), then a dense sweep of the whole working range and the edge values a colour
Expand Down
7 changes: 4 additions & 3 deletions rust-modules/gfx/src/overdraw.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@
//! five GL draws); this can, and it is how a stalled spring that kept every visited card on the
//! focus program was found. `/tmp/plxnative-nocardsplit` ([`set_card_split`]) switches the split
//! off for a leg, so one binary measures it on and off interleaved. A region drawn once into a
//! texture (`gfx::region_paint`, the Under posters preview) has two switches of its own:
//! `/tmp/plxnative-nopreviewcache` ([`set_region_cache`]) draws it live again, and
//! texture (`gfx::region_paint`: the Under posters preview and Home's parked backdrop) has two
//! switches of its own: `/tmp/plxnative-nopreviewcache` ([`set_region_cache`]) draws every such
//! region live again (the name is the first user's), and
//! `/tmp/plxnative-previewsnap` ([`set_region_snap`]) puts its quad on whole pixels.
//!
//! A masked leg is deliberately a BROKEN PICTURE. This is a measurement knob, not a feature — the
Expand Down Expand Up @@ -173,7 +174,7 @@ mod imp {
static PATH_DRAWS: [Cell<u32>; NPATH] = const { [const { Cell::new(0) }; NPATH] };
/// Is the resting-card split allowed? On unless a leg switched it off.
static SPLIT: Cell<bool> = const { Cell::new(true) };
/// Is a region (the Under posters preview) allowed to be served from its texture? On unless a leg switched it off.
/// Is a region (the Under posters preview, Home's parked backdrop) allowed to be served from its texture? On unless a leg switched it off.
static REGION_CACHE: Cell<bool> = const { Cell::new(true) };
/// Is a cached region's quad put on whole pixels? Off unless a leg switched it on.
static REGION_SNAP: Cell<bool> = const { Cell::new(false) };
Expand Down
124 changes: 118 additions & 6 deletions rust-modules/screens/src/home/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -528,18 +528,109 @@ impl Backdrop {
});
}

/// Paint the ground, photograph and the shared side and shelf shade. A slide or opaque art
/// draws the shade separately over the art.
/// **Draw the page's backdrop: the ground (wash and photograph) and the shared side and shelf
/// shade over it.** A slide or opaque art draws the shade separately over the art. `rests` is the
/// page's own statement that the snap dive is over (`HomeScreen::snap` has landed), the one input
/// the backdrop does not own.
///
/// A backdrop that is not moving is ONE textured quad: [`Self::ground_key`] names the picture
/// while every spring that eases it has landed, and `Painter::cached_ground` paints it into the
/// region texture once per name and serves it from there. Home stands parked at the hero while a
/// Continue Watching card holds focus, so a focus move redraws the shelf over a backdrop that
/// did not change, and the 2.1M-fragment ground was re-shaded under it on every frame
/// (TV, 2026-11-09, `grid-pong`: the ground's `grad` + `image` draw classes were 2.6M of the
/// frame's 9.5M GPU cycles). While anything moves the backdrop has no name and is drawn live,
/// exactly as before.
fn draw(
&self,
p: Painter,
env: &Env,
slide: Option<(f32, f32)>,
scrim: Option<plx_ui::widgets::WashScrim>,
rests: bool,
) {
if !self.pending_art.is_empty() && env.hero_a > 0.01 && env.sp < HERO_ART_CULL {
plx_ui::placeholder::note(p, plx_ui::placeholder::Reason::HomeBackdrop, &self.pending_art);
}
// Past the cull the page stands on one flat colour, which the renderer already draws as a
// clear: nothing to cache, and no ask, so the texture goes back (`gfx::region_frame_end`).
if env.sp >= HERO_ART_CULL {
self.paint(p, env, slide, scrim);
return;
}
p.cached_ground(
self.ground_key(env, slide, scrim, rests),
&[self.tex.0, self.outgoing_tex.0],
Rect::FULL,
|q| self.paint(q, env, slide, scrim),
);
}

/// **The name of the picture [`Self::paint`] draws**: every input of it that this screen owns, by
/// value, and `None` while the picture is not settled.
///
/// The inputs are the wash (the exact bits of its twelve springs, [`AmbientWash::paint_bits`]),
/// both art layers (the texture each resolved to, its decoded size, which sets the cover crop; a
/// layer's reveal alpha is not an input, because a named layer is at exactly 1.0, below), the
/// dive (`env.sp`, from which the art's offset and fade and the hero's own alpha follow) and the
/// shared side and shelf shade over it (`scrim`, by value: its ink and every uniform the shader
/// is given, [`plx_ui::widgets::WashScrim::paint_bits`]; the shelf ramp rides the first shelf's
/// live top, so it names where the shelf stands as well as how far the hero has faded). There is
/// no slide: a slide has no name.
///
/// **The renderer's own state is not read here.** A texture re-specified under the same name is
/// another picture, and the ground's paths depend on which programs linked; both live in the
/// renderer, which folds them into this name when the picture is looked up
/// (`Painter::cached_ground` is handed the texture ids, `gfx::region_ground_key`). A screen's
/// name holds only what the screen holds.
///
/// **A picture that is moving has no name, rather than a new one every frame.** A key that
/// changed on every frame of the hero's reveal, a flip or the dive would fill the texture on
/// every one of them: the same shading as the live draw, plus a full-screen write and a quad
/// over it, which is dearer than not caching. So the picture is named only once every spring
/// that eases it has landed on its target (`AmbientWash::at_rest`, which the wash lands on
/// exactly) and the page says the dive is over (`HomeScreen::dive_rests`: the dive is landed on
/// its target too); any frame short of that is drawn live and fills nothing. A layer with a
/// texture has landed when its reveal spring stands at exactly 1.0 with no velocity: `update`
/// steps every resident layer toward 1.0 and lands it there, and a velocity of 0 alone is not
/// enough, because `bind` leaves a spring at velocity 0 where it `jump`s (a replacement, at the
/// draw) and where art that was not resident arrives (parked at 0.0), a frame before `update`
/// steps it. A layer with no texture draws nothing, so its reveal spring says nothing.
fn ground_key(
&self,
env: &Env,
slide: Option<(f32, f32)>,
scrim: Option<plx_ui::widgets::WashScrim>,
rests: bool,
) -> Option<u64> {
use std::hash::{Hash, Hasher};
let landed = |tex: (u32, f32, f32), art: &Spring| tex.0 == 0 || (art.pos == 1.0 && art.vel == 0.0);
if slide.is_some()
|| !rests
|| !self.wash.at_rest()
|| !landed(self.tex, &self.art)
|| !landed(self.outgoing_tex, &self.outgoing_art)
{
return None;
}
let mut h = std::collections::hash_map::DefaultHasher::new();
self.wash.paint_bits().hash(&mut h);
for (id, w, h_px) in [self.tex, self.outgoing_tex] {
(id, w.to_bits(), h_px.to_bits()).hash(&mut h);
}
(env.sp.to_bits(), env.hero_a.to_bits()).hash(&mut h);
scrim.map(|s| s.paint_bits()).hash(&mut h);
Some(h.finish())
}

/// The backdrop's primitives, as `draw` hands them to the painter or to the region texture.
fn paint(
&self,
p: Painter,
env: &Env,
slide: Option<(f32, f32)>,
scrim: Option<plx_ui::widgets::WashScrim>,
) {
let incoming_a = reveal(self.tex.0, &self.art);
let outgoing_a = reveal(self.outgoing_tex.0, &self.outgoing_art);
// Art held beneath a replaced hero (`held`) is the un-sliding outgoing layer: the new art
Expand Down Expand Up @@ -1686,6 +1777,14 @@ impl HomeScreen {
self.hub(view, row)?.items.get(col).map(|m| &**m)
}

/// Has the snap dive landed: the one input of the backdrop's picture that the backdrop does not
/// own (`Backdrop::draw`). Exactly 0 only once the spring has parked on its target:
/// `update` lands the dive (`Spring::land`) once it is within a hair of it, which a bare `step`
/// never does.
fn dive_rests(&self) -> bool {
self.snap.vel == 0.0
}

fn env(&self, dt: f32) -> Env {
let mut env = Env::inert();
env.dt = dt;
Expand Down Expand Up @@ -1900,8 +1999,12 @@ impl HomeScreen {
} else {
self.hero_auto = HERO_AUTO_S;
}
self.snap
.step(pinned_snap(self.snap_target, self.rows.len()), K_SNAP, dt);
let snap_to = pinned_snap(self.snap_target, self.rows.len());
self.snap.step(snap_to, K_SNAP, dt);
// A dive that has arrived is LANDED on its target (`Spring::land`), as the art and the wash
// are: `step` parks it one ulp off with a velocity of ~1e-44 and keeps it there, and the
// backdrop is named (`Backdrop::ground_key`) only while the dive's velocity is exactly 0.
self.snap.land(snap_to, dt);
// ONE answer for "is the dive still running", read by the present gate below. See
// `SNAP_REST_POS`/`SNAP_REST_VEL` for why both terms are needed.
let snap_moving = (self.snap.pos - self.snap_target).abs() > SNAP_REST_POS
Expand Down Expand Up @@ -2277,8 +2380,10 @@ impl HomeScreen {
self.carousel.as_ref(),
self.snap.pos,
);
let shade = (env.hero_a > 0.01).then(|| home_shade(self.shelf_fade(env.hero_a), env.hero_a));
plx_ui::profile::phase("hm.backdrop", || self.backdrop.draw(p, &env, slide, shade));
let shade = self.backdrop_shade(&env);
plx_ui::profile::phase("hm.backdrop", || {
self.backdrop.draw(p, &env, slide, shade, self.dive_rests())
});
if env.hero_a > 0.01 {
plx_ui::profile::phase("hm.hero", || {
self.draw_hero(
Expand Down Expand Up @@ -2318,6 +2423,13 @@ impl HomeScreen {
shelf_fade(tiles_top, hero_a)
}

/// **The backdrop's shade of THIS frame**: the fixed left shade joined with the shelf fade, the
/// hero's own (`None` once the hero has faded out). One place builds it, for the draw and for the
/// name the backdrop's cached picture is looked up by (`Backdrop::ground_key`).
fn backdrop_shade(&self, env: &Env) -> Option<plx_ui::widgets::WashScrim> {
(env.hero_a > 0.01).then(|| home_shade(self.shelf_fade(env.hero_a), env.hero_a))
}

fn draw_hero(
&self,
view: HubsView<'_>,
Expand Down
4 changes: 2 additions & 2 deletions rust-modules/screens/src/home/placeholder_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ fn env(sp: f32, hero_a: f32) -> Env {
}

fn drawn(b: &Backdrop, env: &Env) -> placeholder::Frame {
placeholder::capture_declared(|| b.draw(Painter::root(), env, None, None)).1
placeholder::capture_declared(|| b.draw(Painter::root(), env, None, None, true)).1
}

#[test]
Expand Down Expand Up @@ -64,6 +64,6 @@ fn a_hero_layer_that_is_not_on_screen_counts_nothing() {
#[test]
fn a_recording_pass_over_the_backdrop_counts_nothing() {
let b = bound("/library/metadata/5/art/1", 0.0);
let f = placeholder::capture_declared(|| b.draw(Painter::recording(), &env(0.0, 1.0), None, None)).1;
let f = placeholder::capture_declared(|| b.draw(Painter::recording(), &env(0.0, 1.0), None, None, true)).1;
assert_eq!(f.count, 0, "{f:?}");
}
Loading
Loading