Skip to main content

alpha2_eval/
evaluate.rs

1use crate::{
2    ActiveCaption, ActiveClip, ActiveComposition, ActiveEffect, ActiveIndex, ActiveTransition,
3    EvalError, FrameDesc, FrameNeed, collect_active, map_source_time, sample_visual,
4};
5use alpha2_model::{Project, TrackKind};
6use alpha2_time::{FrameRate, MediaTime, TICKS_PER_SECOND, TimeRange};
7
8/// Evaluates visual and audio clip descriptions at one timeline timestamp.
9///
10/// The result borrows identities and effects from `index`. Vectors are sized exactly, so an
11/// evaluation allocates one scratch list plus one list per non-empty field.
12///
13/// # Errors
14/// Returns an error for mismatched indexes or unrepresentable retiming.
15pub fn evaluate<'a>(
16    project: &'a Project,
17    index: &'a ActiveIndex,
18    time: MediaTime,
19) -> Result<FrameDesc<'a>, EvalError> {
20    ensure_index_matches(project, index)?;
21    let context = crate::SampleContext::timeline(project, &index.data);
22    let aspect = f64::from(project.settings.width) / f64::from(project.settings.height.max(1));
23    // No instant has more clips active than the index's deepest overlap.
24    let mut active = Vec::with_capacity(index.max_active);
25    if let Some(root) = index.root {
26        collect_active(&index.nodes, root, time, &mut active);
27    }
28    active.sort_unstable_by_key(|entry| (entry.track_order, entry.clip_order));
29
30    let visual_count = active
31        .iter()
32        .filter(|entry| entry.track_kind == TrackKind::Video)
33        .count();
34    let audio_count = active
35        .iter()
36        .filter(|entry| entry.track_kind == TrackKind::Audio)
37        .count();
38    // A caption lies over the clips of the tracks before it.
39    let captions = index
40        .captions
41        .iter()
42        .filter_map(|track| {
43            let cues = &track.captions.cues;
44            // Cues are ordered and disjoint, so only the last one starting at or before `time` can
45            // be active.
46            let candidate = cues.partition_point(|cue| cue.timeline_range.start() <= time);
47            let index = candidate.checked_sub(1)?;
48            let cue = &cues[index];
49            cue.timeline_range.contains(time).then(|| ActiveCaption {
50                track_id: &track.track_id,
51                text: &cue.text,
52                local_time: MediaTime(time.ticks() - cue.timeline_range.start().ticks()),
53                style: &track.styles[track.cue_styles[index]],
54                layers_below: active
55                    .iter()
56                    .filter(|entry| {
57                        entry.track_kind == TrackKind::Video
58                            && entry.track_order < track.track_order
59                    })
60                    .count(),
61            })
62        })
63        .collect();
64    let mut visual = Vec::with_capacity(visual_count);
65    let mut audio = Vec::with_capacity(audio_count);
66    let frame_mirror = crate::Mirror::frame(project.settings.frame_rate);
67    for entry in active {
68        let item = active_clip(entry, frame_mirror, time, aspect, &context)?;
69        match entry.track_kind {
70            TrackKind::Video => visual.push(item),
71            TrackKind::Audio => audio.push(item),
72            _ => {}
73        }
74    }
75    let frame_rate = project.settings.frame_rate;
76    let active_transitions = || {
77        index
78            .transitions
79            .iter()
80            .take_while(move |transition| transition.timeline_range.start() <= time)
81            .filter(move |transition| transition.timeline_range.contains(time))
82    };
83    let mut transitions = Vec::with_capacity(active_transitions().count());
84    transitions.extend(active_transitions().map(|transition| {
85        let linear_progress = centred_progress(transition.timeline_range, frame_rate, time);
86        // Transition shaders are defined on 0..=1; clamp overshooting curves.
87        #[allow(clippy::cast_possible_truncation)]
88        let progress = transition.easing.apply(linear_progress).clamp(0.0, 1.0) as f32;
89        ActiveTransition {
90            from_clip: &transition.from_clip,
91            to_clip: &transition.to_clip,
92            effect: ActiveEffect::new(&transition.effect, time, context),
93            progress,
94        }
95    }));
96    Ok(FrameDesc {
97        time,
98        background: Some(project.settings.background),
99        blend_space: project.settings.blend_space,
100        canvas: Some((project.settings.width, project.settings.height)),
101        visual,
102        audio,
103        transitions,
104        captions,
105    })
106}
107
108fn active_clip<'a>(
109    entry: &'a crate::IndexedClip,
110    frame_mirror: crate::Mirror,
111    time: MediaTime,
112    aspect: f64,
113    context: &crate::SampleContext<'a>,
114) -> Result<ActiveClip<'a>, EvalError> {
115    let source_time = map_source_time(
116        entry.timeline_range,
117        entry.source_range,
118        entry.time_map,
119        frame_mirror,
120        time,
121    )
122    .ok_or_else(|| EvalError::UnmappableClip {
123        clip: entry.clip_id.clone(),
124    })?;
125    Ok(ActiveClip {
126        clip_id: &entry.clip_id,
127        source_id: &entry.source_id,
128        track_id: &entry.track_id,
129        source_time,
130        visual: (entry.track_kind == TrackKind::Video)
131            .then(|| sample_visual(&entry.visual, time, aspect, context)),
132        composition: active_composition(entry, time)?.map(|plan| plan.with_data(*context)),
133        blend_mode: entry.blend_mode,
134        cache: entry.cache,
135        masks: &entry.masks,
136        matte: entry.matte.as_ref(),
137        is_matte: entry.is_matte,
138        generator: entry.generator.as_ref(),
139        plan: entry.plan.as_deref(),
140        source_composition: active_source_composition(entry, source_time)?
141            .map(|plan| plan.with_data(*context)),
142        data: *context,
143        correction: (entry.track_kind == TrackKind::Video)
144            .then(|| {
145                crate::data::clip_correction(
146                    &entry.visual,
147                    (entry.timeline_range, entry.source_range, entry.time_map),
148                    time,
149                    context,
150                )
151            })
152            .flatten(),
153    })
154}
155
156fn active_source_composition(
157    entry: &crate::IndexedClip,
158    source_time: MediaTime,
159) -> Result<Option<ActiveComposition<'_>>, EvalError> {
160    entry
161        .source_composition
162        .as_ref()
163        .filter(|_| entry.track_kind == TrackKind::Video)
164        .map(|(id, plan)| {
165            plan.as_ref()
166                .as_ref()
167                .map(|plan| ActiveComposition::new(plan, source_time))
168                .map_err(|reason| EvalError::IncompleteComposition {
169                    clip: entry.clip_id.clone(),
170                    composition: id.clone(),
171                    reason: reason.clone(),
172                })
173        })
174        .transpose()
175}
176
177fn active_composition(
178    entry: &crate::IndexedClip,
179    time: MediaTime,
180) -> Result<Option<ActiveComposition<'_>>, EvalError> {
181    let Some(indexed) = entry
182        .composition
183        .as_ref()
184        .filter(|_| entry.track_kind == TrackKind::Video)
185    else {
186        return Ok(None);
187    };
188    let plan =
189        indexed
190            .plan
191            .as_ref()
192            .as_ref()
193            .map_err(|reason| EvalError::IncompleteComposition {
194                clip: entry.clip_id.clone(),
195                composition: indexed.reference.id.clone(),
196                reason: reason.clone(),
197            })?;
198    let local = indexed
199        .reference
200        .local_time(entry.timeline_range.start(), time)
201        .ok_or_else(|| EvalError::UnmappableClip {
202            clip: entry.clip_id.clone(),
203        })?;
204    Ok(Some(ActiveComposition::new(plan, local)))
205}
206
207/// A transition's linear progress, `clamp((t - start + F/2) / D, 0, 1)`.
208///
209/// `F` is one project frame and `D` the duration. Sampling at frame centres makes frame `i` of
210/// `N` show `(i + 0.5) / N`, so every frame mixes both clips and reversed playback shows `1 - p`.
211fn centred_progress(range: TimeRange, frame_rate: FrameRate, time: MediaTime) -> f64 {
212    let elapsed = i128::from(time.ticks()) - i128::from(range.start().ticks());
213    let duration = i128::from(range.end().ticks()) - i128::from(range.start().ticks());
214    // F / 2 = TICKS_PER_SECOND * den / (2 * num); scale by 2 * num to stay exact until the division.
215    let num = i128::from(frame_rate.numerator());
216    let den = i128::from(frame_rate.denominator());
217    let numerator = 2 * num * elapsed + i128::from(TICKS_PER_SECOND) * den;
218    let denominator = 2 * num * duration;
219    #[allow(clippy::cast_precision_loss)]
220    let progress = (numerator as f64 / denominator as f64).clamp(0.0, 1.0);
221    progress
222}
223
224/// Describes all source frames needed at a timestamp.
225///
226/// The list is in evaluation order with no duplicate `(source, timestamp)` pairs. Generated
227/// sources and audio clips need no frames. A visual clip needs its own source only when it draws
228/// it ([`ActiveClip::needs_source`]) plus every source its composition reads. A matte clip needs
229/// frames only while an active clip names it ([`FrameDesc::draws`]).
230///
231/// # Errors
232///
233/// Returns any error emitted by [`evaluate`].
234pub fn frame_needs(
235    project: &Project,
236    index: &ActiveIndex,
237    time: MediaTime,
238) -> Result<Vec<FrameNeed>, EvalError> {
239    let frame = evaluate(project, index, time)?;
240    let mut needs = Needs::default();
241    for item in frame.visual.iter().filter(|item| frame.draws(item)) {
242        if item.needs_source() {
243            needs.ask(item.clip_id, item.source_id, item.source_time, || None);
244        }
245        let plans = item
246            .composition
247            .iter()
248            .map(|composition| (composition, false))
249            .chain(
250                item.source_composition
251                    .iter()
252                    .map(|composition| (composition, true)),
253            );
254        for (composition, of_source) in plans {
255            let steps = &composition.plan().steps;
256            for (step, source_id, time) in composition.media() {
257                let node = &steps[step].node;
258                // Prefix source-composition steps with `/`, which no own-composition path starts with.
259                needs.ask(item.clip_id, source_id, time, || {
260                    if of_source {
261                        alpha2_model::NodeId::new(format!("/{node}")).ok()
262                    } else {
263                        Some(node.clone())
264                    }
265                });
266            }
267        }
268    }
269    Ok(needs.list)
270}
271
272/// Needs deduplicated by linear scan before switching to a hash set. Frames usually need only a
273/// few sources, but a composition may read tens of thousands.
274pub(crate) const SCANNED_NEEDS: usize = 32;
275
276#[cfg(test)]
277thread_local! {
278    /// Comparisons made by [`Needs::ask`] on this thread.
279    pub(crate) static COMPARED: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
280}
281
282#[derive(Default)]
283struct Needs<'a> {
284    list: Vec<FrameNeed>,
285    /// Needs past the first [`SCANNED_NEEDS`], borrowing IDs so lookups clone nothing.
286    hashed: std::collections::HashSet<(&'a alpha2_media::SourceId, MediaTime)>,
287}
288
289impl<'a> Needs<'a> {
290    /// Records `source_id` at `media_time` unless already recorded. `reader` runs only for a new
291    /// need.
292    fn ask(
293        &mut self,
294        clip_id: &alpha2_model::ClipId,
295        source_id: &'a alpha2_media::SourceId,
296        media_time: MediaTime,
297        reader: impl FnOnce() -> Option<alpha2_model::NodeId>,
298    ) {
299        let scanned = &self.list[..self.list.len().min(SCANNED_NEEDS)];
300        #[cfg(test)]
301        COMPARED.with(|compared| compared.set(compared.get() + scanned.len()));
302        let repeat = scanned
303            .iter()
304            .any(|need| need.media_time == media_time && need.source_id == *source_id)
305            || (self.list.len() > SCANNED_NEEDS && self.hashed.contains(&(source_id, media_time)));
306        if repeat {
307            return;
308        }
309        if self.list.len() >= SCANNED_NEEDS {
310            self.hashed.insert((source_id, media_time));
311        }
312        self.list.push(FrameNeed {
313            clip_id: clip_id.clone(),
314            reader: reader(),
315            source_id: source_id.clone(),
316            media_time,
317        });
318    }
319}
320
321pub(crate) fn ensure_index_matches(
322    project: &Project,
323    index: &ActiveIndex,
324) -> Result<(), EvalError> {
325    if project.id == index.project_id {
326        Ok(())
327    } else {
328        Err(EvalError::IndexProjectMismatch {
329            index_project: index.project_id.clone(),
330            evaluated_project: project.id.clone(),
331        })
332    }
333}