mirror of
https://github.com/storytold/effectcraft.git
synced 2026-11-20 09:05:51 +00:00
Doc comments for the functions this PR touches
This commit is contained in:
1 parent
ac34105a57
commit
8a479a4922
26 files changed
+95
No files matched your search
@@ -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 {
|
||||
|
||||
@@ -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) }),
|
||||
|
||||
@@ -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 }
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
@@ -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 };
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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) })
|
||||
}
|
||||
|
||||
@@ -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);
|
||||
|
||||
Reference in new issue
Block a user