Skip to main content

alpha2_render/cpu/
execute.rs

1//! Runs a render graph on the CPU with the GPU executor's walk (`graph_execute.rs`), drawing
2//! each node into a [`CpuImage`] by row bands.
3
4use std::sync::Arc;
5use std::sync::atomic::Ordering;
6
7use alpha2_media::YuvEncoding;
8use web_time::Instant;
9
10use super::CpuRenderer;
11use super::composite::{CompositeSettings, LayerInput, composite};
12use super::half;
13use super::image::{CpuImage, PixelBox};
14use super::kernels::{CpuLut, KernelContext};
15use super::renderer::add_elapsed;
16use crate::graph::{RenderGraph, RenderNode, RenderNodeId};
17use crate::graph_cache::renderer_node_key;
18use crate::{
19    CacheEligibility, CacheIntent, EffectId, EffectKind, EffectParams, EffectResources,
20    EffectRuntime, GraphError, RenderCacheKey, RenderError, Yuv420pTargets,
21};
22
23struct KernelNode<'a> {
24    effect: &'a EffectId,
25    kind: EffectKind,
26    source_a: Option<RenderNodeId>,
27    source_b: Option<RenderNodeId>,
28    inputs: Vec<(&'a str, RenderNodeId)>,
29    params: &'a EffectParams<'a>,
30    resources: &'a EffectResources,
31    runtime: EffectRuntime,
32}
33
34impl CpuRenderer {
35    /// Draws the reachable part of `graph` and returns its output.
36    ///
37    /// # Errors
38    /// A structural error or the first pass failure: [`RenderError::UnknownEffect`] for an effect
39    /// without a CPU kernel, [`RenderError::InvalidSource`] for a GPU source.
40    #[allow(clippy::too_many_lines)]
41    pub fn execute_graph(&self, graph: &RenderGraph<'_>) -> Result<Arc<CpuImage>, GraphError> {
42        let started = Instant::now();
43        let quality = self.quality_controls();
44        let plan = graph.compile_with_quality(quality)?;
45        if matches!(graph.nodes[plan.output.index], RenderNode::Source(_)) {
46            return Err(GraphError::SourceOutput);
47        }
48        let blend_space = graph.blend_space.unwrap_or(self.blend_space);
49        let cached =
50            self.cached_results(graph, &plan.order, plan.output, blend_space.shader_value());
51        let mut outputs: Vec<Option<Arc<CpuImage>>> = vec![None; graph.nodes.len()];
52        let mut inserts = Vec::new();
53        let mut drawn = 0_u64;
54        let mut high_water = 0_u64;
55        for (position, node) in plan.order.iter().copied().enumerate() {
56            if let Some(hit) = cached.hits[node.index].clone() {
57                outputs[node.index] = Some(hit);
58                release_inputs(graph, &plan.last_use, &mut outputs, node, position);
59                continue;
60            }
61            if !cached.needed[node.index] {
62                release_inputs(graph, &plan.last_use, &mut outputs, node, position);
63                continue;
64            }
65            let node_started = Instant::now();
66            let image = match &graph.nodes[node.index] {
67                RenderNode::Source(view) => {
68                    let source = view.cpu_source().ok_or(RenderError::InvalidSource)?;
69                    source.presented(self)
70                }
71                RenderNode::Effect {
72                    effect,
73                    source,
74                    inputs,
75                    params,
76                    resources,
77                    runtime,
78                } => Arc::new(self.draw_kernel(
79                    graph,
80                    &outputs,
81                    &KernelNode {
82                        effect,
83                        kind: EffectKind::Effect,
84                        source_a: Some(*source),
85                        source_b: None,
86                        inputs: inputs.iter().collect(),
87                        params,
88                        resources,
89                        runtime: *runtime,
90                    },
91                )?),
92                RenderNode::Transition {
93                    effect,
94                    from,
95                    to,
96                    params,
97                    resources,
98                    runtime,
99                } => Arc::new(self.draw_kernel(
100                    graph,
101                    &outputs,
102                    &KernelNode {
103                        effect,
104                        kind: EffectKind::Transition,
105                        source_a: Some(*from),
106                        source_b: Some(*to),
107                        inputs: Vec::new(),
108                        params,
109                        resources,
110                        runtime: *runtime,
111                    },
112                )?),
113                RenderNode::Generator {
114                    effect,
115                    params,
116                    resources,
117                    runtime,
118                } => Arc::new(self.draw_kernel(
119                    graph,
120                    &outputs,
121                    &KernelNode {
122                        effect,
123                        kind: EffectKind::Generator,
124                        source_a: None,
125                        source_b: None,
126                        inputs: Vec::new(),
127                        params,
128                        resources,
129                        runtime: *runtime,
130                    },
131                )?),
132                RenderNode::Vector { scene } => Arc::new(super::vector::draw(
133                    &self.workers,
134                    &self.frame_pool,
135                    &self.coverage,
136                    scene,
137                    graph.size,
138                    blend_space,
139                )?),
140                RenderNode::Composite { layers, background } => {
141                    let inputs = layers
142                        .iter()
143                        .map(|layer| LayerInput {
144                            image: output(&outputs, layer.source),
145                            visual: layer.visual,
146                            blend_mode: layer.blend_mode,
147                        })
148                        .collect::<Vec<_>>();
149                    Arc::new(composite(
150                        &self.workers,
151                        &self.frame_pool,
152                        &inputs,
153                        CompositeSettings {
154                            size: graph.size,
155                            background: *background,
156                            blend_space,
157                            max_filter_samples: quality.max_filter_samples,
158                        },
159                    )?)
160                }
161            };
162            let stage = match &graph.nodes[node.index] {
163                RenderNode::Source(_) => None,
164                RenderNode::Effect { .. }
165                | RenderNode::Transition { .. }
166                | RenderNode::Generator { .. } => Some(&self.stats.kernel_micros),
167                RenderNode::Vector { .. } => Some(&self.stats.vector_micros),
168                RenderNode::Composite { .. } => Some(&self.stats.composite_micros),
169            };
170            if let Some(counter) = stage {
171                add_elapsed(counter, node_started);
172                drawn += 1;
173            }
174            if let Some((key, pinned)) = cached.store[node.index] {
175                inserts.push((key, Arc::clone(&image), pinned));
176            }
177            outputs[node.index] = Some(image);
178            high_water = high_water.max(
179                outputs
180                    .iter()
181                    .flatten()
182                    .map(|image| image.retained_bytes())
183                    .sum(),
184            );
185            release_inputs(graph, &plan.last_use, &mut outputs, node, position);
186        }
187        let image = outputs[plan.output.index]
188            .take()
189            .ok_or(GraphError::SourceOutput)?;
190        self.keep_results(cached.clears, &inserts);
191        self.stats.graphs.fetch_add(1, Ordering::Relaxed);
192        self.stats.nodes.fetch_add(drawn, Ordering::Relaxed);
193        add_elapsed(&self.stats.render_micros, started);
194        self.stats
195            .image_high_water_bytes
196            .fetch_max(high_water, Ordering::Relaxed);
197        Ok(image)
198    }
199
200    /// Draws `graph` and packs it as YUV420 with `encoding` directly into the caller's planes; the
201    /// CPU counterpart of [`crate::Renderer::render_graph_yuv420p`].
202    ///
203    /// # Errors
204    /// [`Self::execute_graph`]'s errors, and [`RenderError::TextureReadback`] for an odd size or a
205    /// target too small.
206    pub fn render_graph_into_yuv420p(
207        &self,
208        graph: &RenderGraph<'_>,
209        encoding: YuvEncoding,
210        targets: &mut Yuv420pTargets<'_>,
211    ) -> Result<(), RenderError> {
212        let image = self
213            .execute_graph(graph)
214            .map_err(GraphError::into_render_error)?;
215        let started = Instant::now();
216        super::pack::pack_yuv420p(&self.workers, &image, encoding, targets)?;
217        add_elapsed(&self.stats.render_micros, started);
218        add_elapsed(&self.stats.pack_micros, started);
219        Ok(())
220    }
221
222    fn draw_kernel(
223        &self,
224        graph: &RenderGraph<'_>,
225        outputs: &[Option<Arc<CpuImage>>],
226        node: &KernelNode<'_>,
227    ) -> Result<CpuImage, GraphError> {
228        let entry = self.entry(node.effect).ok_or(RenderError::UnknownEffect)?;
229        let definition = &entry.definition;
230        if definition.kind != node.kind {
231            return Err(GraphError::EffectKindMismatch);
232        }
233        crate::runtime_effect::validate_runtime(node.runtime)?;
234        crate::runtime_effect::encode_params(&definition.params, node.params)?;
235        if node
236            .resources
237            .iter()
238            .any(|(name, _)| !definition.resources.iter().any(|spec| spec.name == name))
239        {
240            return Err(RenderError::InvalidEffectParams.into());
241        }
242        let mut held: Vec<(&str, std::sync::Arc<CpuLut>)> =
243            Vec::with_capacity(definition.resources.len());
244        for spec in &definition.resources {
245            let id = node
246                .resources
247                .get(&spec.name)
248                .ok_or(RenderError::MissingEffectResource)?;
249            let lut = self
250                .resource(id)
251                .ok_or(RenderError::MissingEffectResource)?;
252            held.push((spec.name.as_str(), lut));
253        }
254        let resources: Vec<(&str, &CpuLut)> =
255            held.iter().map(|(name, lut)| (*name, &**lut)).collect();
256        if node
257            .inputs
258            .iter()
259            .any(|(name, _)| !definition.inputs.iter().any(|spec| spec.name == *name))
260        {
261            return Err(RenderError::InvalidEffectParams.into());
262        }
263        let mut inputs = Vec::with_capacity(definition.inputs.len());
264        for spec in &definition.inputs {
265            let (_, input) = node
266                .inputs
267                .iter()
268                .find(|(name, _)| *name == spec.name)
269                .ok_or(RenderError::MissingEffectInput)?;
270            inputs.push((spec.name.as_str(), output(outputs, *input)));
271        }
272        let transparent = CpuImage::transparent(graph.size);
273        let source_a = node.source_a.map_or(&transparent, |id| output(outputs, id));
274        let source_b = node.source_b.map_or(source_a, |id| output(outputs, id));
275        let context = KernelContext {
276            size: graph.size,
277            definition,
278            params: node.params,
279            runtime: node.runtime,
280            max_filter_samples: self.quality_controls().max_filter_samples,
281            source_a,
282            source_b,
283            texels: [source_a.texels(), source_b.texels()],
284            inputs: &inputs,
285            resources: &resources,
286        };
287        let kernel = entry.kernel;
288        // Kernel bounds are in input pixels, which match the output only at output size. A source
289        // presented at another size is sampled in uv and can reach every pixel.
290        let matching = [source_a, source_b]
291            .into_iter()
292            .chain(inputs.iter().map(|(_, image)| *image))
293            .all(|image| image.size() == graph.size);
294        let bounds = if matching {
295            kernel.bounds(&context)
296        } else {
297            PixelBox::whole(graph.size)
298        }
299        .intersect(PixelBox::whole(graph.size));
300        if bounds.is_empty() {
301            return Ok(CpuImage::transparent(graph.size));
302        }
303        let width = bounds.width as usize;
304        let mut pixels = self.frame_pool.take(bounds.pixels());
305        self.workers.bands_with(
306            &mut pixels,
307            width,
308            || vec![[0.0_f32; 4]; width],
309            |row, first_row, band| {
310                row.fill([0.0; 4]);
311                for (index, line) in band.chunks_mut(width).enumerate() {
312                    #[allow(clippy::cast_possible_truncation)]
313                    let y = bounds.y + (first_row + index) as u32;
314                    kernel.row(&context, y, bounds.x, row);
315                    for (out, value) in line.iter_mut().zip(row.iter()) {
316                        *out = half::store4(*value);
317                    }
318                }
319            },
320        );
321        Ok(CpuImage::pooled(
322            graph.size,
323            bounds,
324            pixels,
325            &self.frame_pool,
326        ))
327    }
328
329    /// Stores drawn results unless the cache was cleared since `clears` was read with the lookups;
330    /// mirrors `Renderer::complete_graph_work`.
331    pub(crate) fn keep_results(
332        &self,
333        clears: u64,
334        inserts: &[(RenderCacheKey, Arc<CpuImage>, bool)],
335    ) {
336        if inserts.is_empty() {
337            return;
338        }
339        let mut cache = self.lock_cache();
340        if cache.clears() == clears {
341            for (key, image, pinned) in inserts {
342                cache.insert(*key, image, *pinned);
343            }
344        }
345    }
346
347    /// Result-cache lookups, as the GPU executor's `cached_results`.
348    fn cached_results(
349        &self,
350        graph: &RenderGraph<'_>,
351        order: &[RenderNodeId],
352        output: RenderNodeId,
353        blend_space: f32,
354    ) -> CachedResults {
355        let count = graph.nodes.len();
356        let mut cached = CachedResults {
357            hits: vec![None; count],
358            store: vec![None; count],
359            needed: vec![true; count],
360            clears: 0,
361        };
362        if graph.intents.iter().all(Option::is_none) {
363            return cached;
364        }
365        let mut cache = self.lock_cache();
366        if !cache.enabled() {
367            return cached;
368        }
369        cached.clears = cache.clears();
370        let eligibility = graph.eligibility();
371        let (mut hits, mut misses, mut ineligible) = (0, 0, 0);
372        cached.needed = vec![false; count];
373        cached.needed[output.index] = true;
374        for node in order.iter().rev() {
375            if !cached.needed[node.index] {
376                continue;
377            }
378            if let Some(intent) = graph.intents[node.index] {
379                if eligibility[node.index] == CacheEligibility::Eligible {
380                    let key = renderer_node_key(graph.cache_keys[node.index], blend_space);
381                    let pinned = intent == CacheIntent::Pin;
382                    if let Some(image) = cache.get(key, pinned) {
383                        cached.hits[node.index] = Some(image);
384                        hits += 1;
385                        continue;
386                    }
387                    cached.store[node.index] = Some((key, pinned));
388                    misses += 1;
389                } else if intent != CacheIntent::Bypass {
390                    ineligible += 1;
391                }
392            }
393            for input in graph.nodes[node.index].dependencies() {
394                cached.needed[input.index] = true;
395            }
396        }
397        let skipped = order
398            .iter()
399            .filter(|node| {
400                !cached.needed[node.index]
401                    && cached.hits[node.index].is_none()
402                    && !matches!(graph.nodes[node.index], RenderNode::Source(_))
403            })
404            .count() as u64;
405        cache.record(hits, misses, ineligible, skipped);
406        cached
407    }
408}
409
410struct CachedResults {
411    hits: Vec<Option<Arc<CpuImage>>>,
412    store: Vec<Option<(RenderCacheKey, bool)>>,
413    needed: Vec<bool>,
414    /// The cache's clear count read with the lookups.
415    clears: u64,
416}
417
418fn output(outputs: &[Option<Arc<CpuImage>>], node: RenderNodeId) -> &CpuImage {
419    outputs[node.index]
420        .as_deref()
421        .expect("compiled dependency has an output")
422}
423
424/// Drops the results `node` was the last to read.
425fn release_inputs(
426    graph: &RenderGraph<'_>,
427    last_use: &[Option<usize>],
428    outputs: &mut [Option<Arc<CpuImage>>],
429    node: RenderNodeId,
430    position: usize,
431) {
432    for dependency in graph.nodes[node.index].dependencies() {
433        if last_use[dependency.index] == Some(position) {
434            outputs[dependency.index] = None;
435        }
436    }
437}