Skip to main content

alpha2_render/
graph_execute.rs

1use std::collections::HashSet;
2use web_time::Instant;
3
4use crate::composite::CompositeTarget;
5use crate::graph::{GraphError, RenderCacheKey, RenderGraph, RenderNode, RenderNodeId};
6use crate::graph_cache::{renderer_cache_key, renderer_node_key};
7use crate::runtime_effect::{EffectPass, PendingEffectTiming};
8use crate::uniform::{
9    BATCH_UNIFORM_FLOATS, RUNTIME_UNIFORM_WORDS, UniformArenaLease, aligned_uniform_end,
10    float_uniform_bytes, param_uniform_bytes,
11};
12use crate::{
13    CompositeLayer, EffectId, EffectKind, RenderedTexture, Renderer, ShaderDiagnostics,
14    WarmupReport,
15};
16
17pub(crate) struct EncodedGraph {
18    texture: RenderedTexture,
19    /// Results to keep after the submission is accepted; keeping them earlier could leave
20    /// unwritten textures after a failure.
21    cache_inserts: Vec<(RenderCacheKey, RenderedTexture, bool)>,
22    /// The result cache's clear count at lookup; a later clear drops `cache_inserts`.
23    cache_clears: u64,
24    uniforms: UniformArenaLease,
25    pending_timings: Vec<PendingEffectTiming>,
26    encoded_nodes: u64,
27    encoded_render_passes: u64,
28}
29
30impl EncodedGraph {
31    pub(crate) fn texture(&self) -> &RenderedTexture {
32        &self.texture
33    }
34
35    pub(crate) fn flush_uniforms(&self, queue: &wgpu::Queue) {
36        self.uniforms.flush(queue);
37    }
38}
39
40impl Renderer {
41    /// A deterministic key for the graph and the settings that affect its pixels (blend space,
42    /// applied quality controls, intermediate format). Adapters that store pictures alike give
43    /// equal keys.
44    ///
45    /// # Errors
46    /// Returns [`GraphError::MissingOutput`] when no output was selected.
47    pub fn graph_cache_key(&self, graph: &RenderGraph<'_>) -> Result<RenderCacheKey, GraphError> {
48        let quality = self.quality_controls();
49        let plan = graph.compile_with_quality(quality)?;
50        Ok(renderer_cache_key(
51            plan.cache_key,
52            graph.blend_space.unwrap_or(self.blend_space).shader_value(),
53            quality,
54            self.intermediate_format(),
55        ))
56    }
57
58    /// Initializes all pipelines referenced by one graph.
59    ///
60    /// # Errors
61    /// Returns graph validation errors, or diagnostics for an unknown effect or a failed pipeline.
62    pub fn warmup_graph(&self, graph: &RenderGraph<'_>) -> Result<WarmupReport, ShaderDiagnostics> {
63        self.warmup_graphs(&[graph])
64    }
65
66    /// Initializes the deduplicated pipeline set referenced by project graphs.
67    ///
68    /// # Errors
69    /// Returns diagnostics for a malformed graph, an unknown effect or a failed pipeline.
70    pub fn warmup_graphs(
71        &self,
72        graphs: &[&RenderGraph<'_>],
73    ) -> Result<WarmupReport, ShaderDiagnostics> {
74        let mut effects = Vec::<EffectId>::new();
75        let mut seen = HashSet::<EffectId>::new();
76        let mut needs_composite = false;
77        let mut composite_layers = Vec::<usize>::new();
78        let mut vector_spaces = Vec::<crate::BlendSpace>::new();
79        for graph in graphs {
80            let plan = graph
81                .compile()
82                .map_err(|error| ShaderDiagnostics::error(error.to_string()))?;
83            for node in plan.order {
84                match &graph.nodes[node.index] {
85                    RenderNode::Effect { effect, .. }
86                    | RenderNode::Transition { effect, .. }
87                    | RenderNode::Generator { effect, .. } => {
88                        if seen.insert(effect.clone()) {
89                            effects.push(effect.clone());
90                        }
91                    }
92                    RenderNode::Composite { layers, .. } => {
93                        needs_composite = true;
94                        composite_layers.push(layers.len());
95                    }
96                    RenderNode::Vector { .. } => {
97                        let space = graph.blend_space.unwrap_or(self.blend_space);
98                        if !vector_spaces.contains(&space) {
99                            vector_spaces.push(space);
100                        }
101                    }
102                    RenderNode::Source(_) => {}
103                }
104            }
105        }
106        self.warmup(&effects)?;
107        let failed = |error: crate::RenderError| ShaderDiagnostics::error(error.to_string());
108        for layers in composite_layers {
109            self.warm_composite(layers).map_err(failed)?;
110        }
111        for space in &vector_spaces {
112            self.warm_vector(*space).map_err(failed)?;
113        }
114        Ok(WarmupReport {
115            runtime_effects: effects.len(),
116            builtins: usize::from(needs_composite) + usize::from(!vector_spaces.is_empty()),
117        })
118    }
119
120    /// Executes the reachable portion of a graph and returns its owned output.
121    ///
122    /// # Errors
123    /// Returns a structural error or the first rendering failure.
124    #[allow(clippy::too_many_lines)]
125    pub fn execute_graph(&self, graph: &RenderGraph<'_>) -> Result<RenderedTexture, GraphError> {
126        let mut command_encoder = self.command_encoder("alpha2 render graph encoder");
127        let graph_work = self.encode_graph(graph, &mut command_encoder)?;
128        graph_work.flush_uniforms(self.gpu.queue());
129        self.submit([command_encoder.finish()])
130            .map_err(GraphError::Render)?;
131        Ok(self.complete_graph_work(graph_work, true))
132    }
133
134    #[allow(clippy::too_many_lines)]
135    pub(crate) fn encode_graph(
136        &self,
137        graph: &RenderGraph<'_>,
138        encoder: &mut crate::renderer::RenderEncoder,
139    ) -> Result<EncodedGraph, GraphError> {
140        self.validate_size(graph.size)?;
141        let plan = graph.compile()?;
142        if matches!(graph.nodes[plan.output.index], RenderNode::Source(_)) {
143            return Err(GraphError::SourceOutput);
144        }
145        let format = self.intermediate_format();
146        let uniform_alignment = u64::from(self.limits.min_uniform_buffer_offset_alignment.max(1));
147        let uniform_capacity = graph_uniform_capacity(self, graph, &plan.order, uniform_alignment);
148        let mut uniforms = self
149            .uniform_buffers
150            .acquire(self.gpu.device(), uniform_capacity);
151        let mut outputs: Vec<Option<RenderedTexture>> =
152            (0..graph.nodes.len()).map(|_| None).collect();
153        let blend_space = graph.blend_space.unwrap_or(self.blend_space).shader_value();
154        let cached = self.cached_results(graph, &plan.order, plan.output, blend_space);
155        let pixels = u64::from(graph.size.width) * u64::from(graph.size.height);
156        let predicted = plan
157            .order
158            .iter()
159            .filter(|node| cached.hits[node.index].is_none() && cached.needed[node.index])
160            .fold(crate::FrameCost::default(), |mut total, node| {
161                if let Some(cost) = self.node_cost(&graph.nodes[node.index]) {
162                    total.add(cost, pixels);
163                }
164                total
165            });
166        self.plan_submissions(encoder, predicted);
167        let mut pending_timings = Vec::<PendingEffectTiming>::new();
168        let mut encoded_nodes = 0_u64;
169        let mut encoded_render_passes = 0_u64;
170        let mut cache_inserts = Vec::new();
171        let timing = self.pass_timing_epoch();
172        for (position, node_id) in plan.order.iter().copied().enumerate() {
173            let started = timing.map(|epoch| (epoch, Instant::now()));
174            if let Some(hit) = cached.hits[node_id.index].clone() {
175                outputs[node_id.index] = Some(hit);
176                release_inputs(graph, &plan.last_use, &mut outputs, node_id, position);
177                continue;
178            }
179            if !cached.needed[node_id.index] {
180                // A cache hit still releases its inputs where drawing would have.
181                release_inputs(graph, &plan.last_use, &mut outputs, node_id, position);
182                continue;
183            }
184            // Recorded for the report of a loss this submission causes.
185            if let RenderNode::Effect { effect, .. }
186            | RenderNode::Transition { effect, .. }
187            | RenderNode::Generator { effect, .. } = &graph.nodes[node_id.index]
188            {
189                self.submission_clock.note_effect(effect);
190            }
191            let output = match &graph.nodes[node_id.index] {
192                RenderNode::Source(_) => None,
193                RenderNode::Effect {
194                    effect,
195                    source,
196                    inputs,
197                    params,
198                    resources,
199                    runtime,
200                } => {
201                    if self
202                        .effect_definition(effect)
203                        .is_some_and(|definition| definition.kind != EffectKind::Effect)
204                    {
205                        return Err(GraphError::EffectKindMismatch);
206                    }
207                    let source_view = graph_view(graph, &outputs, *source)?;
208                    let input_views: Vec<(&str, &wgpu::TextureView)> = inputs
209                        .iter()
210                        .map(|(name, node)| Ok((name, graph_view(graph, &outputs, node)?)))
211                        .collect::<Result<_, GraphError>>()?;
212                    let target = self.textures.acquire(
213                        self.gpu.device(),
214                        graph.size,
215                        format,
216                        "alpha2 graph effect target",
217                    );
218                    if let Some(pending) = self.encode_effect_pass(
219                        encoder,
220                        EffectPass {
221                            id: effect,
222                            kind: crate::RenderNodeKind::Effect,
223                            source_a: source_view,
224                            source_b: None,
225                            inputs: &input_views,
226                            size: graph.size,
227                            params,
228                            resources,
229                            runtime: *runtime,
230                            output: target.view(),
231                        },
232                        &mut uniforms,
233                    )? {
234                        pending_timings.push(pending);
235                    }
236                    encoded_render_passes = encoded_render_passes.saturating_add(1);
237                    Some(RenderedTexture::pooled(graph.size, format, target))
238                }
239                RenderNode::Transition {
240                    effect,
241                    from,
242                    to,
243                    params,
244                    resources,
245                    runtime,
246                } => {
247                    if self
248                        .effect_definition(effect)
249                        .is_some_and(|definition| definition.kind != EffectKind::Transition)
250                    {
251                        return Err(GraphError::EffectKindMismatch);
252                    }
253                    let from_view = graph_view(graph, &outputs, *from)?;
254                    let to_view = graph_view(graph, &outputs, *to)?;
255                    let target = self.textures.acquire(
256                        self.gpu.device(),
257                        graph.size,
258                        format,
259                        "alpha2 graph transition target",
260                    );
261                    if let Some(pending) = self.encode_effect_pass(
262                        encoder,
263                        EffectPass {
264                            id: effect,
265                            kind: crate::RenderNodeKind::Transition,
266                            source_a: from_view,
267                            source_b: Some(to_view),
268                            inputs: &[],
269                            size: graph.size,
270                            params,
271                            resources,
272                            runtime: *runtime,
273                            output: target.view(),
274                        },
275                        &mut uniforms,
276                    )? {
277                        pending_timings.push(pending);
278                    }
279                    encoded_render_passes = encoded_render_passes.saturating_add(1);
280                    Some(RenderedTexture::pooled(graph.size, format, target))
281                }
282                RenderNode::Generator {
283                    effect,
284                    params,
285                    resources,
286                    runtime,
287                } => {
288                    if self
289                        .effect_definition(effect)
290                        .is_some_and(|definition| definition.kind != EffectKind::Generator)
291                    {
292                        return Err(GraphError::EffectKindMismatch);
293                    }
294                    let target = self.textures.acquire(
295                        self.gpu.device(),
296                        graph.size,
297                        format,
298                        "alpha2 graph generator target",
299                    );
300                    // A generator samples nothing, but its bindings still need a texture.
301                    if let Some(pending) = self.encode_effect_pass(
302                        encoder,
303                        EffectPass {
304                            id: effect,
305                            kind: crate::RenderNodeKind::Generator,
306                            source_a: &self.empty_input,
307                            source_b: None,
308                            inputs: &[],
309                            size: graph.size,
310                            params,
311                            resources,
312                            runtime: *runtime,
313                            output: target.view(),
314                        },
315                        &mut uniforms,
316                    )? {
317                        pending_timings.push(pending);
318                    }
319                    encoded_render_passes = encoded_render_passes.saturating_add(1);
320                    Some(RenderedTexture::pooled(graph.size, format, target))
321                }
322                RenderNode::Vector { scene } => {
323                    encoder.place_pass(crate::submission_planner::VECTOR_COST, pixels, false);
324                    let target = self.textures.acquire(
325                        self.gpu.device(),
326                        graph.size,
327                        format,
328                        "alpha2 graph vector target",
329                    );
330                    encoded_render_passes =
331                        encoded_render_passes.saturating_add(self.encode_vector(
332                            encoder,
333                            scene,
334                            graph.size,
335                            graph.blend_space.unwrap_or(self.blend_space),
336                            target.view(),
337                            &mut uniforms,
338                        )?);
339                    Some(RenderedTexture::pooled(graph.size, format, target))
340                }
341                RenderNode::Composite { layers, background } => {
342                    encoder.place_pass(
343                        crate::submission_planner::COMPOSITE_LAYER_COST
344                            .times(u64::try_from(layers.len()).unwrap_or(u64::MAX)),
345                        pixels,
346                        false,
347                    );
348                    let views = layers
349                        .iter()
350                        .map(|layer| graph_view(graph, &outputs, layer.source))
351                        .collect::<Result<Vec<_>, _>>()?;
352                    let composite_layers = layers
353                        .iter()
354                        .zip(&views)
355                        .map(|(layer, view)| CompositeLayer {
356                            texture: view,
357                            visual: layer.visual,
358                            blend_mode: layer.blend_mode,
359                        })
360                        .collect::<Vec<_>>();
361                    let target = self.textures.acquire(
362                        self.gpu.device(),
363                        graph.size,
364                        format,
365                        "alpha2 graph composite target",
366                    );
367                    encoded_render_passes =
368                        encoded_render_passes.saturating_add(self.encode_layers_pass(
369                            encoder,
370                            graph.size,
371                            &composite_layers,
372                            CompositeTarget {
373                                background: *background,
374                                blend_space: graph.blend_space.unwrap_or(self.blend_space),
375                                output: target.texture(),
376                                output_view: target.view(),
377                            },
378                            &mut uniforms,
379                        )?);
380                    Some(RenderedTexture::pooled(graph.size, format, target))
381                }
382            };
383            if let Some((epoch, started)) = started
384                && !matches!(graph.nodes[node_id.index], RenderNode::Source(_))
385            {
386                let label = graph.nodes[node_id.index].kind().pass_label();
387                crate::diagnostics::record_pass(
388                    &self.diagnostics,
389                    epoch,
390                    label,
391                    started.elapsed(),
392                    crate::TimingSource::CpuEncoding,
393                );
394            }
395            if let (Some(output), Some((key, pinned))) = (&output, cached.store[node_id.index]) {
396                cache_inserts.push((key, output.clone(), pinned));
397            }
398            outputs[node_id.index] = output;
399            if !matches!(graph.nodes[node_id.index], RenderNode::Source(_)) {
400                encoded_nodes = encoded_nodes.saturating_add(1);
401            }
402            release_inputs(graph, &plan.last_use, &mut outputs, node_id, position);
403        }
404
405        let texture = outputs[plan.output.index]
406            .take()
407            .ok_or(GraphError::SourceOutput)?;
408        Ok(EncodedGraph {
409            texture,
410            cache_inserts,
411            cache_clears: cached.clears,
412            uniforms,
413            pending_timings,
414            encoded_nodes,
415            encoded_render_passes,
416        })
417    }
418
419    /// Predicted per-pixel cost of drawing `node`; `None` for sources.
420    fn node_cost(&self, node: &RenderNode<'_>) -> Option<crate::effect_cost::EffectCost> {
421        match node {
422            RenderNode::Effect { effect, .. }
423            | RenderNode::Transition { effect, .. }
424            | RenderNode::Generator { effect, .. } => {
425                self.effects().get(effect).map(|registered| registered.cost)
426            }
427            RenderNode::Composite { layers, .. } => Some(
428                crate::submission_planner::COMPOSITE_LAYER_COST
429                    .times(u64::try_from(layers.len()).unwrap_or(u64::MAX)),
430            ),
431            RenderNode::Vector { .. } => Some(crate::submission_planner::VECTOR_COST),
432            RenderNode::Source(_) => None,
433        }
434    }
435
436    pub(crate) fn complete_graph_work(
437        &self,
438        encoded: EncodedGraph,
439        standalone_submission: bool,
440    ) -> RenderedTexture {
441        let EncodedGraph {
442            texture,
443            cache_inserts,
444            cache_clears,
445            uniforms,
446            pending_timings,
447            encoded_nodes,
448            encoded_render_passes,
449        } = encoded;
450        uniforms.recycle();
451        if !cache_inserts.is_empty() {
452            let mut cache = self.lock_result_cache();
453            // A clear since the lookup may have changed what these results should show.
454            if cache.clears() == cache_clears {
455                for (key, result, pinned) in &cache_inserts {
456                    cache.insert(*key, result, *pinned);
457                }
458            }
459        }
460        crate::diagnostics::record_graph_work(
461            &self.diagnostics,
462            encoded_nodes,
463            encoded_render_passes,
464            standalone_submission,
465        );
466        for timing in pending_timings {
467            timing.map_after_submit();
468        }
469        texture
470    }
471}
472
473fn graph_uniform_capacity(
474    renderer: &Renderer,
475    graph: &RenderGraph<'_>,
476    order: &[RenderNodeId],
477    alignment: u64,
478) -> u64 {
479    let mut capacity = 0_u64;
480    for node in order {
481        match &graph.nodes[node.index] {
482            RenderNode::Effect { effect, .. }
483            | RenderNode::Transition { effect, .. }
484            | RenderNode::Generator { effect, .. } => {
485                let parameter_bytes = renderer
486                    .effects()
487                    .get(effect)
488                    .map_or(0, |registered| registered.definition.params.len());
489                let parameter_bytes =
490                    u64::try_from(param_uniform_bytes(parameter_bytes)).unwrap_or(u64::MAX);
491                capacity = aligned_uniform_end(capacity, parameter_bytes, alignment);
492                capacity = aligned_uniform_end(
493                    capacity,
494                    float_uniform_bytes(RUNTIME_UNIFORM_WORDS),
495                    alignment,
496                );
497            }
498            RenderNode::Composite { layers, .. } => {
499                let passes = renderer
500                    .composite_batch_count(layers.iter().map(|layer| layer.visual), graph.size);
501                for _ in 0..passes {
502                    capacity = aligned_uniform_end(
503                        capacity,
504                        float_uniform_bytes(BATCH_UNIFORM_FLOATS),
505                        alignment,
506                    );
507                }
508            }
509            RenderNode::Vector { scene } => {
510                let slices = scene
511                    .ops
512                    .iter()
513                    .filter(|op| !matches!(op, alpha2_geometry::VectorOp::PushLayer { .. }))
514                    .count()
515                    + 1;
516                for _ in 0..slices {
517                    capacity = aligned_uniform_end(
518                        capacity,
519                        crate::vector::VECTOR_UNIFORM_BYTES,
520                        alignment,
521                    );
522                }
523            }
524            RenderNode::Source(_) => {}
525        }
526    }
527    capacity
528}
529
530/// The texture a dependency is drawn from; `None` for a CPU source.
531fn graph_view<'a>(
532    graph: &'a RenderGraph<'_>,
533    outputs: &'a [Option<RenderedTexture>],
534    node: RenderNodeId,
535) -> Result<&'a wgpu::TextureView, GraphError> {
536    match &graph.nodes[node.index] {
537        RenderNode::Source(view) => view
538            .wgpu_view()
539            .ok_or(GraphError::Render(crate::RenderError::InvalidSource)),
540        _ => Ok(outputs[node.index]
541            .as_ref()
542            .expect("compiled dependency has an output")
543            .view()),
544    }
545}
546
547/// Returns to the pool the results `node` was the last to read.
548fn release_inputs(
549    graph: &RenderGraph<'_>,
550    last_use: &[Option<usize>],
551    outputs: &mut [Option<RenderedTexture>],
552    node: RenderNodeId,
553    position: usize,
554) {
555    for dependency in graph.nodes[node.index].dependencies() {
556        if last_use[dependency.index] == Some(position) {
557            outputs[dependency.index] = None;
558        }
559    }
560}
561
562/// Cache hits, results to keep, and nodes still to draw for one graph.
563struct CachedResults {
564    hits: Vec<Option<RenderedTexture>>,
565    store: Vec<Option<(RenderCacheKey, bool)>>,
566    needed: Vec<bool>,
567    /// The cache's clear count read with the lookups.
568    clears: u64,
569}
570
571impl Renderer {
572    /// Looks up cache candidates and marks which nodes hits make unnecessary. With the cache off or
573    /// no candidates, everything is drawn and nothing kept.
574    fn cached_results(
575        &self,
576        graph: &RenderGraph<'_>,
577        order: &[RenderNodeId],
578        output: RenderNodeId,
579        blend_space: f32,
580    ) -> CachedResults {
581        let count = graph.nodes.len();
582        let mut cached = CachedResults {
583            hits: vec![None; count],
584            store: vec![None; count],
585            needed: vec![true; count],
586            clears: 0,
587        };
588        if graph.intents.iter().all(Option::is_none) {
589            return cached;
590        }
591        let mut cache = self.lock_result_cache();
592        if !cache.enabled() {
593            return cached;
594        }
595        cached.clears = cache.clears();
596        let eligibility = graph.eligibility();
597        let (mut hits, mut misses, mut ineligible) = (0, 0, 0);
598        // From the output down: look a node up only if still needed; a hit's inputs are then needed
599        // only by others.
600        cached.needed = vec![false; count];
601        cached.needed[output.index] = true;
602        for node in order.iter().rev() {
603            if !cached.needed[node.index] {
604                continue;
605            }
606            if let Some(intent) = graph.intents[node.index] {
607                if eligibility[node.index] == crate::CacheEligibility::Eligible {
608                    let key = renderer_node_key(graph.cache_keys[node.index], blend_space);
609                    let pinned = intent == crate::CacheIntent::Pin;
610                    if let Some(texture) = cache.get(key, pinned) {
611                        cached.hits[node.index] = Some(texture);
612                        hits += 1;
613                        continue;
614                    }
615                    cached.store[node.index] = Some((key, pinned));
616                    misses += 1;
617                } else if intent != crate::CacheIntent::Bypass {
618                    ineligible += 1;
619                }
620            }
621            for input in graph.nodes[node.index].dependencies() {
622                cached.needed[input.index] = true;
623            }
624        }
625        let skipped = order
626            .iter()
627            .filter(|node| {
628                !cached.needed[node.index]
629                    && cached.hits[node.index].is_none()
630                    && !matches!(graph.nodes[node.index], RenderNode::Source(_))
631            })
632            .count() as u64;
633        cache.record(hits, misses, ineligible, skipped);
634        cached
635    }
636}