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}