From f2235de77a6f9a08f6c2399fdf426bc79b1946ad Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 19 Nov 2026 17:47:33 +0100 Subject: [PATCH] Prepare complete screen-sized decks and retain playback frames in RAM --- Cargo.lock | 2 +- Cargo.toml | 2 +- crates/pdf-presenter/src/document.rs | 23 +- crates/pdf-presenter/src/native.rs | 134 ++++++++-- crates/pdf-presenter/src/output.rs | 8 + crates/pdf-presenter/src/presenter_ui.rs | 38 ++- crates/pdf-presenter/src/settings.rs | 5 + crates/pdf-presenter/src/studio.rs | 312 ++++++++++++++++++---- crates/pdf-presenter/src/worker.rs | 30 ++- crates/pdf-presenter/tests/native.rs | 53 +++- crates/pdf-presenter/tests/preparation.rs | 176 ++++++++++++ crates/pdf-presenter/tests/settings.rs | 6 + docs/changelog.md | 14 + docs/development/native-implementation.md | 38 ++- docs/development/tasks.md | 5 + docs/interfaces/examples/settings-v1.toml | 1 + docs/interfaces/extraction-cache.md | 20 +- docs/interfaces/process-protocol.md | 15 ++ docs/interfaces/settings.md | 4 + docs/user-guide.md | 42 ++- 20 files changed, 810 insertions(+), 118 deletions(-) create mode 100644 crates/pdf-presenter/tests/preparation.rs diff --git a/Cargo.lock b/Cargo.lock index b860805..f3dea92 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2212,7 +2212,7 @@ dependencies = [ [[package]] name = "pdf-presenter" -version = "0.1.12" +version = "0.1.13" dependencies = [ "bytemuck", "chrono", diff --git a/Cargo.toml b/Cargo.toml index 40d0e14..617ce5c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"] resolver = "3" [workspace.package] -version = "0.1.12" +version = "0.1.13" edition = "2024" license = "MIT" repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter" diff --git a/crates/pdf-presenter/src/document.rs b/crates/pdf-presenter/src/document.rs index 7297c88..462fda9 100644 --- a/crates/pdf-presenter/src/document.rs +++ b/crates/pdf-presenter/src/document.rs @@ -265,6 +265,18 @@ impl Document { }) } pub fn render(&self, page: usize, edge: u32) -> Result { + self.render_inner(page, edge, false)? + .ok_or_else(|| "Missing rendered frame".into()) + } + pub fn cached(&self, page: usize, edge: u32) -> Result, String> { + self.render_inner(page, edge, true) + } + fn render_inner( + &self, + page: usize, + edge: u32, + cached_only: bool, + ) -> Result, String> { if page >= self.info.names.len() { return Err("Slide out of range".into()); } @@ -279,7 +291,7 @@ impl Document { let dir = self.cache.join(&self.info.key).join(&identity); let path = dir.join(format!("{page}-{edge}-hayro09.rgba")); if let Ok((width, height, rgba)) = read_frame(&path) { - return Ok(Frame { + return Ok(Some(Frame { info: FrameInfo { page, width, @@ -288,7 +300,10 @@ impl Document { sha256: identity, }, rgba, - }); + })); + } + if cached_only { + return Ok(None); } let (width, height, rgba) = match &self.source { Source::Pdf(pdf) => { @@ -342,7 +357,7 @@ impl Document { &dir.join(format!("{page}-{edge}-extraction.json")), &serde_json::to_vec_pretty(&manifest).unwrap(), )?; - Ok(Frame { + Ok(Some(Frame { info: FrameInfo { page, width, @@ -351,7 +366,7 @@ impl Document { sha256: identity, }, rgba, - }) + })) } } pub fn validate_frame(w: u32, h: u32, len: usize) -> Result<(), String> { diff --git a/crates/pdf-presenter/src/native.rs b/crates/pdf-presenter/src/native.rs index 101eab2..ed71274 100644 --- a/crates/pdf-presenter/src/native.rs +++ b/crates/pdf-presenter/src/native.rs @@ -261,6 +261,8 @@ struct Host { cache: HashMap>, frame: Option>, presented: HashSet, + failed_reads: HashSet, + preload_cursor: usize, } struct App { studio: Option, @@ -507,11 +509,15 @@ impl App { } if let Some(output) = &self.output { while let Ok(ack) = output.rx.try_recv() { + if ack.generation == s.buffer_generation() { + s.output_buffered = ack.buffered; + } if !ack.awake.is_empty() { s.awake_status = ack.awake; } if !ack.status.is_empty() { s.status = ack.status; + s.output_buffered = 0; s.blanked = true; s.new_output = true; } @@ -524,11 +530,22 @@ impl App { let state = HostState { sequence: s.output_sequence, page: s.requested, - frame: s.frame_info(), - preload: [s.requested.saturating_sub(1), s.requested + 1] - .iter() - .filter_map(|&p| s.full_frame(p).map(|f| f.info.clone())) - .collect(), + frame: if s.routes.presentation.is_empty() { + None + } else { + s.frame_info() + }, + generation: s.buffer_generation(), + buffer_mib: s.settings.buffer_mib, + preload: if s.routes.presentation.is_empty() { + vec![] + } else { + (0..s.count()) + .filter_map(|p| { + s.frames.get(&(p, s.target_edge)).map(|f| f.info.clone()) + }) + .collect() + }, monitors: s.routes.presentation.clone(), fullscreen: s.settings.presentation_fullscreen, blanked: s.blanked, @@ -570,45 +587,95 @@ impl App { w.ui.textures.clear(); } } + if state.generation != host.state.generation { + host.cache.clear(); + host.failed_reads.clear(); + host.frame = None; + } + // Keep the prepared deck resident; retire previews/superseded resolutions only. + let retained: HashSet<_> = state + .preload + .iter() + .map(|f| &f.path) + .chain(state.frame.iter().map(|f| &f.path)) + .collect(); + host.cache.retain(|path, _| retained.contains(path)); + host.preload_cursor = 0; + if state.buffer_mib > host.state.buffer_mib { + host.failed_reads.clear(); + } + if state.monitors.is_empty() { + host.frame = None; + } host.state = state; } while let Ok(c) = host.reader.rx.try_recv() { repaint = true; - host.reading = None; - if let Ok(packet) = c.result - && let Some(info) = packet.reply.frame - { - let frame = Arc::new(Frame { - info, - rgba: packet.data, - }); - if host.cache.len() >= 6 { - host.cache.clear(); + let reading = host.reading.take(); + if c.generation != host.state.generation { + continue; + } + match c.result { + Ok(packet) if packet.reply.frame.is_some() => { + let info = packet.reply.frame.unwrap(); + let bytes: usize = host.cache.values().map(|f| f.rgba.len()).sum(); + let limit = host.state.buffer_mib.max(256) as usize * 1024 * 1024; + if bytes.saturating_add(packet.data.len()) <= limit { + host.cache.insert( + info.path.clone(), + Arc::new(Frame { + info, + rgba: packet.data, + }), + ); + } else if let Some(path) = reading { + host.failed_reads.insert(path); + let _ = host.acks.try_send(Ack { + status: "Presentation RAM budget reached; increase the budget in Menu to finish buffering.".into(), + ..Default::default() + }); + } + } + _ => { + if let Some(path) = reading { + host.failed_reads.insert(path); + let _ = host.acks.try_send(Ack { + status: + "Could not buffer an output slide; reopen the source to retry." + .into(), + ..Default::default() + }); + } } - host.cache.insert(frame.info.path.clone(), frame); } } if let Some(info) = &host.state.frame { if let Some(frame) = host.cache.get(&info.path) { host.frame = Some(frame.clone()); } else if host.reading.is_none() - && host - .reader - .submit(0, 0, Request::ReadFrame(info.path.clone())) + && !host.failed_reads.contains(&info.path) + && host.reader.submit( + host.state.generation, + 0, + Request::ReadFrame(info.path.clone()), + ) { host.reading = Some(info.path.clone()); } } - if host.reading.is_none() { - for info in &host.state.preload { - if !host.cache.contains_key(&info.path) - && host - .reader - .submit(0, 0, Request::ReadFrame(info.path.clone())) - { - host.reading = Some(info.path.clone()); - break; - } + while host.reading.is_none() && host.preload_cursor < host.state.preload.len() { + let info = &host.state.preload[host.preload_cursor]; + if host.cache.contains_key(&info.path) || host.failed_reads.contains(&info.path) { + host.preload_cursor += 1; + } else if host.reader.submit( + host.state.generation, + 0, + Request::ReadFrame(info.path.clone()), + ) { + host.reading = Some(info.path.clone()); + host.preload_cursor += 1; + } else { + break; } } } @@ -746,6 +813,13 @@ impl ApplicationHandler for App { && host.presented.len() >= self.windows.len(); let _ = host.acks.try_send(Ack { sequence: host.state.sequence, + generation: host.state.generation, + buffered: host + .state + .preload + .iter() + .filter(|f| host.cache.contains_key(&f.path)) + .count(), page: shown.then_some(host.state.page), ..Default::default() }); @@ -863,6 +937,8 @@ pub fn run_output() -> Result<(), Failure> { cache: HashMap::new(), frame: None, presented: HashSet::new(), + failed_reads: HashSet::new(), + preload_cursor: 0, }), output: None, lease: Some(SleepLease::new()), diff --git a/crates/pdf-presenter/src/output.rs b/crates/pdf-presenter/src/output.rs index 8e3a693..eaa652c 100644 --- a/crates/pdf-presenter/src/output.rs +++ b/crates/pdf-presenter/src/output.rs @@ -17,9 +17,13 @@ use std::{ #[derive(Clone, Default, Debug, Serialize, Deserialize)] pub struct HostState { pub sequence: u64, + #[serde(default)] + pub generation: u64, pub page: usize, pub frame: Option, pub preload: Vec, + #[serde(default)] + pub buffer_mib: u32, pub monitors: Vec, pub fullscreen: bool, pub blanked: bool, @@ -31,6 +35,10 @@ pub struct Ack { pub page: Option, pub status: String, pub awake: String, + #[serde(default)] + pub generation: u64, + #[serde(default)] + pub buffered: usize, } pub struct OutputLink { pub tx: SyncSender, diff --git a/crates/pdf-presenter/src/presenter_ui.rs b/crates/pdf-presenter/src/presenter_ui.rs index 928e9c4..ed5396f 100644 --- a/crates/pdf-presenter/src/presenter_ui.rs +++ b/crates/pdf-presenter/src/presenter_ui.rs @@ -71,6 +71,8 @@ impl UiState { fn trim(&mut self, s: &Studio) { self.textures.retain(|(generation, page, edge), _| { *generation == s.generation + && (page.abs_diff(s.requested) <= 1 + || (s.browser_open && s.visible_thumbs.contains(page))) && s.frames .values() .any(|f| f.info.page == *page && f.info.width.max(f.info.height) == *edge) @@ -143,7 +145,7 @@ pub fn presenter(ui: &mut Ui, s: &mut Studio, native: &mut UiState) { body.min.y += 64.; } if s.layout.footer { - body.max.y -= 66.; + body.max.y -= 90.; } let preview_visible = s.layout.previous.show || s.layout.current.show || s.layout.next.show; let notes_h = if s.layout.notes.show { @@ -336,8 +338,8 @@ pub fn presenter(ui: &mut Ui, s: &mut Studio, native: &mut UiState) { } if footer { let rect = Rect::from_min_size( - Pos2::new(screen.left(), screen.bottom() - 66.), - Vec2::new(screen.width(), 66.), + Pos2::new(screen.left(), screen.bottom() - 90.), + Vec2::new(screen.width(), 90.), ); ui.painter() .rect_filled(rect, 0., Color32::from_rgb(25, 37, 40)); @@ -376,9 +378,33 @@ pub fn presenter(ui: &mut Ui, s: &mut Studio, native: &mut UiState) { } ui.small(&s.awake_status); }); + ui.label(s.preparation_status()); ui.small(&s.status); + if s.count() > 0 && !s.fully_buffered() { + let prepared = s.prepared.len() + + if s.routes.presentation.is_empty() { + s.prepared.len() + } else { + s.output_buffered + }; + ui.add( + egui::ProgressBar::new(prepared as f32 / (2 * s.count()) as f32) + .desired_height(4.), + ); + } }); } + if !footer && (s.loading || s.notes_loading || (s.deck.is_some() && !s.fully_buffered())) { + egui::Area::new("preparation-progress".into()) + .anchor(egui::Align2::LEFT_BOTTOM, Vec2::new(12., -12.)) + .interactable(false) + .show(&ctx, |ui| { + egui::Frame::popup(ui.style()).show(ui, |ui| { + ui.set_max_width((screen.width() - 24.).max(100.)); + ui.label(s.preparation_status()); + }); + }); + } if !s.jump.is_empty() { egui::Area::new("jump".into()) .anchor(egui::Align2::CENTER_BOTTOM, Vec2::new(0., -80.)) @@ -413,6 +439,12 @@ pub fn presenter(ui: &mut Ui, s: &mut Studio, native: &mut UiState) { Action::Windowed, &mut s.actions, ); + ui.separator(); + ui.label(s.preparation_status()); + ui.label(format!("Processed slides: {}", s.cache_path.display())); + ui.label("RAM budget per process (presenter + output each use this allowance):"); + if ui.add(egui::Slider::new(&mut s.settings.buffer_mib, 256..=16384).text("MiB")).changed() { s.remember_buffer_budget(); } + ui.small("Raise only within available RAM; OS paging can cause delays. Screen rendering is capped at 4096 px."); ui.label(format!("Configuration: {}", s.settings_path.display())); button(ui, "Quit", Action::Exit, &mut s.actions); if ui.button("Close menu").clicked() { diff --git a/crates/pdf-presenter/src/settings.rs b/crates/pdf-presenter/src/settings.rs index 28dfd16..3647f9f 100644 --- a/crates/pdf-presenter/src/settings.rs +++ b/crates/pdf-presenter/src/settings.rs @@ -137,6 +137,7 @@ pub struct Settings { pub presentation_fullscreen: bool, pub browser_monitor: Option, pub thumbnail_size: f32, + pub buffer_mib: u32, } impl Default for Settings { fn default() -> Self { @@ -149,6 +150,7 @@ impl Default for Settings { presentation_fullscreen: true, browser_monitor: None, thumbnail_size: 220., + buffer_mib: 1024, } } } @@ -157,6 +159,9 @@ impl Settings { if self.version != 1 { return Err(format!("Unsupported settings version {}", self.version)); } + if !(256..=16384).contains(&self.buffer_mib) { + return Err("RAM buffer must be 256–16384 MiB per process".into()); + } if self.projects.len() > 4096 || !(100. ..=400.).contains(&self.thumbnail_size) { return Err("Invalid settings limits".into()); } diff --git a/crates/pdf-presenter/src/studio.rs b/crates/pdf-presenter/src/studio.rs index 549b19d..a9e60a2 100644 --- a/crates/pdf-presenter/src/studio.rs +++ b/crates/pdf-presenter/src/studio.rs @@ -5,7 +5,7 @@ use crate::{ worker::{Bridge, Request}, }; use std::{ - collections::{HashMap, HashSet, VecDeque}, + collections::{HashMap, HashSet}, path::PathBuf, sync::Arc, time::{Duration, Instant}, @@ -47,7 +47,14 @@ pub struct Studio { pub awake_status: String, pub generation: u64, pub frames: HashMap<(usize, u32), Arc>, - order: VecDeque<(usize, u32)>, + pub prepared: HashSet, + pub target_edge: u32, + pub preparation_started: Instant, + pub output_buffered: usize, + pub ram_blocked: bool, + pub cached_slides: usize, + pub loading: bool, + pub notes_loading: bool, pub visible_thumbs: HashSet, pub layout_open: bool, pub displays_open: bool, @@ -66,6 +73,8 @@ pub struct Studio { pub dialog: Bridge, fg_busy: bool, bg_busy: bool, + fg_job: Option<(usize, u32)>, + bg_job: Option<(usize, u32)>, notes_pending: bool, pending_open: Option, pending_save: bool, @@ -80,9 +89,17 @@ pub struct Studio { pub smoke: bool, pub startup: Instant, _smoke_dir: Option, + worker_program: PathBuf, } impl Studio { pub fn new(smoke: bool, open_path: Option) -> Self { + Self::with_program( + smoke, + open_path, + std::env::current_exe().unwrap_or_default(), + ) + } + pub fn with_program(smoke: bool, open_path: Option, worker_program: PathBuf) -> Self { let (mut settings_path, mut cache_path) = settings::paths().unwrap_or_else(|_| { ( PathBuf::from("settings.toml"), @@ -98,7 +115,7 @@ impl Studio { settings_path = dir.path().join("settings.toml"); cache_path = dir.path().join("cache"); } - let io = Bridge::new(Duration::from_secs(10)); + let io = Bridge::with_program(Duration::from_secs(10), worker_program.clone()); io.submit(0, 0, Request::LoadSettings(settings_path.clone())); Self { settings: Settings::default(), @@ -114,7 +131,14 @@ impl Studio { awake_status: "Sleep protection starting…".into(), generation: 0, frames: HashMap::new(), - order: VecDeque::new(), + prepared: HashSet::new(), + target_edge: 1920, + preparation_started: Instant::now(), + output_buffered: 0, + ram_blocked: false, + cached_slides: 0, + loading: false, + notes_loading: false, visible_thumbs: HashSet::new(), layout_open: false, displays_open: false, @@ -127,12 +151,14 @@ impl Studio { actions: vec![], settings_path, cache_path, - fg: Bridge::new(Duration::from_secs(30)), - bg: Bridge::new(Duration::from_secs(30)), + fg: Bridge::with_program(Duration::from_secs(30), worker_program.clone()), + bg: Bridge::with_program(Duration::from_secs(30), worker_program.clone()), io, - dialog: Bridge::new(Duration::from_secs(300)), + dialog: Bridge::with_program(Duration::from_secs(300), worker_program.clone()), fg_busy: false, bg_busy: false, + fg_job: None, + bg_job: None, notes_pending: false, pending_open: None, pending_save: false, @@ -147,6 +173,7 @@ impl Studio { smoke, startup: Instant::now(), _smoke_dir: smoke_dir, + worker_program, } } pub fn count(&self) -> usize { @@ -158,12 +185,12 @@ impl Studio { .map_or_else(|| "empty".into(), |d| d.key.clone()) } pub fn frame(&self, page: usize) -> Option> { - [2560, 1280, 320] + [self.target_edge, 512, 1280, 320] .iter() .find_map(|&edge| self.frames.get(&(page, edge)).cloned()) } pub fn full_frame(&self, page: usize) -> Option> { - [2560, 1280] + [self.target_edge, 512, 1280] .iter() .find_map(|&edge| self.frames.get(&(page, edge)).cloned()) } @@ -210,9 +237,12 @@ impl Studio { match action { Action::Open(path) => { if self.fg_busy { - self.fg = Bridge::new(Duration::from_secs(30)); + self.fg = + Bridge::with_program(Duration::from_secs(30), self.worker_program.clone()); self.fg_busy = false; + self.fg_job = None; } + self.loading = true; self.pending_open = Some(path); self.status = "Opening document in an isolated worker…".into(); } @@ -223,9 +253,13 @@ impl Studio { } Action::Go(page) => { if page < self.count() { - if page != self.requested && self.fg_busy { - self.fg = Bridge::new(Duration::from_secs(30)); + if page != self.requested && self.fg_busy && !self.loading { + self.fg = Bridge::with_program( + Duration::from_secs(30), + self.worker_program.clone(), + ); self.fg_busy = false; + self.fg_job = None; } self.requested = page; self.jump.clear(); @@ -294,7 +328,7 @@ impl Studio { } else if let Some(settings) = packet.reply.settings { if !self.smoke { self.settings = settings; - self.layout = self.settings.layout.clone(); + self.layout = self.settings.for_project(&self.project()); self.routes = Routes::default(); } self.dirty_routes = true; @@ -308,9 +342,7 @@ impl Studio { }; self.initialized = true; } - if self.initialized - && let Some(path) = self.open_path.take() - { + if let Some(path) = self.open_path.take() { self.execute(Action::Open(path)); } if self.pending_save @@ -350,8 +382,10 @@ impl Studio { }; if foreground { self.fg_busy = false; + self.fg_job = None; } else { self.bg_busy = false; + self.bg_job = None; } if c.generation != self.generation { continue; @@ -360,11 +394,18 @@ impl Studio { Ok(packet) => { if let Some(error) = packet.reply.error { self.status = error; - self.failed.insert(((c.tag >> 32) as usize, c.tag as u32)); + if c.tag == u64::MAX { + self.notes_loading = false; + } else if self.loading && foreground { + self.loading = false; + } else { + self.failed.insert(((c.tag >> 32) as usize, c.tag as u32)); + } continue; } if let Some(info) = packet.reply.info { if c.tag == u64::MAX { + self.notes_loading = false; if let Some(deck) = &mut self.deck { deck.notes = info.notes; deck.warnings = info.warnings; @@ -374,10 +415,22 @@ impl Studio { } continue; } + self.loading = false; + self.bg = Bridge::with_program( + Duration::from_secs(30), + self.worker_program.clone(), + ); + self.bg_busy = false; + self.bg_job = None; + self.notes_loading = false; self.notes_pending = true; + self.cached_slides = 0; self.generation += 1; self.frames.clear(); - self.order.clear(); + self.prepared.clear(); + self.preparation_started = Instant::now(); + self.output_buffered = 0; + self.ram_blocked = false; self.failed.clear(); self.requested = 0; self.displayed = None; @@ -393,28 +446,45 @@ impl Studio { self.new_output = true; } if let Some(info) = packet.reply.frame { - let key = (info.page, c.tag as u32); + let key = (info.page, packet.reply.edge.unwrap_or(c.tag as u32)); + if key.1 != self.target_edge && key.1 != 512 { + continue; + } + if key.1 == self.target_edge + && packet.reply.cached + && !self.prepared.contains(&key.0) + { + self.cached_slides += 1; + } let frame = Arc::new(Frame { info, rgba: packet.data, }); + if key.1 == self.target_edge { + self.frames.retain(|(page, edge), _| { + *page != key.0 || *edge == self.target_edge + }); + } self.frames.insert(key, frame); - self.order.retain(|k| *k != key); - self.order.push_back(key); - self.trim_cache(); + if key.1 == self.target_edge { + self.prepared.insert(key.0); + } + self.new_output = true; if key.0 == self.requested { self.new_output = true; - self.status = format!( - "Slide {} ready · {} cached frames", - self.requested + 1, - self.frames.len() - ); + self.status = format!("Slide {} ready", self.requested + 1); } } } Err(e) => { self.status = e; - self.failed.insert(((c.tag >> 32) as usize, c.tag as u32)); + if c.tag == u64::MAX { + self.notes_loading = false; + } else if self.loading && foreground { + self.loading = false; + } else { + self.failed.insert(((c.tag >> 32) as usize, c.tag as u32)); + } } } } @@ -438,11 +508,7 @@ impl Studio { } if self.deck.is_some() && self.pending_open.is_none() { if !self.fg_busy { - let edge = if self.frames.contains_key(&(self.requested, 1280)) { - 2560 - } else { - 1280 - }; + let edge = self.target_edge; if !self.frames.contains_key(&(self.requested, edge)) && !self.failed.contains(&(self.requested, edge)) { @@ -462,31 +528,81 @@ impl Studio { ) { self.notes_pending = false; + self.notes_loading = true; self.bg_busy = true; } - if !self.bg_busy { + // Use spare foreground capacity to prepare the tail while background fills forward. + // Interactive navigation still cancels/supersedes this work immediately. + if !self.fg_busy + && self.prepared.len() < self.count() + && let Some(page) = (0..self.count()).rev().find(|p| { + let key = (*p, self.target_edge); + !self.frames.contains_key(&key) + && !self.failed.contains(&key) + && Some(key) != self.bg_job + }) + { + self.schedule(page, self.target_edge, true); + } + if !self.bg_busy && self.prepared.len() < self.count() { let mut jobs = vec![]; - if self.requested + 1 < self.count() { - jobs.push((self.requested + 1, 1280)); - } - if self.requested > 0 { - jobs.push((self.requested - 1, 1280)); - } - for &page in &self.visible_thumbs { + for page in [self.requested + 1, self.requested.saturating_sub(1)] { if page < self.count() { - jobs.push((page, 320)); + jobs.push((page, self.target_edge)); } } - if let Some((page, edge)) = jobs - .into_iter() - .find(|key| !self.frames.contains_key(key) && !self.failed.contains(key)) - { + // Prepare the entire show, not just the currently visible neighbourhood. + jobs.extend((0..self.count()).map(|p| (p, self.target_edge))); + if let Some((page, edge)) = jobs.into_iter().find(|key| { + !self.frames.contains_key(key) + && Some(*key) != self.fg_job + && !self.failed.contains(key) + && key.0 != self.requested + }) { self.schedule(page, edge, false); } } } + if self.prepared.len() == self.count() { + self.ram_blocked = false; + } + let edge = self + .monitors + .iter() + .filter(|m| self.routes.presentation.contains(&m.id)) + .chain( + self.monitors + .iter() + .filter(|m| self.routes.presenter.contains(&m.id)), + ) + .map(|m| m.size.0.max(m.size.1)) + .max() + .unwrap_or(1920) + .clamp(512, 4096); + if edge != self.target_edge { + self.target_edge = edge; + self.prepared = self + .frames + .keys() + .filter(|(_, e)| *e == edge) + .map(|(p, _)| *p) + .collect(); + self.frames.retain(|(_, e), _| *e == edge || *e == 512); + self.preparation_started = Instant::now(); + self.cached_slides = 0; + self.output_buffered = 0; + self.ram_blocked = false; + self.new_output = true; + } } fn schedule(&mut self, page: usize, edge: u32, foreground: bool) { + // Reserve the worst-case square frame plus the other in-flight render. + let reserve = 2 * edge as usize * edge as usize * 4; + self.ram_blocked = self.buffer_bytes().saturating_add(reserve) + > self.settings.buffer_mib as usize * 1024 * 1024; + if self.ram_blocked { + return; + } let request = Request::Render { epoch: self.generation, path: self.deck.as_ref().unwrap().path.clone(), @@ -494,6 +610,17 @@ impl Studio { page, edge, }; + let request = if foreground && page == self.requested && self.frame(page).is_none() { + Request::Preview { + epoch: self.generation, + path: self.deck.as_ref().unwrap().path.clone(), + cache: self.cache_path.clone(), + page, + edge, + } + } else { + request + }; let bridge = if foreground { &self.fg } else { &self.bg }; if bridge.submit( self.generation, @@ -502,25 +629,92 @@ impl Studio { ) { if foreground { self.fg_busy = true; + self.fg_job = Some((page, edge)); } else { self.bg_busy = true; + self.bg_job = Some((page, edge)); } } } - fn trim_cache(&mut self) { - let mut bytes: usize = self.frames.values().map(|f| f.rgba.len()).sum(); - let count = self.order.len(); - for _ in 0..count { - if bytes <= 128 * 1024 * 1024 { - break; - } - if let Some(key) = self.order.pop_front() { - if key.0.abs_diff(self.requested) <= 1 { - self.order.push_back(key); - } else if let Some(frame) = self.frames.remove(&key) { - bytes -= frame.rgba.len(); + pub fn buffer_generation(&self) -> u64 { + (self.generation << 32) | u64::from(self.target_edge) + } + pub fn remember_buffer_budget(&mut self) { + self.pending_save = true; + self.ram_blocked = false; + self.new_output = true; + } + pub fn buffer_bytes(&self) -> usize { + self.frames.values().map(|f| f.rgba.len()).sum() + } + pub fn fully_buffered(&self) -> bool { + !self.loading + && self.count() > 0 + && self.prepared.len() == self.count() + && (self.routes.presentation.is_empty() || self.output_buffered == self.count()) + } + pub fn preparation_status(&self) -> String { + if self.loading { + return "Opening source and verifying cached slide identity… ETA estimating".into(); + } + if self.deck.is_none() { + return self.status.clone(); + } + let n = self.prepared.len(); + let total = self.count(); + let ram = self.buffer_bytes() / (1024 * 1024); + if self.notes_loading { + return format!( + "Reading presenter notes · {n}/{total} slides buffered · playback remains available" + ); + } + if self.fully_buffered() { + return format!( + "READY — all {total} slides buffered in RAM · {ram} MiB · {} px", + self.target_edge + ); + } + if self.ram_blocked { + return format!( + "RAM budget reached — {n}/{total} buffered. Increase the buffer in Menu; the show is not fully loaded." + ); + } + if !self.failed.is_empty() { + return format!( + "Preparation incomplete — {n}/{total} buffered; a slide failed. {}", + self.status + ); + } + let eta = if n >= 2 && n < total { + format!( + "~{} s remaining", + (self.preparation_started.elapsed().as_secs_f64() / n as f64 * (total - n) as f64) + .ceil() as u64 + ) + } else { + "estimating…".into() + }; + if n == total { + format!( + "Buffering presentation output — {}/{total} slides · {ram} MiB in presenter RAM · {}", + self.output_buffered, + if self.output_buffered > 0 { + format!( + "~{} s remaining", + (self.preparation_started.elapsed().as_secs_f64() + / self.output_buffered as f64 + * total.saturating_sub(self.output_buffered) as f64) + .ceil() as u64 + ) + } else { + "ETA estimating…".into() } - } + ) + } else { + format!( + "Preparing {} px — {n}/{total} slides · {ram} MiB · ETA {eta} · {} cached", + self.target_edge, self.cached_slides + ) } } } diff --git a/crates/pdf-presenter/src/worker.rs b/crates/pdf-presenter/src/worker.rs index ff50691..c200cc5 100644 --- a/crates/pdf-presenter/src/worker.rs +++ b/crates/pdf-presenter/src/worker.rs @@ -34,6 +34,13 @@ pub enum Request { path: PathBuf, cache: PathBuf, }, + Preview { + epoch: u64, + path: PathBuf, + cache: PathBuf, + page: usize, + edge: u32, + }, ReadFrame(PathBuf), LoadSettings(PathBuf), SaveSettings { @@ -53,6 +60,8 @@ pub struct Reply { pub settings: Option, pub picked: Option, pub bytes: usize, + pub edge: Option, + pub cached: bool, } pub struct ResultPacket { pub reply: Reply, @@ -134,6 +143,7 @@ pub fn run() -> Result<(), String> { let result = (|| -> Result { let mut reply = Reply::default(); let mut data = vec![]; + let preview = matches!(&request, Request::Preview { .. }); match request { Request::Open { epoch, path, cache } => { let doc = document::Document::open_slides(&path, cache)?; @@ -141,7 +151,14 @@ pub fn run() -> Result<(), String> { source = Some(doc); source_epoch = epoch; } - Request::Render { + Request::Preview { + epoch, + path, + cache, + page, + edge, + } + | Request::Render { epoch, path, cache, @@ -154,7 +171,16 @@ pub fn run() -> Result<(), String> { source_epoch = epoch; } let doc = source.as_ref().unwrap(); - let Frame { info, rgba } = doc.render(page, edge)?; + let (frame, actual_edge, cached) = + if let Some(frame) = doc.cached(page, edge)? { + (frame, edge, true) + } else { + let actual_edge = if preview { 512.min(edge) } else { edge }; + (doc.render(page, actual_edge)?, actual_edge, false) + }; + let Frame { info, rgba } = frame; + reply.edge = Some(actual_edge); + reply.cached = cached; reply.frame = Some(info); data = rgba; } diff --git a/crates/pdf-presenter/tests/native.rs b/crates/pdf-presenter/tests/native.rs index 65d5656..803df0d 100644 --- a/crates/pdf-presenter/tests/native.rs +++ b/crates/pdf-presenter/tests/native.rs @@ -100,10 +100,14 @@ fn independent_output_acknowledges_frames_and_blanking() { .1; let monitor = format!("{name}#1"); let temp = tempfile::tempdir().unwrap(); - let pdf = temp.path().join("host.pdf"); - common::pdf(&pdf); - let doc = Document::open(&pdf, temp.path().join("cache")).unwrap(); - let frames = [doc.render(0, 320).unwrap(), doc.render(1, 320).unwrap()]; + for page in 0..8 { + common::image( + &temp.path().join(format!("slide{page}.png")), + [page * 30, 128, 220, 255], + ); + } + let doc = Document::open(temp.path(), temp.path().join("cache")).unwrap(); + let frames: Vec<_> = (0..8).map(|page| doc.render(page, 320).unwrap()).collect(); struct ChildGuard(std::process::Child); impl Drop for ChildGuard { fn drop(&mut self) { @@ -129,12 +133,51 @@ fn independent_output_acknowledges_frames_and_blanking() { } } }); - for (sequence, page, blanked) in [(1, 0, false), (2, 1, false), (3, 1, true)] { + write_json( + &mut input, + &HostState { + generation: 99, + frame: Some(frames[0].info.clone()), + preload: frames.iter().map(|f| f.info.clone()).collect(), + buffer_mib: 256, + monitors: vec![monitor.clone()], + blanked: true, + ..Default::default() + }, + ) + .unwrap(); + let deadline = Instant::now() + Duration::from_secs(10); + loop { + let ack = rx + .recv_timeout(deadline.saturating_duration_since(Instant::now())) + .expect("full output buffer deadline"); + if ack.generation == 99 && ack.buffered == 8 { + break; + } + } + // The independent output must navigate entirely from RAM after preparation. + std::fs::remove_dir_all(temp.path().join("cache")).unwrap(); + for page in 0..8 { + std::fs::remove_file(temp.path().join(format!("slide{page}.png"))).unwrap(); + } + for (sequence, page, blanked) in [ + (1, 7, false), + (2, 0, false), + (3, 6, false), + (4, 1, false), + (5, 5, false), + (6, 2, false), + (7, 4, false), + (8, 3, true), + ] { write_json( &mut input, &HostState { sequence, page, + generation: 99, + preload: frames.iter().map(|f| f.info.clone()).collect(), + buffer_mib: 256, frame: Some(frames[page].info.clone()), monitors: vec![monitor.clone()], fullscreen: false, diff --git a/crates/pdf-presenter/tests/preparation.rs b/crates/pdf-presenter/tests/preparation.rs new file mode 100644 index 0000000..67001ef --- /dev/null +++ b/crates/pdf-presenter/tests/preparation.rs @@ -0,0 +1,176 @@ +mod common; +use pdf_presenter::studio::{Action, Monitor, Studio}; +use std::{ + path::{Path, PathBuf}, + time::{Duration, Instant}, +}; +fn studio(path: &Path, cache: &Path) -> Studio { + let mut s = Studio::with_program( + true, + Some(path.to_owned()), + env!("CARGO_BIN_EXE_pdf-presenter").into(), + ); + s.cache_path = cache.to_owned(); + s.set_monitors( + vec![Monitor { + id: "one".into(), + name: "one".into(), + origin: (0, 0), + size: (640, 480), + }], + 0, + ); + s +} +fn prepare(s: &mut Studio) { + let deadline = Instant::now() + Duration::from_secs(15); + while !s.fully_buffered() || s.notes_loading { + s.poll(); + assert!( + Instant::now() < deadline, + "{} / {}", + s.preparation_status(), + s.status + ); + std::thread::sleep(Duration::from_millis(2)); + } +} +fn artifacts(path: &Path) -> Vec { + let mut result = vec![]; + for entry in std::fs::read_dir(path).unwrap() { + let path = entry.unwrap().path(); + if path.is_dir() { + result.extend(artifacts(&path)); + } else if path.extension().is_some_and(|e| e == "rgba") { + result.push(path); + } + } + result +} +#[test] +fn whole_deck_stays_in_ram_and_warm_open_reuses_screen_sized_cache() { + let temp = tempfile::tempdir().unwrap(); + let dir = temp.path().join("slides"); + std::fs::create_dir(&dir).unwrap(); + for i in 0..8 { + common::image(&dir.join(format!("slide{i}.png")), [i * 30, 128, 200, 255]); + } + let cache = temp.path().join("processed"); + let mut first = studio(&dir, &cache); + prepare(&mut first); + assert_eq!(first.prepared.len(), 8); + assert_eq!(first.target_edge, 640); + assert!(first.preparation_status().starts_with("READY")); + let files = artifacts(&cache); + let timestamps: Vec<_> = files + .iter() + .filter(|p| p.file_name().unwrap().to_str().unwrap().contains("-640-")) + .map(|p| (p.clone(), std::fs::metadata(p).unwrap().modified().unwrap())) + .collect(); + assert_eq!(timestamps.len(), 8); + for p in &files { + if p.file_name().unwrap().to_str().unwrap().contains("-512-") { + std::fs::remove_file(p).unwrap(); + } + } + drop(first); + let mut warm = studio(&dir, &cache); + prepare(&mut warm); + assert_eq!(warm.cached_slides, 8); + for (path, time) in timestamps { + assert_eq!(std::fs::metadata(path).unwrap().modified().unwrap(), time); + } + assert!( + !artifacts(&cache).iter().any(|p| p + .file_name() + .unwrap() + .to_str() + .unwrap() + .contains("-512-")) + ); + // Once ready, even removing both sources and processed files cannot cause a slide read. + std::fs::remove_dir_all(&dir).unwrap(); + std::fs::remove_dir_all(&cache).unwrap(); + for page in [7, 0, 5, 1, 6, 2, 4, 3] { + warm.execute(Action::Go(page)); + warm.poll(); + assert!(warm.fully_buffered()); + assert_eq!(warm.full_frame(page).unwrap().info.page, page); + } + assert!(!cache.exists()); +} +#[test] +fn changing_screen_resolution_reprepares_and_readiness_waits_for_output() { + let temp = tempfile::tempdir().unwrap(); + let path = temp.path().join("show.pdf"); + common::pdf(&path); + let mut s = studio(&path, &temp.path().join("cache")); + prepare(&mut s); + let generation = s.buffer_generation(); + s.monitors[0].size = (800, 600); + s.poll(); + assert!(!s.fully_buffered()); + assert_ne!(generation, s.buffer_generation()); + prepare(&mut s); + assert_eq!(s.target_edge, 800); + assert_eq!(s.full_frame(0).unwrap().info.width, 800); + s.routes.presentation = vec!["output".into()]; + assert!(!s.fully_buffered()); + assert!( + s.preparation_status() + .contains("Buffering presentation output") + ); + s.output_buffered = s.count(); + assert!(s.fully_buffered()); + s.output_buffered = 0; + s.ram_blocked = true; + assert!(s.preparation_status().contains("RAM budget reached")); +} + +#[test] +fn preparation_pauses_at_ram_budget_and_resumes_without_evicting_ready_slides() { + let temp = tempfile::tempdir().unwrap(); + let pdf = temp.path().join("show.pdf"); + common::pdf(&pdf); + let mut s = studio(&pdf, &temp.path().join("cache")); + // An intentionally tiny internal test budget exercises pressure without huge allocations. + s.settings.buffer_mib = 1; + let deadline = Instant::now() + Duration::from_secs(5); + while !s.ram_blocked { + s.poll(); + assert!(Instant::now() < deadline); + std::thread::sleep(Duration::from_millis(2)); + } + assert!(!s.fully_buffered()); + assert!(s.preparation_status().contains("RAM budget reached")); + s.settings.buffer_mib = 256; + s.remember_buffer_budget(); + prepare(&mut s); + assert!(s.buffer_bytes() <= 256 * 1024 * 1024); + let frame = s.full_frame(0).unwrap(); + s.execute(Action::Go(1)); + s.poll(); + assert!(std::sync::Arc::ptr_eq(&frame, &s.full_frame(0).unwrap())); +} + +#[test] +fn navigating_buffered_show_during_failed_open_does_not_cancel_open_completion() { + let temp = tempfile::tempdir().unwrap(); + let path = temp.path().join("show.pdf"); + common::pdf(&path); + let mut s = studio(&path, &temp.path().join("cache")); + prepare(&mut s); + let frame = s.full_frame(1).unwrap(); + s.execute(Action::Open(temp.path().join("missing.pdf"))); + s.poll(); + s.execute(Action::Go(1)); + let deadline = Instant::now() + Duration::from_secs(5); + while s.loading { + s.poll(); + assert!(Instant::now() < deadline); + std::thread::sleep(Duration::from_millis(2)); + } + assert!(s.fully_buffered()); + assert_eq!(s.requested, 1); + assert!(std::sync::Arc::ptr_eq(&frame, &s.full_frame(1).unwrap())); +} diff --git a/crates/pdf-presenter/tests/settings.rs b/crates/pdf-presenter/tests/settings.rs index f3a129e..631bbde 100644 --- a/crates/pdf-presenter/tests/settings.rs +++ b/crates/pdf-presenter/tests/settings.rs @@ -6,6 +6,7 @@ fn settings_roundtrip_preserves_project_overrides_and_hidden_bars() { assert_eq!(settings::read(&path).unwrap().version, 1); let mut settings = Settings::default(); settings.layout.notes.size = 42.; + settings.buffer_mib = 2048; let mut project = Layout::default(); project.current.show = false; project.header = false; @@ -20,6 +21,7 @@ fn settings_roundtrip_preserves_project_overrides_and_hidden_bars() { assert_eq!(loaded.for_project("show"), project); assert_eq!(loaded.for_project("other").notes.size, 42.); assert_eq!(loaded.routes, settings.routes); + assert_eq!(loaded.buffer_mib, 2048); let bytes = std::fs::read(&path).unwrap(); settings.version = 2; assert!(settings::write(&path, &settings).is_err()); @@ -33,6 +35,9 @@ fn settings_reject_invalid_versions_ranges_and_duplicate_roles() { }; assert!(s.validate().is_err()); s.version = 1; + s.buffer_mib = 128; + assert!(s.validate().is_err()); + s.buffer_mib = 1024; s.layout.clock.size = f32::NAN; assert!(s.validate().is_err()); s.layout = Default::default(); @@ -49,6 +54,7 @@ fn settings_reject_invalid_versions_ranges_and_duplicate_roles() { assert!(settings::read(&p).is_err()); std::fs::write(&p, "version=1").unwrap(); assert!(settings::read(&p).unwrap().layout.header); + assert_eq!(settings::read(&p).unwrap().buffer_mib, 1024); } #[test] fn monitor_recovery_preserves_survivors_and_distinct_groups() { diff --git a/docs/changelog.md b/docs/changelog.md index e95a187..6d6e271 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -2,6 +2,20 @@ ## Unreleased +### 0.1.13 + +- Prepare every slide at the largest active screen resolution (4096-pixel edge cap), + using two supervised workers and a quick cold preview. Reopen verified processed + frames without rerendering or decoding; avoid redundant preview renders on cache hits. +- Retain the complete prepared deck in presenter and output RAM. READY requires both + buffers; preparation pauses explicitly at the configurable RAM budget instead of + evicting slides and incurring later disk reads. Resolution/host changes reset readiness. +- Show preparation stage, slide counts, cache reuse, RAM use and estimated time left; + retain a compact notification when menus are hidden. Keep errors visible separately. +- Test warm-cache reuse, budget pause/resume, resolution changes and navigation after + deleting source/cache files, including eight slides in the independent output host. + + ### 0.1.12 - Implement the approved native presenter workflow: independently sized/hidden widgets, diff --git a/docs/development/native-implementation.md b/docs/development/native-implementation.md index d1d3c94..fdccb77 100644 --- a/docs/development/native-implementation.md +++ b/docs/development/native-implementation.md @@ -1,4 +1,4 @@ -# Native implementation — 0.1.12 +# Native implementation — 0.1.12 and 0.1.13 The HTML approval is implemented in the native executable. This record supersedes starting-stack proposals in `implementation.md`; historical acceptance budgets still @@ -33,12 +33,19 @@ The minimal output process only receives raw frames and display/blank state, nev operator notes or menus. This establishes a software rendering baseline; it does not claim GPU-level throughput at every resolution. -Cold rendering requests 1280-pixel frames and then 2560 refinement. Neighbours and -visible thumbnails are prepared in the background, with no full-deck eager render. -Raw RGBA with dimensions and SHA-256 trailer avoids repeated image decode; disk -artifacts are disposable and namespaced by source hash and renderer. See -[cache](../interfaces/extraction-cache.md), [settings](../interfaces/settings.md) and -[private IPC](../interfaces/process-protocol.md) contracts. +0.1.13 replaces neighbour-only caching with whole-deck preparation and RAM residency. +A cold 512-pixel preview precedes screen-sized frames; warm verified full-size cache +hits skip that preview. Two workers fill the complete deck, and the independent +output acknowledges its own complete RAM buffer before READY. Small-screen outputs +share the largest screen-sized variant (4096-pixel cap). Progress, cache reuse, RAM +usage, approximate ETA and memory-pressure pause are explicit in the presenter. +No application slide-file reads, decoding or rasterization occur on prepared navigation. +OS paging can still occur; configuring enough available physical RAM remains necessary. + +The default decoded budget is 1024 MiB per process, adjustable in Menu. Insufficient +capacity pauses rather than evicts and never reports READY. Worker/texture memory is +additional. See [cache](../interfaces/extraction-cache.md), +[settings](../interfaces/settings.md) and [private IPC](../interfaces/process-protocol.md). The original single-process mock remains available through `--display-proof` for window-management comparison. It is not the default native presenter. @@ -101,3 +108,20 @@ benchmark or comparison against Pympress. The source PDF remains untracked and u These remain visible release gates; native workflow implementation is not a claim that the hard multiscreen/performance requirements have already been accepted. + +## 0.1.13 preparation regression evidence + +New tests prepare eight slides, reopen the same persistent cache without rewriting +artifacts or generating an unnecessary 512-pixel preview, then delete both source +and processed files before random navigation. Both the presenter-state test and the +independent native output-host test continue from resident frames. Additional tests +cover resolution-generation invalidation, output acknowledgment readiness, budget +pause/resume without eviction and backward-compatible settings defaults. This is +application I/O evidence, not an optical latency or OS-page-locking claim. + +Validation for 0.1.13: 37 Rust tests (including native window/output tests), 10 Python +helper tests, formatting and warnings-denied Clippy/rustdoc pass. The whole-application +coverage is 84.42% (75% floor), with no production exclusions. Linux and Windows release +artifacts are rebuilt, and macOS aarch64 is compile-checked. The native presenter was +visually inspected with the local PDF and showed all three slides buffered in RAM. +Navigating the previous buffered show while a new load fails is also regression-tested. diff --git a/docs/development/tasks.md b/docs/development/tasks.md index 68f57d8..a55e890 100644 --- a/docs/development/tasks.md +++ b/docs/development/tasks.md @@ -15,6 +15,11 @@ blanked output-host restart. T01 full latency instrumentation, T15 disk quota, T17 explicit notes-region crop, T18 reconnect, platform acceptance and clean-machine release checks remain open. Do not mark their broader acceptance from this code alone. +0.1.13 adds whole-deck processed-frame reuse and RAM preparation to T09/T12/T13: +two workers, screen-derived resolution, cache-first opening, retained complete buffers, +explicit preparation progress/ETA and memory-pressure pause. T01's full optical +latency matrix and T15's persistent disk quota remain open. + ## P0 — Instrumentation and two-display proof - [ ] T01: Add monotonic startup/input/frame markers, bounded logs and a benchmark diff --git a/docs/interfaces/examples/settings-v1.toml b/docs/interfaces/examples/settings-v1.toml index c5ae4e4..ad45590 100644 --- a/docs/interfaces/examples/settings-v1.toml +++ b/docs/interfaces/examples/settings-v1.toml @@ -2,6 +2,7 @@ version = 1 presenter_fullscreen = true presentation_fullscreen = true thumbnail_size = 220.0 +buffer_mib = 1024 [routes] presenter = ["Primary#1"] diff --git a/docs/interfaces/extraction-cache.md b/docs/interfaces/extraction-cache.md index 0dbd782..5270b08 100644 --- a/docs/interfaces/extraction-cache.md +++ b/docs/interfaces/extraction-cache.md @@ -26,9 +26,17 @@ its informational manifest. The manifest is not consumed for loading and cannot redirect a file read. Unsupported manifest versions are not imported. Cache files are disposable, not an interchange format or project representation. -First render uses a 1280-pixel edge, then current-slide refinement at 2560; -neighbours use 1280 and visible browser thumbnails 320. No eager whole-deck render. -Decoded presenter cache targets 128 MiB with current/adjacent slides pinned; -output retains at most six decoded frames. Disk eviction/quota remains outstanding. -A cache write failure reports an error and holds existing output. Source bytes -remain unchanged, including on malformed inputs and regeneration. +As of 0.1.13, a cold first frame uses a 512-pixel edge, then all slides are prepared +at the maximum pixel edge of connected presenter/presentation screens (512–4096). +Smaller screens share the largest variant. An exact verified target-size cache hit +bypasses preview rendering. Resolution changes use a distinct existing/new artifact +key. The disk schema remains v1; prior artifacts at matching resolutions remain usable. + +The entire decoded deck is retained in presenter and presentation-process RAM. +`buffer_mib` (default 1024 per process) bounds each decoded cache; render reservations +prevent overfilling the presenter budget. No eviction-based false READY state is +allowed. Insufficient capacity pauses preparation until the budget increases. +Only temporary preview/superseded-resolution frames are retired. Source/artifact +reads happen during preparation/recovery, not prepared navigation. OS paging and +software composition are outside this application-level no-file-read guarantee. +Disk eviction/quota remains outstanding; full disk reports an explicit error. diff --git a/docs/interfaces/process-protocol.md b/docs/interfaces/process-protocol.md index 2beda62..c712943 100644 --- a/docs/interfaces/process-protocol.md +++ b/docs/interfaces/process-protocol.md @@ -26,3 +26,18 @@ this is not optical proof that a projector displayed a frame. Heartbeats detect stopped host after 8 s; at most three starts, recovery blanked. A presenter crash leaves the independent host displaying its last frame. Normal exit sends quit and allows bounded shutdown outside the UI loop. Reconnection to an orphan is pending. + +## Whole-deck buffering in 0.1.13 + +Preview requests first check the verified target-resolution artifact, falling back to +512 only on a miss. Replies identify the actual requested render edge and cache-hit +status. The two workers prepare the remaining deck concurrently with foreground +navigation able to supersede outstanding work. + +HostState now carries a document/resolution generation, decoded RAM budget and the +complete available target-frame preload list. The host retains the whole prepared +deck, acknowledges the number buffered for that generation, and retires only temporary +previews or obsolete generations/resolutions. READY requires both presenter and host +counts to reach the deck total. Stale acknowledgments cannot mark another resolution +ready. The bounded JSON envelope and raw-frame limits remain unchanged. This protocol +still requires the same executable build at both ends. diff --git a/docs/interfaces/settings.md b/docs/interfaces/settings.md index 173a520..b6f7a18 100644 --- a/docs/interfaces/settings.md +++ b/docs/interfaces/settings.md @@ -25,6 +25,10 @@ flushed temporary file. Unknown fields are ignored and not preserved on round tr - `presenter_fullscreen`, `presentation_fullscreen`: booleans, default true. - `browser_monitor`: optional monitor ID; missing/unavailable means presenter screen. - `thumbnail_size`: logical width in pixels, finite 100–400; default 220. +- `buffer_mib`: integer 256–16384, default 1024, added in 0.1.13. Decoded slide RAM + allowance for each presenter/output process; one MiB = 1048576 bytes. Additional + worker/texture/UI memory is not included. Older v1 files default to 1024. The menu + persists changes asynchronously; lowering does not evict resident frames. Transient reveals, blank/current/selected slides, elapsed time, loaded document, Change on click and worker state are not persisted. HTML prototype localStorage is diff --git a/docs/user-guide.md b/docs/user-guide.md index 23f9109..d2b33b6 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -62,7 +62,47 @@ Choose another monitor in its toolbar. Preview size changes the grid. Clicking s without navigating unless Change on click is checked; it resets to OFF each time the browser opens. Show selected navigates explicitly and respects output blanking. The selected tile and current slide have distinct outlines. Closing the browser saves -its monitor and preview-size preferences. Only visible thumbnails are prepared. +its monitor and preview-size preferences. The grid uses the slides already in memory; +only visible thumbnail textures are retained. + +## Preparation, processed slides and RAM + +Opening a show starts two supervised preparation workers. The current slide gets a +512-pixel preview first if a verified full-resolution cache entry is unavailable. +Then the **entire deck** is prepared at the largest connected role screen's pixel +edge, preserving slide aspect ratio. Smaller screens use that same frame scaled to +fit; separate copies for every smaller resolution would waste RAM. The current +renderer limit is 4096 pixels per side, shown in Menu. Resolution changes start a +new preparation pass with a new buffer identity. + +Processed frames are kept in the application's persistent cache; Menu shows its +location. Reopening with unchanged source contents, resolution and renderer reuses +those frames without PDF rasterization or image decoding. It still verifies source +identity/checksums and reads frames into RAM: a restart cannot literally take zero +time. A warm full-size cached frame appears directly, without an unnecessary preview +render. Sources and their folders remain unchanged. + +The footer shows the active operation, slides prepared/total, cache reuse, decoded +RAM usage, and an approximate ETA once there are enough completed slides. It also +shows output-process buffering separately. A compact progress notification remains +visible while preparing if the footer is hidden. Notes reading and failures have +explicit status. ETAs use observed throughput and may change on complex slides. + +**READY** means every target-resolution slide is held in presenter RAM and, when +outputs are assigned, acknowledged in the independent presentation host's RAM. +Navigation then performs no application slide-file reads, PDF rendering or image +decoding. Raster composition still happens, and the OS can page memory under pressure. +The entire prepared deck stays resident instead of evicting distant slides. + +Menu → RAM budget controls the decoded-slide allowance for **each process**, default +1024 MiB, configurable from 256 to 16384 MiB. Presenter and output can each consume +that allowance; textures, workers and other application memory are additional. +Preparation reserves capacity for in-flight frames. If the deck cannot fit, it pauses +and reports that it is **not fully loaded**, rather than claiming READY and loading +slides later. Increase the budget within available physical RAM to resume. Lowering +the budget does not evict already buffered slides; reopen to apply a lower allocation +to an existing show. Cold rendering/decoding may continue while you present early. +After a host restart or resolution change, wait for READY again for RAM-only playback. ## Recovery and portability