Doc comments for the functions this PR touches

This commit is contained in:
vangel76 committed 2026-11-07 19:52:49 +01:00
1 parent ac34105a57
commit 8a479a4922
26 files changed
+95

No files matched your search

+8
View File
@@ -117,6 +117,7 @@ impl LayerCache {
}
}
/// The attached disk cache, if any.
pub fn disk(&self) -> Option<Arc<crate::disk_cache::DiskCache>> {
self.disk.lock().ok()?.clone()
}
@@ -137,6 +138,7 @@ impl LayerCache {
}
}
/// The attached virtual-file identity lookup, if any.
fn virtual_id(&self) -> Option<SharedVirtualFileId> {
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::<effectcraft_raster::Px>())
}
@@ -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<VirtualFileId<'_>>) -> Option<(Arc<Buf>, 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 {
+9
View File
@@ -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<str>]) {
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<Job> {
if let Some(j) = self.frames.pop_front() {
@@ -1081,6 +1083,7 @@ fn with_files(files: &EntryFiles, pixels: Vec<u8>) -> Vec<u8> {
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<DiskCache>, q: Arc<(Mutex<Queue>, 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<VirtualFileId<'_>>) -> Option<(Arc<Buf>, 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<u8> {
out
}
/// Decodes a stored layer payload into a buffer, or `None` when it is too short or damaged.
fn decode_layer(p: &[u8]) -> Option<Buf> {
if p.len() < 32 {
return None;
@@ -1357,6 +1364,7 @@ fn decode_layer(p: &[u8]) -> Option<Buf> {
/// 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();
@@ -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<u8>) {
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<VirtualFileId<'_>>) -> 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<VirtualFileId<'_>>) -> 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<u8> {
self.take(1)?.first().copied()
}
/// Reads a little-endian `u32`.
fn u32(&mut self) -> Option<u32> {
Some(u32::from_le_bytes(self.take(4)?.try_into().ok()?))
}
/// Reads a little-endian `u64`.
fn u64(&mut self) -> Option<u64> {
Some(u64::from_le_bytes(self.take(8)?.try_into().ok()?))
}
/// Reads a little-endian `i128`.
fn i128(&mut self) -> Option<i128> {
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) }),
+1
View File
@@ -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 }
}
+2
View File
@@ -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<Arc<Image>> {
None
}
+1
View File
@@ -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<Vec<f32>> {
let other = self.ctx.layer(effectcraft_project::LayerId(id))?;
let LayerSource::Footage { item } = &other.source else { return None };
+4
View File
@@ -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<Arc<Image>> {
let mode = frame_blend_mode(ctx, layer);
let float = self.pipe.float_curve(f);
+7
View File
@@ -59,6 +59,7 @@ pub struct ReadFile {
}
impl ReadFile {
/// A file read with the given path and stamp.
pub fn new(path: impl Into<Arc<str>>, 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<ReadFile> for ReadFiles {
/// Collects files into a list, adding each in turn.
fn from_iter<I: IntoIterator<Item = ReadFile>>(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) })
}
+3
View File
@@ -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);