From 8a479a4922dc246462556bce030aa669a052a3ef Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 7 Nov 2026 19:52:49 +0100 Subject: [PATCH] Doc comments for the functions this PR touches --- apps/effectcraft-web/src/store.rs | 1 + crates/automation/src/confine.rs | 14 ++++++++++++++ crates/engine/src/background/remote.rs | 1 + crates/engine/src/cmd/path_nulls.rs | 2 ++ crates/engine/src/cmd/prop.rs | 2 ++ crates/engine/src/cmd/rig3d.rs | 1 + crates/engine/src/cmd/three_d.rs | 1 + crates/expr/src/host.rs | 1 + crates/expr/src/sample.rs | 2 ++ crates/media/src/pool.rs | 4 ++++ crates/media/src/reads.rs | 3 +++ crates/media/src/stream.rs | 2 ++ crates/project/src/reach.rs | 2 ++ crates/render/src/cache.rs | 8 ++++++++ crates/render/src/disk_cache.rs | 9 +++++++++ crates/render/src/disk_cache/entry_files.rs | 11 +++++++++++ crates/render/src/eval.rs | 1 + crates/render/src/footage.rs | 2 ++ crates/render/src/fx_host.rs | 1 + crates/render/src/pipeline.rs | 4 ++++ crates/render/src/reads.rs | 7 +++++++ crates/render/src/three_d/adv/scene.rs | 3 +++ crates/text/src/fonts.rs | 2 ++ crates/ui-egui/src/frames.rs | 9 +++++++++ crates/ui-egui/src/panels/viewer.rs | 1 + crates/ui-egui/src/panels/viewer/shapes.rs | 1 + 26 files changed, 95 insertions(+) diff --git a/apps/effectcraft-web/src/store.rs b/apps/effectcraft-web/src/store.rs index abda69a77..a4947600b 100644 --- a/apps/effectcraft-web/src/store.rs +++ b/apps/effectcraft-web/src/store.rs @@ -189,6 +189,7 @@ pub struct Store { } impl Default for Store { + /// An empty store with no mirror contents, change callback or clock. fn default() -> Self { Self { mirror: Mutex::default(), on_change: OnceLock::new(), clock: OnceLock::new() } } diff --git a/crates/automation/src/confine.rs b/crates/automation/src/confine.rs index 55fa8043c..570726932 100644 --- a/crates/automation/src/confine.rs +++ b/crates/automation/src/confine.rs @@ -363,32 +363,41 @@ thread_local! { static REFUSED_READS: std::cell::Cell = const { std::cell::Cell::new(0) }; } +/// The number of reads this thread has refused for lying outside the allowed roots. fn refused_reads() -> u64 { REFUSED_READS.try_with(std::cell::Cell::get).unwrap_or(0) } impl FootageSource for ConfinedFootage { + /// The frame from the inner source, or `None` when the footage lies outside the allowed roots. fn frame(&self, item: ItemId, footage: &Footage, t: Tick) -> Option> { self.readable(footage).then(|| self.inner.frame(item, footage, t)).flatten() } + /// The frame scaled to `width` by `height`, or `None` when the footage lies outside the allowed roots. fn frame_at_size(&self, item: ItemId, footage: &Footage, t: Tick, width: u32, height: u32) -> Option> { self.readable(footage).then(|| self.inner.frame_at_size(item, footage, t, width, height)).flatten() } + /// The frame with an explicit size and float curve, or `None` when the footage lies outside the allowed roots. fn frame_with(&self, item: ItemId, footage: &Footage, t: Tick, size: Option<(u32, u32)>, float: FloatCurve) -> Option> { self.readable(footage).then(|| self.inner.frame_with(item, footage, t, size, float)).flatten() } + /// The footage audio from the inner source, or `None` when the footage lies outside the allowed roots. fn audio(&self, item: ItemId, footage: &Footage, t: Tick, frames: usize, rate: u32) -> Option> { self.readable(footage).then(|| self.inner.audio(item, footage, t, frames, rate)).flatten() } + /// The auxiliary channels of the footage frame, or `None` when the footage lies outside the allowed roots. fn aux(&self, item: ItemId, footage: &Footage, t: Tick) -> Option> { self.readable(footage).then(|| self.inner.aux(item, footage, t)).flatten() } + /// Forwards the auxiliary footage paths to the inner source. fn set_aux_footage(&self, paths: &[String]) { self.inner.set_aux_footage(paths) } + /// The 3D model for the footage, or `None` when the footage lies outside the allowed roots. fn model(&self, item: ItemId, footage: &Footage) -> Option> { self.readable(footage).then(|| self.inner.model(item, footage)).flatten() } + /// The rasterised vector footage at `scale`, or `None` when the footage lies outside the allowed roots. fn vector_frame(&self, item: ItemId, footage: &Footage, scale: f64) -> Option> { self.readable(footage).then(|| self.inner.vector_frame(item, footage, scale)).flatten() } @@ -411,12 +420,15 @@ impl FootageSource for ConfinedFootage { fn set_conform_folder(&self, folder: Option) { self.inner.set_conform_folder(folder) } + /// The inner source's cache budget. fn cache_budget(&self) -> Option { self.inner.cache_budget() } + /// Runs `f` under the inner source's cancel flag. fn cancellable(&self, cancel: &Arc, f: &mut dyn FnMut()) { self.inner.cancellable(cancel, f) } + /// Whether the inner source has been called off. fn called_off(&self) -> bool { self.inner.called_off() } @@ -632,10 +644,12 @@ mod tests { /// Reads every file, noting it. struct Noting; impl FootageSource for Noting { + /// Returns a 1x1 frame and notes the footage path it was asked for. fn frame(&self, _: ItemId, f: &Footage, _: Tick) -> Option> { NOTED.with(|n| n.borrow_mut().push(f.path.clone())); Some(Arc::new(Image::new(1, 1))) } + /// Runs `f`, then reports every path noted meanwhile to `reads` as a file with a missing stamp. fn recording(&self, reads: &ReadLog, f: &mut dyn FnMut()) { f(); for p in NOTED.with(|n| std::mem::take(&mut *n.borrow_mut())) { diff --git a/crates/engine/src/background/remote.rs b/crates/engine/src/background/remote.rs index 153bb324b..aea210ec5 100644 --- a/crates/engine/src/background/remote.rs +++ b/crates/engine/src/background/remote.rs @@ -289,6 +289,7 @@ struct Pending { pub const MAX_PASSES: u32 = 24; impl FrameServer { + /// A frame server over `footage` and the optional expression host, with an empty layer cache. pub fn new(footage: Arc, expr: Option>) -> FrameServer { FrameServer { footage, diff --git a/crates/engine/src/cmd/path_nulls.rs b/crates/engine/src/cmd/path_nulls.rs index a6b51c763..6da43afde 100644 --- a/crates/engine/src/cmd/path_nulls.rs +++ b/crates/engine/src/cmd/path_nulls.rs @@ -73,6 +73,8 @@ struct PathInfo { span: (f64, f64), } +/// Reads a mask or shape path at the current time and returns its comp-space vertices, value, expression reference and layer name. +/// Errors when the property is missing, is not a path or has no vertices. fn info(s: &Session, cid: ItemId, lid: LayerId, uid: Uid, cmd: &str) -> Result { let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?; let layer = comp.layer(lid).ok_or(EngineError::NoComp)?; diff --git a/crates/engine/src/cmd/prop.rs b/crates/engine/src/cmd/prop.rs index 70d123957..b23e73575 100644 --- a/crates/engine/src/cmd/prop.rs +++ b/crates/engine/src/cmd/prop.rs @@ -1380,6 +1380,8 @@ fn convert_expr_to_keys(s: &mut Session, p: &Value) -> Result { convert_one_expr(s, cid, lid, uid) } +/// Replaces the expression on one property with keyframes sampled from its evaluated values. +/// Returns the number of properties converted. fn convert_one_expr(s: &mut Session, cid: ItemId, lid: LayerId, uid: Uid) -> Result { let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?.clone(); let layer = comp.layer(lid).ok_or(EngineError::NoComp)?.clone(); diff --git a/crates/engine/src/cmd/rig3d.rs b/crates/engine/src/cmd/rig3d.rs index e7852fbd2..58a4281a8 100644 --- a/crates/engine/src/cmd/rig3d.rs +++ b/crates/engine/src/cmd/rig3d.rs @@ -47,6 +47,7 @@ impl Env { fn of(s: &Session, cid: ItemId) -> Env { Env { time: s.time_of(cid), expr: s.expr.clone(), footage: s.footage.clone() } } + /// The evaluation context of `comp` in `proj` at the session's current time. fn ctx<'a>(&'a self, proj: &'a Project, cid: ItemId, comp: &'a Comp) -> EvalCtx<'a> { EvalCtx { project: proj, diff --git a/crates/engine/src/cmd/three_d.rs b/crates/engine/src/cmd/three_d.rs index de6bc4d7a..58d5d3bc2 100644 --- a/crates/engine/src/cmd/three_d.rs +++ b/crates/engine/src/cmd/three_d.rs @@ -418,6 +418,7 @@ fn set_view_camera(s: &mut Session, p: &Value) -> Result { Ok(json!({"view": v.id()})) } +/// Returns the active comp's 3D view state, with the comp size, for the 3D view commands. fn get_3d(s: &mut Session, p: &Value) -> Result { let cid = comp_id(s, p)?; let comp = s.project.comp(cid).ok_or(EngineError::NoComp)?; diff --git a/crates/expr/src/host.rs b/crates/expr/src/host.rs index b0abcaafa..43400ea1d 100644 --- a/crates/expr/src/host.rs +++ b/crates/expr/src/host.rs @@ -297,6 +297,7 @@ impl<'a> Resolver<'a> { } self.comp(c)?.layer(LayerId(l)) } + /// The evaluation context for comp `c` at time `t` seconds, or `None` when the comp does not exist. fn ctx_at(&self, c: u64, t: f64) -> Option> { let comp = self.comp(c)?; let same_comp = c == self.ctx.comp_id.0; diff --git a/crates/expr/src/sample.rs b/crates/expr/src/sample.rs index e097691de..38f617289 100644 --- a/crates/expr/src/sample.rs +++ b/crates/expr/src/sample.rs @@ -46,6 +46,8 @@ fn fingerprint(layer: &Layer) -> u64 { h.finish() } +/// Renders `layer` of `comp` at time `t` for an expression sample, before or after effects as `post` says. +/// Returns `None` once the nesting depth limit is reached. fn render(ctx: EvalCtx, comp: ItemId, layer: &Layer, post: bool, t: f64) -> Option { let depth = DEPTH.with(|d| *d.borrow()); if depth >= MAX_DEPTH { diff --git a/crates/media/src/pool.rs b/crates/media/src/pool.rs index 4b7b05603..ab4a47568 100644 --- a/crates/media/src/pool.rs +++ b/crates/media/src/pool.rs @@ -110,6 +110,7 @@ struct Lru { } impl Lru { + /// The cached image and its read files for `k`, marking the entry as most recently used. fn get(&mut self, k: &Key) -> Option<(Arc, Arc)> { let e = self.map.get_mut(k)?; self.order.remove(&e.stamp); @@ -118,6 +119,7 @@ impl Lru { self.order.insert(e.stamp, k.clone()); Some((e.img.clone(), e.files.clone())) } + /// Stores an image with its read files under `k` and evicts the least recently used entries until the cache fits `budget` bytes. fn insert(&mut self, k: Key, img: Arc, files: Arc, budget: usize) { let bytes = img.data.len() * std::mem::size_of::() + 64; self.clock += 1; @@ -905,6 +907,8 @@ impl Inner { } } + /// Decodes the still image at `loc` and applies the footage alpha and float handling. + /// A placeholder path decodes to colour bars. fn decode_still(&self, loc: &Loc, footage: &Footage) -> Result { let op = AlphaOp::of(footage, loc.float); let path = &loc.key.path; diff --git a/crates/media/src/reads.rs b/crates/media/src/reads.rs index 29b2fafac..43ea209b8 100644 --- a/crates/media/src/reads.rs +++ b/crates/media/src/reads.rs @@ -64,6 +64,8 @@ enum Out<'a> { } impl Scope<'_> { + /// Starts collecting the files read on this thread into `out`. + /// At the nesting limit the scope stays closed and reports an incomplete list. fn open(out: Out<'_>) -> Scope<'_> { let opened = SCOPES .try_with(|s| match s.try_borrow_mut() { @@ -79,6 +81,7 @@ impl Scope<'_> { } impl Drop for Scope<'_> { + /// Ends the scope and hands the collected files to its output, marked incomplete when the scope could not be opened. fn drop(&mut self) { let files = if self.opened { SCOPES.try_with(|s| s.try_borrow_mut().ok().and_then(|mut s| s.pop())).ok().flatten() } else { None }; // A scope that could not open saw nothing: what it made can't name its files. diff --git a/crates/media/src/stream.rs b/crates/media/src/stream.rs index 99b1cb774..0155b4acd 100644 --- a/crates/media/src/stream.rs +++ b/crates/media/src/stream.rs @@ -26,6 +26,7 @@ pub(crate) struct FileReader { #[cfg(any(unix, windows))] impl FileReader { + /// Opens `path` for reading and records its length and modification time. pub(crate) fn open(path: &Path) -> std::io::Result { #[cfg(test)] crate::count_open(path); @@ -87,6 +88,7 @@ pub(crate) fn open_source(path: &Path) -> Option<(Result, FileStam Some((opened.map_err(Into::into), stamp)) } +/// Without a native file system there is no in-place source: always `None`. #[cfg(not(any(unix, windows)))] pub(crate) fn open_source(_path: &Path) -> Option<(Result, FileStamp)> { None diff --git a/crates/project/src/reach.rs b/crates/project/src/reach.rs index dd510f9db..4cfde8385 100644 --- a/crates/project/src/reach.rs +++ b/crates/project/src/reach.rs @@ -197,6 +197,8 @@ pub fn expression_reach(text: &str) -> ExprReach { expression_names(text).map_or(ExprReach::Anything, |(comps, footage)| ExprReach::Names { comps, footage }) } +/// The comp names and footage names an expression references by literal name. +/// Returns `None` when it can reach anything by a computed name or cannot be tokenised. fn expression_names(text: &str) -> Option<(Vec, Vec)> { let toks = tokens(text)?; let (mut comps, mut footage) = (Vec::new(), Vec::new()); diff --git a/crates/render/src/cache.rs b/crates/render/src/cache.rs index 692a80576..a1bd85290 100644 --- a/crates/render/src/cache.rs +++ b/crates/render/src/cache.rs @@ -117,6 +117,7 @@ impl LayerCache { } } + /// The attached disk cache, if any. pub fn disk(&self) -> Option> { self.disk.lock().ok()?.clone() } @@ -137,6 +138,7 @@ impl LayerCache { } } + /// The attached virtual-file identity lookup, if any. fn virtual_id(&self) -> Option { self.virtual_id.lock().ok()?.clone() } @@ -329,6 +331,7 @@ struct Fetched { used: u64, } +/// The memory a buffer's pixels take, in bytes. fn buf_bytes(b: &Buf) -> usize { b.img.data.len().saturating_mul(std::mem::size_of::()) } @@ -346,12 +349,14 @@ struct Prefetched { } impl Prefetched { + /// Records a missed key for prefetching, up to a fixed bound. fn note_miss(&mut self, key: u128) { if !self.misses.contains(&key) && self.misses.len() < 1024 { self.misses.push(key); } } + /// Drops the prefetched entry for `key` and frees its bytes. fn remove(&mut self, key: u128) { if let Some(f) = self.ready.remove(&key) { self.bytes = self.bytes.saturating_sub(buf_bytes(&f.buf)); @@ -425,6 +430,7 @@ impl PrefetchStore { } impl LayerStore for PrefetchStore { + /// The prefetched layer for `key` with its read files, or `None` when it is not ready. fn get_layer(&self, key: u128, virtual_id: Option>) -> Option<(Arc, ReadFiles)> { let found = { let mut s = self.st.lock().ok()?; @@ -459,6 +465,7 @@ impl LayerStore for PrefetchStore { Some((buf, files.to_read_files())) } + /// Queues the layer for writing to the persistent store the first time `key` is seen. fn put_layer(&self, key: u128, buf: &Buf, files: &EntryFiles, _since: u64) { let Ok(mut s) = self.st.lock() else { return }; if s.known.insert(key) { @@ -810,6 +817,7 @@ fn key_any(ctx: &EvalCtx, layer: &Layer, scale: f64, draft: bool, blur: bool, fo /// Set Matte…)? Those layers are drawn by the reading layer's renderer, so the switches it /// passes down belong in the key (`Renderer::nested_look`). pub(crate) fn reads_layers(ctx: &EvalCtx, layer: &Layer) -> bool { + /// Whether any enabled layer-valued property of `layer` points at another layer. fn reads(ctx: &EvalCtx, layer: &Layer, g: &PropGroup, depth: usize) -> bool { depth < 32 && g.children.iter().any(|n| match n { diff --git a/crates/render/src/disk_cache.rs b/crates/render/src/disk_cache.rs index 67fbc4a7c..c334c2011 100644 --- a/crates/render/src/disk_cache.rs +++ b/crates/render/src/disk_cache.rs @@ -300,6 +300,7 @@ struct Drops { } impl Drops { + /// Notes that the given paths were dropped, bumping the generation and tracking them for later checks. fn record(&mut self, paths: &[Arc]) { self.generation = self.generation.saturating_add(1); if self.last.len().saturating_add(paths.len()) > MAX_DROPPED_PATHS { @@ -320,6 +321,7 @@ impl Drops { } impl Queue { + /// Takes the next queued job, frames first, and releases the bytes it held. #[cfg(not(target_arch = "wasm32"))] fn pop(&mut self) -> Option { if let Some(j) = self.frames.pop_front() { @@ -1081,6 +1083,7 @@ fn with_files(files: &EntryFiles, pixels: Vec) -> Vec { out } +/// The writer thread: evicts to the limit at open, then drains the job queue until the cache is dropped. #[cfg(not(target_arch = "wasm32"))] fn writer(dc: std::sync::Weak, q: Arc<(Mutex, Condvar)>) { let (m, cv) = &*q; @@ -1208,12 +1211,15 @@ impl effectcraft_effects::roto::SegStore for DiskCache { } impl crate::cache::LayerStore for DiskCache { + /// The layer for `key` from the disk cache, or `None` when it is missing or stale. fn get_layer(&self, key: u128, virtual_id: Option>) -> Option<(Arc, ReadFiles)> { DiskCache::get_layer(self, key, virtual_id).map(|(b, f)| (Arc::new(b), f)) } + /// Queues a layer write on the disk cache. fn put_layer(&self, key: u128, buf: &Buf, files: &EntryFiles, since: u64) { DiskCache::put_layer(self, key, buf, files, since); } + /// The current drop generation of the disk cache. fn drop_generation(&self) -> u64 { DiskCache::drop_generation(self) } @@ -1325,6 +1331,7 @@ fn encode_layer(b: &Buf) -> Vec { out } +/// Decodes a stored layer payload into a buffer, or `None` when it is too short or damaged. fn decode_layer(p: &[u8]) -> Option { if p.len() < 32 { return None; @@ -1357,6 +1364,7 @@ fn decode_layer(p: &[u8]) -> Option { /// Bump when rendering changes in a way that makes old disk entries wrong. const RENDER_VERSION: &str = "effectcraft-render-6"; +/// Feeds the `Debug` form of `v` into the hash, followed by a separator byte. fn hash_debug(h: &mut Hash128, v: &impl std::fmt::Debug) { h.write(format!("{v:?}").as_bytes()); h.write(&[0xff]); @@ -1401,6 +1409,7 @@ pub fn comp_content_key(project: &effectcraft_project::Project, comp: effectcraf comp_content_key_for_renderer(project, comp, RENDER_VERSION) } +/// The content key of `comp` for one renderer: its settings, the comps and footage it uses, and the renderer name. fn comp_content_key_for_renderer(project: &effectcraft_project::Project, comp: effectcraft_project::ItemId, renderer: &str) -> u128 { use effectcraft_project::ItemKind; let mut h = Hash128::default(); diff --git a/crates/render/src/disk_cache/entry_files.rs b/crates/render/src/disk_cache/entry_files.rs index 4ebd1f2e6..a36ca1033 100644 --- a/crates/render/src/disk_cache/entry_files.rs +++ b/crates/render/src/disk_cache/entry_files.rs @@ -63,14 +63,17 @@ impl EntryFiles { Some(EntryFiles(out)) } + /// The listed files. pub fn files(&self) -> &[EntryFile] { &self.0 } + /// The number of listed files. pub fn len(&self) -> usize { self.0.len() } + /// Whether no files are listed. pub fn is_empty(&self) -> bool { self.0.is_empty() } @@ -96,6 +99,7 @@ impl EntryFiles { self.0.iter().all(|f| file_unchanged(f, virtual_id)) } + /// Appends the list to `out` in little-endian binary form. pub(super) fn encode(&self, out: &mut Vec) { out.extend_from_slice(&(self.0.len() as u32).to_le_bytes()); for f in &self.0 { @@ -153,6 +157,7 @@ impl EntryFiles { } } +/// Whether the file still matches its stored stamp, by its native stamp or by its in-memory identity. fn file_unchanged(f: &EntryFile, virtual_id: Option>) -> bool { let from_memory = || virtual_id.and_then(|id| id(&f.path)); match f.stamp { @@ -167,20 +172,25 @@ fn file_unchanged(f: &EntryFile, virtual_id: Option>) -> bool struct Reader<'a>(&'a [u8]); impl<'a> Reader<'a> { + /// Takes the next `n` bytes, or `None` when fewer remain. fn take(&mut self, n: usize) -> Option<&'a [u8]> { let head = self.0.get(..n)?; self.0 = self.0.get(n..)?; Some(head) } + /// Reads one byte. fn u8(&mut self) -> Option { self.take(1)?.first().copied() } + /// Reads a little-endian `u32`. fn u32(&mut self) -> Option { Some(u32::from_le_bytes(self.take(4)?.try_into().ok()?)) } + /// Reads a little-endian `u64`. fn u64(&mut self) -> Option { Some(u64::from_le_bytes(self.take(8)?.try_into().ok()?)) } + /// Reads a little-endian `i128`. fn i128(&mut self) -> Option { Some(i128::from_le_bytes(self.take(16)?.try_into().ok()?)) } @@ -190,6 +200,7 @@ impl<'a> Reader<'a> { mod tests { use super::*; + /// A sample list of native, missing and virtual files for the tests. fn files() -> ReadFiles { [ ReadFile::new("/a.png", FileStamp::Native { len: 3, modified: Some(9) }), diff --git a/crates/render/src/eval.rs b/crates/render/src/eval.rs index e900ffa6e..5a0a3dea3 100644 --- a/crates/render/src/eval.rs +++ b/crates/render/src/eval.rs @@ -50,6 +50,7 @@ pub struct EvalCtx<'a> { } impl<'a> EvalCtx<'a> { + /// A context for `comp` at `time` with no expressions, footage, overrides or read log. pub fn new(project: &'a Project, comp_id: ItemId, comp: &'a Comp, time: Tick) -> EvalCtx<'a> { EvalCtx { project, comp_id, comp, time, expr: None, footage: None, property_overrides: &[], media_overrides: &[], reads: None } } diff --git a/crates/render/src/footage.rs b/crates/render/src/footage.rs index 04957b34e..0e17f152d 100644 --- a/crates/render/src/footage.rs +++ b/crates/render/src/footage.rs @@ -204,6 +204,7 @@ impl FootageSource for CancellableFootage<'_> { fn called_off(&self) -> bool { self.cancel.load(Ordering::Relaxed) || self.inner.called_off() } + /// Runs `f` with the inner source, collecting the files it reads into `reads`. fn recording(&self, reads: &ReadLog, f: &mut dyn FnMut()) { self.inner.recording(reads, f) } @@ -224,6 +225,7 @@ pub fn is_vector_footage(f: &Footage) -> bool { pub struct NoFootage; impl FootageSource for NoFootage { + /// Always `None`: there is no footage. fn frame(&self, _: ItemId, _: &Footage, _: Tick) -> Option> { None } diff --git a/crates/render/src/fx_host.rs b/crates/render/src/fx_host.rs index 9b1700df8..3a6f1a34c 100644 --- a/crates/render/src/fx_host.rs +++ b/crates/render/src/fx_host.rs @@ -95,6 +95,7 @@ impl EffectHost for FxHost<'_, '_, '_> { Some(self.pixels(other, buf, false)) } + /// The audio of footage layer `id` from `start`, or `None` when the layer is not footage. fn audio(&self, id: u64, start: f64, frames: usize, rate: u32) -> Option> { let other = self.ctx.layer(effectcraft_project::LayerId(id))?; let LayerSource::Footage { item } = &other.source else { return None }; diff --git a/crates/render/src/pipeline.rs b/crates/render/src/pipeline.rs index 6a0be930d..be3c3da8f 100644 --- a/crates/render/src/pipeline.rs +++ b/crates/render/src/pipeline.rs @@ -102,6 +102,7 @@ fn collapsed_instance(ctx: &EvalCtx, layer: &Layer, item: ItemId) -> Option<(Vec } impl<'a> Renderer<'a> { + /// A renderer over `project` and `footage` with the given options. pub fn new(project: &'a Project, footage: &'a dyn FootageSource, opts: RenderOpts) -> Renderer<'a> { Renderer { project, @@ -446,6 +447,7 @@ impl<'a> Renderer<'a> { } } + /// The evaluation context of `comp` at `t`, carrying this renderer's expressions, footage and read log. pub(crate) fn ctx(&self, comp_id: ItemId, comp: &'a Comp, t: Tick) -> EvalCtx<'a> { EvalCtx { project: self.project, @@ -936,6 +938,8 @@ impl<'a> Renderer<'a> { if per_pixel { Some(Arc::new(interpret_pixels(&img, f, self.pipe.linear_footage_space(f)))) } else { Some(img) } } + /// The footage frame at source time `t` after frame blending: the average of the source frames one comp frame spans, else a blend of the two neighbouring frames, else the plain frame. + /// Log scans are converted first, and blended frames are cached. fn footage_frame_raw(&self, ctx: &EvalCtx, layer: &Layer, item: ItemId, f: &Footage, t: Tick, size: Option<(u32, u32)>) -> Option> { let mode = frame_blend_mode(ctx, layer); let float = self.pipe.float_curve(f); diff --git a/crates/render/src/reads.rs b/crates/render/src/reads.rs index 91a0b10bf..326554c5b 100644 --- a/crates/render/src/reads.rs +++ b/crates/render/src/reads.rs @@ -59,6 +59,7 @@ pub struct ReadFile { } impl ReadFile { + /// A file read with the given path and stamp. pub fn new(path: impl Into>, stamp: FileStamp) -> ReadFile { ReadFile { path: path.into(), stamp } } @@ -128,16 +129,19 @@ impl ReadFiles { self.files.get(i).map(|f| f.stamp) } + /// The number of files in the list. pub fn len(&self) -> usize { self.files.len() } + /// Whether the list holds no files. pub fn is_empty(&self) -> bool { self.files.is_empty() } } impl FromIterator for ReadFiles { + /// Collects files into a list, adding each in turn. fn from_iter>(iter: I) -> Self { let mut out = ReadFiles::default(); for f in iter { @@ -155,10 +159,12 @@ pub struct ReadLog { } impl ReadLog { + /// An empty read log. pub fn new() -> ReadLog { ReadLog::default() } + /// Locks the file list, recovering from a poisoned lock. fn lock(&self) -> std::sync::MutexGuard<'_, ReadFiles> { self.files.lock().unwrap_or_else(PoisonError::into_inner) } @@ -196,6 +202,7 @@ impl ReadLog { mod tests { use super::*; + /// A native file with the given length for the tests. fn file(path: &str, len: u64) -> ReadFile { ReadFile::new(path, FileStamp::Native { len, modified: Some(7) }) } diff --git a/crates/render/src/three_d/adv/scene.rs b/crates/render/src/three_d/adv/scene.rs index 9166dc4a4..6d2b071d5 100644 --- a/crates/render/src/three_d/adv/scene.rs +++ b/crates/render/src/three_d/adv/scene.rs @@ -477,6 +477,7 @@ fn clip_start(ctx: &EvalCtx, layer: &Layer, prop: &Property, lt: Tick) -> Tick { start } +/// Adds a model layer to the Advanced 3D scene with its material options, opacity and world transform. fn model_layer(r: &Renderer, ctx: &EvalCtx, layer: &Layer, b: &mut Builder) { let lin = b.s.linear_io; let (opts, prim_mat) = model_options(ctx, layer, lin); @@ -651,6 +652,7 @@ pub fn extruded_meshes(ctx: &EvalCtx, layer: &Layer, p: &model::extrude::Extrude out } +/// Adds an extruded layer to the Advanced 3D scene with its card material, opacity and world transform. fn extruded_layer(r: &Renderer, ctx: &EvalCtx, layer: &Layer, p: &model::extrude::ExtrudeParams, b: &mut Builder) { let base = card_material(ctx, layer); let opacity = (ctx.opacity(layer) as f32 * r.opacity_mul()).clamp(0.0, 1.0); @@ -694,6 +696,7 @@ fn card(b: &mut Builder, buf: &Buf, world: Mat4, mut mat: Material) { b.emit(&p, m, &|_| world); } +/// Adds a flat card layer to the Advanced 3D scene with its material, opacity and world transform. fn card_layer(r: &Renderer, ctx: &EvalCtx, layer: &Layer, b: &mut Builder) { let mut mat = card_material(ctx, layer); mat.opacity = (ctx.opacity(layer) as f32 * r.opacity_mul()).clamp(0.0, 1.0); diff --git a/crates/text/src/fonts.rs b/crates/text/src/fonts.rs index f9ad858eb..d199bf0ff 100644 --- a/crates/text/src/fonts.rs +++ b/crates/text/src/fonts.rs @@ -208,6 +208,7 @@ pub struct VMetrics { } impl Face { + /// The font file bytes, loaded once on first use, or `None` when they cannot be read. fn bytes(&self) -> Option<&[u8]> { self.bytes .get_or_init(|| match &self.info.data { @@ -356,6 +357,7 @@ fn db() -> &'static RwLock { }) } +/// Adds a face to the database and returns its id. fn push(db: &mut Db, info: FaceInfo) -> FaceId { let id = db.faces.len(); db.faces.push(Arc::new(Face { id, info, bytes: OnceLock::new(), file_meta: OnceLock::new(), shaper: OnceLock::new() })); diff --git a/crates/ui-egui/src/frames.rs b/crates/ui-egui/src/frames.rs index 14c3f32ef..c369d8194 100644 --- a/crates/ui-egui/src/frames.rs +++ b/crates/ui-egui/src/frames.rs @@ -180,6 +180,7 @@ struct Cached { struct DiskSince(std::sync::Weak, u64); impl DiskSince { + /// A marker for the drop generation of `dc` at the time of a render. fn of(dc: &Arc, generation: u64) -> DiskSince { DiskSince(Arc::downgrade(dc), generation) } @@ -294,6 +295,7 @@ impl Cache { self.gpu_bytes = self.gpu_bytes.saturating_sub(img.bytes()); } } + /// Removes the entry for `k` and releases its image. fn remove(&mut self, k: &FrameKey) { if let Some(i) = self.map.remove(k) { self.forget(&i.img); @@ -371,6 +373,7 @@ struct ContentKeyJobs { pending: VecDeque<(Arc, u64, u64)>, } +/// The content key of `comp` at `revision`, memoised per revision. fn content_key(keys: &ContentKeys, project: &Project, revision: u64, comp: u64) -> u128 { if let Some(k) = keys.lock().ok().and_then(|m| m.get(&(revision, comp)).copied()) { return k; @@ -1183,6 +1186,7 @@ impl Frames { } } + /// Queues a background hash of `comp` at `revision`, coalescing rapid edits so only a bounded number of snapshots are kept. #[cfg(not(target_arch = "wasm32"))] fn request_content_key(&self, project: Arc, revision: u64, comp: u64) { let mut jobs = self.content_key_jobs.lock().unwrap_or_else(std::sync::PoisonError::into_inner); @@ -1235,6 +1239,7 @@ impl Frames { self.cache.lock().map(|c| c.budget).unwrap_or(0) } + /// Drops every cached frame and purges the remote server, if there is one. pub fn clear(&self) { if let Some(r) = &self.remote { r.purge(); @@ -1428,6 +1433,7 @@ impl Frames { } } + /// A render worker sharing this cache's queue, cache and in-flight set. fn worker(&self) -> Worker { Worker { queue: self.queue.clone(), @@ -1701,6 +1707,7 @@ impl Worker { self.finish_key(job.key, job.urgent, img, files, since, t0); } + /// Stores a finished frame in the cache with its read files, records the render time for urgent jobs, then releases the job. fn finish_key(&self, key: FrameKey, urgent: bool, img: FrameImage, files: Option>, since: Option, t0: web_time::Instant) { if urgent && let Ok(mut l) = self.last.lock() { *l = t0.elapsed().as_secs_f64() * 1000.0; @@ -1769,12 +1776,14 @@ impl Worker { } } + /// Tells the cache that a GPU render succeeded. fn gpu_succeeded(&self) { if let Ok(mut c) = self.cache.lock() { c.gpu_succeeded(); } } + /// Whether GPU rendering is available and has not been retired. fn gpu_ready(&self) -> bool { !self.gpu_retired.load(Ordering::Acquire) && self.cache.lock().is_ok_and(|c| c.gpu_ready()) } diff --git a/crates/ui-egui/src/panels/viewer.rs b/crates/ui-egui/src/panels/viewer.rs index 1e214ab53..cd0006c0f 100644 --- a/crates/ui-egui/src/panels/viewer.rs +++ b/crates/ui-egui/src/panels/viewer.rs @@ -143,6 +143,7 @@ struct Vw<'a> { puppet_layers: Vec<(&'a Layer, super::puppet_tool::Overlay)>, } +/// Draws the viewer panel in `rect` for the active comp and handles its input. pub fn show(app: &mut EffectcraftApp, ui: &mut egui::Ui, rect: Rect) { let t = app.tokens; let ctx = ui.ctx().clone(); diff --git a/crates/ui-egui/src/panels/viewer/shapes.rs b/crates/ui-egui/src/panels/viewer/shapes.rs index 903abd42f..76892cbaf 100644 --- a/crates/ui-egui/src/panels/viewer/shapes.rs +++ b/crates/ui-egui/src/panels/viewer/shapes.rs @@ -200,6 +200,7 @@ fn bounds_of(pts: &[Pos2]) -> Option { Some(r) } +/// Creates the shape for a drag from `a` to `b` with the given tool, as a mask or as a shape layer. pub(super) fn create_shape(app: &mut EffectcraftApp, tool: Tool, a: [f64; 2], b: [f64; 2], mods: egui::Modifiers) { let Some(d) = shape_drag(app, tool, a, b, mods) else { return }; let (kind, (w, h), (cx, cy)) = (d.kind, (d.size[0], d.size[1]), (d.centre[0], d.centre[1]));