Skip to main content

alpha2_eval/
frame.rs

1use crate::{EffectParamValue, SampleContext, sample_effect_param};
2use alpha2_media::SourceId;
3use alpha2_model::{
4    BlendSpace, ClipBlendMode, ClipEffect, ClipId, EffectResourceId, Generator, Matte, Rgb,
5    ShapeMask, TextStyle, TrackId, Vec2,
6};
7use alpha2_time::MediaTime;
8
9/// A timestamp-specific composition description with no GPU handles.
10///
11/// Identities and authored effects are borrowed from the [`crate::ActiveIndex`] (`'a`), so
12/// evaluating a frame copies none of them.
13#[derive(Clone, Debug, PartialEq)]
14pub struct FrameDesc<'a> {
15    /// Timestamp evaluated on the project timeline.
16    pub time: MediaTime,
17    /// Opaque color under every visual layer, or `None` for transparent black (alpha output).
18    pub background: Option<Rgb>,
19    /// The space in which blend modes are evaluated.
20    pub blend_space: BlendSpace,
21    /// The project canvas in pixels, which effects sized in project pixels refer to; `None`
22    /// draws them at the render size.
23    pub canvas: Option<(u32, u32)>,
24    /// Active visual clips in composition order.
25    pub visual: Vec<ActiveClip<'a>>,
26    /// Active audio clips in mix order.
27    pub audio: Vec<ActiveClip<'a>>,
28    /// Active two-input transitions by start, then track order, then position in their track's
29    /// `transitions`. The engine's fold makes the picture independent of this order.
30    pub transitions: Vec<ActiveTransition<'a>>,
31    /// The cue each caption track shows, in track order.
32    pub captions: Vec<ActiveCaption<'a>>,
33}
34
35impl FrameDesc<'_> {
36    /// Whether the frame draws `clip`'s picture. A matte ([`ActiveClip::is_matte`]) is drawn
37    /// only while an active clip names it.
38    #[must_use]
39    pub fn draws(&self, clip: &ActiveClip<'_>) -> bool {
40        !clip.is_matte
41            || self.visual.iter().any(|other| {
42                other
43                    .matte
44                    .is_some_and(|matte| &matte.source == clip.clip_id)
45            })
46    }
47}
48
49/// The cue one caption track shows at a timestamp.
50#[derive(Clone, Copy, Debug, PartialEq)]
51pub struct ActiveCaption<'a> {
52    /// The caption track.
53    pub track_id: &'a TrackId,
54    /// The cue's text.
55    pub text: &'a alpha2_model::TextContent,
56    /// Time since the cue started, which keys its style's animators.
57    pub local_time: alpha2_time::MediaTime,
58    /// The track style with the cue's (or else its speaker's) named style patch applied.
59    pub style: &'a TextStyle,
60    /// How many [`FrameDesc::visual`] clips lie under the caption by track order, counting clips
61    /// the frame does not draw ([`FrameDesc::draws`]) so an undrawn clip never shifts a caption.
62    pub layers_below: usize,
63}
64
65/// A visible or audible clip mapped to its source timestamp.
66#[derive(Clone, Copy, Debug, PartialEq)]
67pub struct ActiveClip<'a> {
68    /// Active clip identity.
69    pub clip_id: &'a ClipId,
70    /// Media source needed for this clip.
71    pub source_id: &'a SourceId,
72    /// Track containing the clip.
73    pub track_id: &'a TrackId,
74    /// Source timestamp selected by the clip's time map.
75    pub source_time: MediaTime,
76    /// Evaluated visual presentation, present only for visual tracks.
77    pub visual: Option<EvaluatedVisual>,
78    /// The composition that builds the clip's picture; `None` shows the source as is.
79    pub composition: Option<crate::ActiveComposition<'a>>,
80    /// Artistic blend operation used by visual composition.
81    pub blend_mode: ClipBlendMode,
82    /// Whether a runtime may keep and reuse the clip's rendered picture.
83    pub cache: alpha2_model::CacheIntent,
84    /// Shape masks in order. Evaluate outlines with [`crate::evaluate_geometry`] and feathers with
85    /// [`crate::sample_scalar`] at the frame's time.
86    pub masks: &'a [ShapeMask],
87    /// The clip whose picture sets where this one is visible.
88    pub matte: Option<&'a Matte>,
89    /// Whether this clip is another clip's matte, drawn only into that matte.
90    pub is_matte: bool,
91    /// Generated source content, drawn at `source_time` with no host frame.
92    pub generator: Option<&'a Generator>,
93    /// Planned shapes or layout generator tree, to evaluate at `source_time`.
94    pub plan: Option<&'a crate::GeneratorPlan>,
95    /// For a composition source, its composition at the clip's source time (no host frame).
96    pub source_composition: Option<crate::ActiveComposition<'a>>,
97    /// What the clip's timeline-time values (its masks) read data through.
98    pub data: SampleContext<'a>,
99    /// The correction drawn between the clip's finished picture and its visual, when it has one
100    /// with a value at this time.
101    pub correction: Option<crate::Correction>,
102}
103
104impl ActiveClip<'_> {
105    /// Whether the clip draws its own host-supplied source frame.
106    #[must_use]
107    pub fn needs_source(&self) -> bool {
108        self.generator.is_none()
109            && self.source_composition.is_none()
110            && self
111                .composition
112                .is_none_or(|composition| composition.plan().uses_clip())
113    }
114}
115
116/// Visual properties evaluated at one timeline timestamp.
117#[derive(Copy, Clone, Debug, PartialEq)]
118pub struct EvaluatedVisual {
119    /// Normalized output translation.
120    pub position: Vec2,
121    /// Normalized source anchor.
122    pub anchor: Vec2,
123    /// Per-axis scale.
124    pub scale: Vec2,
125    /// Clockwise rotation in degrees.
126    pub rotation_degrees: f32,
127    /// Opacity from zero to one.
128    pub opacity: f32,
129}
130
131/// A source-frame request emitted for host prefetch and decode scheduling.
132#[derive(Clone, Debug, PartialEq, Eq)]
133pub struct FrameNeed {
134    /// Clip consumer that owns the sequential decoder cursor.
135    ///
136    /// Multiple clips may read the same source at unrelated timestamps. Hosts
137    /// must not make those clips share one seek position.
138    pub clip_id: ClipId,
139    /// The composition step reading the source, if not the clip itself: its
140    /// [`crate::Step::node`] path, prefixed with `/` for steps of a composition source. Each
141    /// (clip, reader) pair keeps its own decoder cursor.
142    pub reader: Option<alpha2_model::NodeId>,
143    /// Source to decode or retrieve.
144    pub source_id: SourceId,
145    /// Timestamp requested on the source timeline.
146    pub media_time: MediaTime,
147}
148
149/// A transition evaluated at one timeline timestamp.
150#[derive(Clone, Copy, Debug, PartialEq)]
151pub struct ActiveTransition<'a> {
152    /// Clip sampled at progress zero.
153    pub from_clip: &'a ClipId,
154    /// Clip sampled at progress one.
155    pub to_clip: &'a ClipId,
156    /// Versioned shader invocation, with parameters sampled at the frame's time.
157    pub effect: ActiveEffect<'a>,
158    /// Eased progress in the inclusive unit interval.
159    pub progress: f32,
160}
161
162/// One effect invocation at one timestamp (timeline time for transitions, composition time for
163/// composition steps).
164#[derive(Clone, Copy, Debug, PartialEq)]
165pub struct ActiveEffect<'a> {
166    effect: &'a ClipEffect,
167    time: MediaTime,
168    context: SampleContext<'a>,
169}
170
171impl<'a> ActiveEffect<'a> {
172    /// The invocation `effect` sampled at `time`, with data bindings read through `context`.
173    #[must_use]
174    pub const fn new(effect: &'a ClipEffect, time: MediaTime, context: SampleContext<'a>) -> Self {
175        Self {
176            effect,
177            time,
178            context,
179        }
180    }
181
182    /// Stable effect definition identifier.
183    #[must_use]
184    pub fn id(&self) -> &'a str {
185        &self.effect.id
186    }
187
188    /// Exact effect definition version.
189    #[must_use]
190    pub const fn version(&self) -> u32 {
191        self.effect.version
192    }
193
194    /// Every authored parameter sampled at this timestamp. Omitted ones use definition defaults.
195    pub fn params(&self) -> impl Iterator<Item = (&'a str, EffectParamValue)> + 'a {
196        let time = self.time;
197        let context = self.context;
198        self.effect.params.iter().map(move |(name, animation)| {
199            (
200                name.as_str(),
201                sample_effect_param(animation, time, &context),
202            )
203        })
204    }
205
206    /// One parameter sampled at this timestamp, if the invocation sets it.
207    #[must_use]
208    pub fn param(&self, name: &str) -> Option<EffectParamValue> {
209        self.effect
210            .params
211            .get(name)
212            .map(|animation| sample_effect_param(animation, self.time, &self.context))
213    }
214
215    /// Named external resources matched against the effect definition.
216    pub fn resources(&self) -> impl Iterator<Item = (&'a str, &'a EffectResourceId)> + 'a {
217        self.effect
218            .resources
219            .iter()
220            .map(|(name, id)| (name.as_str(), id))
221    }
222
223    /// The authored invocation, with its parameters unevaluated.
224    #[must_use]
225    pub const fn authored(&self) -> &'a ClipEffect {
226        self.effect
227    }
228}