Skip to main content

alpha2_render/
runtime_effect.rs

1use std::sync::Arc;
2use std::sync::atomic::{AtomicBool, Ordering};
3
4use crate::{
5    EffectId, EffectKind, EffectParams, EffectResources, EffectRuntime, GraphError, ParamSpec,
6    ParamType, ParamValue, RenderError, RenderGraph, RenderSize, RenderedTexture, Renderer,
7    uniform::{
8        PARAM_SLOT_BYTES, RUNTIME_UNIFORM_WORDS, UniformArenaLease, f32_bytes, param_uniform_bytes,
9    },
10};
11
12impl Renderer {
13    /// Draws a registered generator at `size`.
14    ///
15    /// # Errors
16    /// [`RenderError`] for an unknown or non-generator effect or mismatched parameters;
17    /// [`RenderError::MissingEffectResource`] when it declares a resource (use
18    /// [`Renderer::render_generator_with_resources`]).
19    pub fn render_generator(
20        &self,
21        id: &EffectId,
22        size: RenderSize,
23        params: &EffectParams,
24        runtime: EffectRuntime,
25    ) -> Result<RenderedTexture, RenderError> {
26        self.render_generator_with_resources(id, size, params, &EffectResources::new(), runtime)
27    }
28
29    /// Draws a registered generator at `size` with named external resources.
30    ///
31    /// # Errors
32    /// [`RenderError`] for an unknown or non-generator effect, mismatched parameters, or a resource
33    /// not bound to a registered one of its kind.
34    pub fn render_generator_with_resources(
35        &self,
36        id: &EffectId,
37        size: RenderSize,
38        params: &EffectParams,
39        resources: &EffectResources,
40        runtime: EffectRuntime,
41    ) -> Result<RenderedTexture, RenderError> {
42        if self
43            .effect_definition(id)
44            .ok_or(RenderError::UnknownEffect)?
45            .kind
46            != EffectKind::Generator
47        {
48            return Err(RenderError::InvalidGraph);
49        }
50        let mut graph = RenderGraph::new(size);
51        let output = graph.add_generator_with_resources(
52            id.clone(),
53            params.clone(),
54            resources.clone(),
55            runtime,
56        );
57        graph
58            .set_output(output)
59            .map_err(GraphError::into_render_error)?;
60        self.execute_graph(&graph)
61            .map_err(GraphError::into_render_error)
62    }
63
64    /// Encodes a registered effect's pass, split into bands (each its own command buffer) when the
65    /// plan says it exceeds a submission's budget.
66    pub(crate) fn encode_effect_pass(
67        &self,
68        encoder: &mut crate::renderer::RenderEncoder,
69        pass: EffectPass<'_>,
70        uniforms: &mut UniformArenaLease,
71    ) -> Result<Option<PendingEffectTiming>, RenderError> {
72        let registered = self
73            .effects()
74            .get(pass.id)
75            .ok_or(RenderError::UnknownEffect)?;
76        self.encode_registered_pass(encoder, &registered, pass, uniforms)
77    }
78
79    #[allow(clippy::too_many_lines)]
80    pub(crate) fn encode_registered_pass(
81        &self,
82        encoder: &mut crate::renderer::RenderEncoder,
83        registered: &crate::registry::RegisteredEffect,
84        pass: EffectPass<'_>,
85        uniforms: &mut UniformArenaLease,
86    ) -> Result<Option<PendingEffectTiming>, RenderError> {
87        let EffectPass {
88            id: _,
89            kind,
90            source_a,
91            source_b,
92            inputs,
93            size,
94            params,
95            resources,
96            runtime,
97            output,
98        } = pass;
99        let drawn = self.effect_pipeline(registered)?;
100        let source_b = match (registered.definition.kind, source_b) {
101            (EffectKind::Transition, Some(source)) => source,
102            (EffectKind::Transition, None) => return Err(RenderError::MissingEffectInput),
103            (EffectKind::Effect | EffectKind::Generator, _) => source_a,
104        };
105        validate_runtime(runtime)?;
106        let parameter_bytes = encode_params(&registered.definition.params, params)?;
107        if resources.iter().any(|(name, _)| {
108            !registered
109                .definition
110                .resources
111                .iter()
112                .any(|spec| spec.name == name)
113        }) {
114            return Err(RenderError::InvalidEffectParams);
115        }
116        let parameter_uniform = uniforms.write(&parameter_bytes);
117        let runtime_uniform = uniforms.write(&runtime_bytes(
118            size,
119            runtime,
120            self.quality_controls().max_filter_samples,
121        ));
122        // Held until the bind group is made, whatever another thread registers meanwhile.
123        let bound = registered
124            .definition
125            .resources
126            .iter()
127            .map(|spec| {
128                let resource = resources
129                    .get(&spec.name)
130                    .and_then(|id| self.effect_resource(id))
131                    .ok_or(RenderError::MissingEffectResource)?;
132                if resource.kind == spec.kind {
133                    Ok(resource)
134                } else {
135                    Err(RenderError::EffectResourceKindMismatch)
136                }
137            })
138            .collect::<Result<Vec<_>, _>>()?;
139        let mut entries = vec![
140            wgpu::BindGroupEntry {
141                binding: 0,
142                resource: wgpu::BindingResource::TextureView(source_a),
143            },
144            wgpu::BindGroupEntry {
145                binding: 1,
146                resource: wgpu::BindingResource::TextureView(source_b),
147            },
148            wgpu::BindGroupEntry {
149                binding: 2,
150                resource: wgpu::BindingResource::Sampler(&drawn.sampler),
151            },
152            wgpu::BindGroupEntry {
153                binding: 3,
154                resource: uniforms.binding(parameter_uniform),
155            },
156            wgpu::BindGroupEntry {
157                binding: 4,
158                resource: uniforms.binding(runtime_uniform),
159            },
160        ];
161        for (index, resource) in bound.iter().enumerate() {
162            entries.push(wgpu::BindGroupEntry {
163                binding: u32::try_from(index).unwrap_or(0) * 2 + 5,
164                resource: wgpu::BindingResource::TextureView(&resource.view),
165            });
166            entries.push(wgpu::BindGroupEntry {
167                binding: u32::try_from(index).unwrap_or(0) * 2 + 6,
168                resource: resource.metadata.as_entire_binding(),
169            });
170        }
171        // An undeclared name is a bad setting; a declared but unbound one is a missing input.
172        if inputs.iter().any(|(name, _)| {
173            !registered
174                .definition
175                .inputs
176                .iter()
177                .any(|spec| spec.name == *name)
178        }) {
179            return Err(RenderError::InvalidEffectParams);
180        }
181        for (index, spec) in registered.definition.inputs.iter().enumerate() {
182            let (_, view) = inputs
183                .iter()
184                .find(|(name, _)| *name == spec.name)
185                .ok_or(RenderError::MissingEffectInput)?;
186            entries.push(wgpu::BindGroupEntry {
187                binding: crate::registry::input_binding(index),
188                resource: wgpu::BindingResource::TextureView(view),
189            });
190        }
191        let bind_group = self
192            .gpu
193            .device()
194            .create_bind_group(&wgpu::BindGroupDescriptor {
195                label: Some("alpha2 runtime effect bind group"),
196                layout: &drawn.bind_group_layout,
197                entries: &entries,
198            });
199        let bands = encoder.place_pass(
200            registered.cost,
201            u64::from(size.width) * u64::from(size.height),
202            true,
203        );
204        if bands > 1 {
205            // Bands read only the pass's sources, never its target, so pixels match an unbanded
206            // pass.
207            for band in 0..bands {
208                if band > 0 {
209                    encoder.next_band();
210                }
211                let (top, rows) = crate::submission_planner::band_rows(band, bands, size.height);
212                if rows > 0 {
213                    encode_pass(
214                        encoder,
215                        &drawn.pipeline,
216                        &bind_group,
217                        output,
218                        None,
219                        Some((band, top, size.width, rows)),
220                    );
221                }
222            }
223            return Ok(None);
224        }
225        // One reusable probe: a query set per pass exhausts Metal counter buffers, and the failed
226        // allocation silently drops the whole submission.
227        let timing = self.pass_timing_epoch();
228        if timing.is_some() {
229            // Advance a pending timestamp map first so one slow map cannot latch `busy` on polled
230            // backends.
231            let _ = self.gpu.device().poll(wgpu::PollType::Poll);
232        }
233        let probe = timing
234            .and_then(|epoch| Some((epoch, self.timestamp_probe()?)))
235            .filter(|(_, probe)| probe.acquire());
236        encode_pass(
237            encoder,
238            &drawn.pipeline,
239            &bind_group,
240            output,
241            probe.map(|(_, probe)| &probe.queries),
242            None,
243        );
244        if let Some((_, probe)) = probe {
245            encoder.resolve_query_set(&probe.queries, 0..2, &probe.resolve, 0);
246            encoder.copy_buffer_to_buffer(&probe.resolve, 0, &probe.readback, 0, 16);
247        }
248        Ok(probe.map(|(epoch, probe)| PendingEffectTiming {
249            epoch,
250            label: kind.pass_label(),
251            readback: probe.readback.clone(),
252            busy: Arc::clone(&probe.busy),
253            diagnostics: self.diagnostics.clone(),
254            timestamp_period: self.gpu.queue().get_timestamp_period(),
255            gpu: self.gpu.clone(),
256            armed: true,
257        }))
258    }
259}
260
261pub(crate) struct PendingEffectTiming {
262    epoch: u64,
263    label: &'static str,
264    readback: wgpu::Buffer,
265    busy: Arc<AtomicBool>,
266    diagnostics: crate::diagnostics::SharedDiagnostics,
267    timestamp_period: f32,
268    gpu: alpha2_gpu::GpuContext,
269    armed: bool,
270}
271
272impl PendingEffectTiming {
273    pub(crate) fn map_after_submit(mut self) {
274        let mapped = self.readback.clone();
275        let busy = Arc::clone(&self.busy);
276        let diagnostics = self.diagnostics.clone();
277        let timestamp_period = self.timestamp_period;
278        let epoch = self.epoch;
279        let label = self.label;
280        self.gpu.map_async(
281            &self.readback.slice(..),
282            wgpu::MapMode::Read,
283            move |result| {
284                if result.is_ok() {
285                    if let Ok(bytes) = mapped.slice(..).get_mapped_range() {
286                        if bytes.len() >= 16 {
287                            let start =
288                                u64::from_ne_bytes(bytes[0..8].try_into().unwrap_or([0; 8]));
289                            let end = u64::from_ne_bytes(bytes[8..16].try_into().unwrap_or([0; 8]));
290                            let elapsed = end.saturating_sub(start);
291                            #[allow(
292                                clippy::cast_possible_truncation,
293                                clippy::cast_precision_loss,
294                                clippy::cast_sign_loss
295                            )]
296                            let nanoseconds = (elapsed as f64 * f64::from(timestamp_period)) as u64;
297                            crate::diagnostics::record_pass(
298                                &diagnostics,
299                                epoch,
300                                label,
301                                std::time::Duration::from_nanos(nanoseconds),
302                                crate::TimingSource::GpuTimestamp,
303                            );
304                        }
305                        drop(bytes);
306                    }
307                    mapped.unmap();
308                }
309                busy.store(false, Ordering::Release);
310            },
311        );
312        self.armed = false;
313        let _ = self.gpu.device().poll(wgpu::PollType::Poll);
314    }
315}
316
317impl Drop for PendingEffectTiming {
318    fn drop(&mut self) {
319        if self.armed {
320            self.busy.store(false, Ordering::Release);
321        }
322    }
323}
324
325#[derive(Copy, Clone)]
326pub(crate) struct EffectPass<'a> {
327    pub(crate) id: &'a EffectId,
328    /// The node kind, which names the pass's timing.
329    pub(crate) kind: crate::RenderNodeKind,
330    pub(crate) source_a: &'a wgpu::TextureView,
331    pub(crate) source_b: Option<&'a wgpu::TextureView>,
332    pub(crate) inputs: &'a [(&'a str, &'a wgpu::TextureView)],
333    pub(crate) size: RenderSize,
334    pub(crate) params: &'a EffectParams<'a>,
335    pub(crate) resources: &'a EffectResources,
336    pub(crate) runtime: EffectRuntime,
337    pub(crate) output: &'a wgpu::TextureView,
338}
339
340pub(crate) fn encode_params(
341    schema: &[ParamSpec],
342    supplied: &EffectParams,
343) -> Result<Vec<u8>, RenderError> {
344    if supplied
345        .names()
346        .any(|name| !schema.iter().any(|param| param.name == name))
347    {
348        return Err(RenderError::InvalidEffectParams);
349    }
350    let mut bytes = vec![0; param_uniform_bytes(schema.len())];
351    for (spec, slot) in schema
352        .iter()
353        .zip(bytes.as_chunks_mut::<PARAM_SLOT_BYTES>().0)
354    {
355        let value = supplied.get(&spec.name).unwrap_or(&spec.default);
356        encode_value(spec, value, slot)?;
357    }
358    Ok(bytes)
359}
360
361fn encode_value(
362    spec: &ParamSpec,
363    value: &ParamValue,
364    output: &mut [u8],
365) -> Result<(), RenderError> {
366    match (spec.param_type, value) {
367        (ParamType::Float, ParamValue::Float(value)) if valid_scalar(spec, *value) => {
368            output[..4].copy_from_slice(&value.to_ne_bytes());
369        }
370        (ParamType::Vec2, ParamValue::Vec2(values))
371            if values.iter().all(|value| valid_scalar(spec, *value)) =>
372        {
373            output[..4].copy_from_slice(&values[0].to_ne_bytes());
374            output[4..8].copy_from_slice(&values[1].to_ne_bytes());
375        }
376        (ParamType::Vec4, ParamValue::Vec4(values))
377            if values.iter().all(|value| valid_scalar(spec, *value)) =>
378        {
379            output.copy_from_slice(&f32_bytes(*values));
380        }
381        (ParamType::Color, ParamValue::Color(values))
382            if values
383                .iter()
384                .all(|value| value.is_finite() && (0.0..=1.0).contains(value)) =>
385        {
386            output.copy_from_slice(&f32_bytes(*values));
387        }
388        (ParamType::Enum, ParamValue::Enum(value))
389            if usize::try_from(*value).is_ok_and(|index| index < spec.enum_values.len()) =>
390        {
391            output[..4].copy_from_slice(&value.to_ne_bytes());
392        }
393        (ParamType::Bool, ParamValue::Bool(value)) => {
394            output[..4].copy_from_slice(&u32::from(*value).to_ne_bytes());
395        }
396        _ => return Err(RenderError::InvalidEffectParams),
397    }
398    Ok(())
399}
400
401fn valid_scalar(spec: &ParamSpec, value: f32) -> bool {
402    value.is_finite()
403        && spec.min.is_none_or(|minimum| value >= minimum)
404        && spec.max.is_none_or(|maximum| value <= maximum)
405}
406
407pub(crate) fn validate_runtime(runtime: EffectRuntime) -> Result<(), RenderError> {
408    if !runtime.progress.is_finite()
409        || !(0.0..=1.0).contains(&runtime.progress)
410        || !runtime.ratio.is_finite()
411        || runtime.ratio <= 0.0
412        || !runtime.scale.is_finite()
413        || runtime.scale <= 0.0
414    {
415        return Err(RenderError::InvalidEffectParameter);
416    }
417    Ok(())
418}
419
420/// Runtime uniform: resolution, `time()` seconds, `render_scale()`, progress, ratio and filter
421/// budget as floats, then the tick count as two words, low first (`time_ticks()`), and the render
422/// scale in 16.16 fixed point (`render_scale_fixed()`).
423#[allow(clippy::cast_precision_loss)]
424fn runtime_bytes(size: RenderSize, runtime: EffectRuntime, max_filter_samples: u32) -> Vec<u8> {
425    let ticks = runtime.time.ticks().cast_unsigned();
426    // Rounded once from the exact quotient.
427    #[allow(clippy::cast_possible_truncation)]
428    let seconds = (runtime.time.ticks() as f64 / alpha2_time::TICKS_PER_SECOND as f64) as f32;
429    let values: [f32; 8] = [
430        size.width as f32,
431        size.height as f32,
432        seconds,
433        runtime.scale,
434        runtime.progress,
435        runtime.ratio,
436        max_filter_samples as f32,
437        0.0,
438    ];
439    #[allow(clippy::cast_possible_truncation)]
440    let words: [u32; RUNTIME_UNIFORM_WORDS - 8] = [
441        ticks as u32,
442        (ticks >> 32) as u32,
443        render_scale_fixed(runtime.scale),
444        0,
445    ];
446    let mut bytes = f32_bytes(values);
447    bytes.extend(words.iter().flat_map(|word| word.to_ne_bytes()));
448    bytes
449}
450
451/// `scale` in 16.16 fixed point, as `render_scale_fixed()` gives it.
452#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
453pub(crate) fn render_scale_fixed(scale: f32) -> u32 {
454    (f64::from(scale) * 65_536.0).round() as u32
455}
456
457/// Encodes one full-target draw, or with `band` (index, top row, width, rows) one band; the
458/// first band clears the target, later ones load it.
459fn encode_pass(
460    encoder: &mut wgpu::CommandEncoder,
461    pipeline: &wgpu::RenderPipeline,
462    bind_group: &wgpu::BindGroup,
463    output: &wgpu::TextureView,
464    timestamp_queries: Option<&wgpu::QuerySet>,
465    band: Option<(u32, u32, u32, u32)>,
466) {
467    let load = match band {
468        Some((index, ..)) if index > 0 => wgpu::LoadOp::Load,
469        _ => wgpu::LoadOp::Clear(wgpu::Color::TRANSPARENT),
470    };
471    let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
472        label: Some("alpha2 runtime effect pass"),
473        color_attachments: &[Some(wgpu::RenderPassColorAttachment {
474            view: output,
475            depth_slice: None,
476            resolve_target: None,
477            ops: wgpu::Operations {
478                load,
479                store: wgpu::StoreOp::Store,
480            },
481        })],
482        depth_stencil_attachment: None,
483        timestamp_writes: timestamp_queries.map(|query_set| wgpu::RenderPassTimestampWrites {
484            query_set,
485            beginning_of_pass_write_index: Some(0),
486            end_of_pass_write_index: Some(1),
487        }),
488        occlusion_query_set: None,
489        multiview_mask: None,
490    });
491    pass.set_pipeline(pipeline);
492    pass.set_bind_group(0, bind_group, &[]);
493    if let Some((_, top, width, rows)) = band {
494        pass.set_scissor_rect(0, top, width, rows);
495    }
496    pass.draw(0..3, 0..1);
497}
498
499/// Reusable GPU timestamp instrumentation for effect passes, one per renderer.
500///
501/// While one measurement is in flight, later passes fall back to CPU timing instead of
502/// allocating more driver resources.
503#[derive(Debug)]
504pub(crate) struct TimestampProbe {
505    pub(crate) queries: wgpu::QuerySet,
506    pub(crate) resolve: wgpu::Buffer,
507    pub(crate) readback: wgpu::Buffer,
508    pub(crate) busy: Arc<AtomicBool>,
509}
510
511impl TimestampProbe {
512    /// Takes the probe for one pass; `false` while a read is pending.
513    pub(crate) fn acquire(&self) -> bool {
514        self.busy
515            .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
516            .is_ok()
517    }
518}
519
520impl Renderer {
521    fn timestamp_probe(&self) -> Option<&TimestampProbe> {
522        self.timestamp_probe
523            .get_or_init(|| {
524                if !self.gpu.capabilities().timestamp_queries {
525                    return None;
526                }
527                let queries = self
528                    .gpu
529                    .device()
530                    .create_query_set(&wgpu::QuerySetDescriptor {
531                        label: Some("alpha2 effect timestamps"),
532                        ty: wgpu::QueryType::Timestamp,
533                        count: 2,
534                    });
535                let resolve = self.gpu.device().create_buffer(&wgpu::BufferDescriptor {
536                    label: Some("alpha2 effect timestamp resolve"),
537                    size: 16,
538                    usage: wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC,
539                    mapped_at_creation: false,
540                });
541                let readback = self.gpu.device().create_buffer(&wgpu::BufferDescriptor {
542                    label: Some("alpha2 effect timestamp readback"),
543                    size: 16,
544                    usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
545                    mapped_at_creation: false,
546                });
547                Some(TimestampProbe {
548                    queries,
549                    resolve,
550                    readback,
551                    busy: Arc::new(AtomicBool::new(false)),
552                })
553            })
554            .as_ref()
555    }
556}