Skip to main content

alpha2_render/
renderer.rs

1use crate::{BlendSpace, Color, RenderError, RenderSize, RenderedTexture};
2use alpha2_gpu::GpuContext;
3use alpha2_gpu::IntermediateFormat;
4use alpha2_gpu::SubmitTimings;
5use std::sync::{Arc, Mutex};
6use std::time::Duration;
7
8/// Renders graphs of sources, effects, transitions and composites on one GPU
9/// device, and owns the pipelines, pools and caches they use.
10#[derive(Debug)]
11pub struct Renderer {
12    pub(crate) gpu: GpuContext,
13    pub(crate) blend_space: BlendSpace,
14    pub(crate) effects: std::sync::RwLock<crate::registry::EffectRegistry>,
15    pub(crate) effect_resources: std::sync::RwLock<crate::effect_resource::EffectResourceRegistry>,
16    pub(crate) textures: crate::Shared<crate::pool::TexturePool>,
17    pub(crate) upload_textures: crate::Shared<crate::pool::UploadTexturePool>,
18    /// Device memory budget in bytes, 0 when unknown.
19    pub(crate) gpu_memory_budget: std::sync::atomic::AtomicU64,
20    pub(crate) readback_buffers: crate::Shared<crate::pool::ReadbackBufferPool>,
21    pub(crate) uniform_buffers: crate::Shared<crate::uniform::UniformBufferPool>,
22    pub(crate) retirement: crate::Shared<crate::retire::Retirement>,
23    pub(crate) pipelines: crate::pipeline::PipelineCache,
24    pub(crate) diagnostics: crate::diagnostics::SharedDiagnostics,
25    pub(crate) quality: Mutex<QualityState>,
26    pub(crate) result_cache: Mutex<crate::result_cache::ResultCache>,
27    pub(crate) vector_state: Mutex<crate::vector::VectorState>,
28    pub(crate) timestamp_probe: std::sync::OnceLock<Option<crate::runtime_effect::TimestampProbe>>,
29    /// Timestamp queries for sampled export frames, created on first use.
30    pub(crate) frame_gpu_timer: std::sync::OnceLock<Option<crate::frame_gpu_time::FrameGpuTimer>>,
31    pub(crate) pass_timing: std::sync::atomic::AtomicBool,
32    /// Test-only: composite every layer full-frame as the culling reference.
33    #[cfg(test)]
34    pub(crate) full_frame_layers: std::sync::atomic::AtomicBool,
35    /// Test-only: max layers per composite pass when nonzero (1 = batching reference).
36    #[cfg(test)]
37    pub(crate) composite_batch_limit: std::sync::atomic::AtomicUsize,
38    /// Test-only: tile rows per vector atlas page when nonzero.
39    #[cfg(test)]
40    pub(crate) vector_page_rows: std::sync::atomic::AtomicU32,
41    /// Test-only: composite pipeline log.
42    #[cfg(test)]
43    pub(crate) composite_pipelines: Mutex<crate::composite::CompositePipelineLog>,
44    /// Test-only: the next lazily created composite or effect pipeline fails to create.
45    #[cfg(test)]
46    pub(crate) fail_next_pipeline: std::sync::atomic::AtomicBool,
47    pub(crate) retired_leases: Arc<crate::yuv::RetiredLeases>,
48    pub(crate) gpu_wait_timeout: Duration,
49    /// Read once because every field read crosses into JavaScript on the browser backend.
50    pub(crate) limits: wgpu::Limits,
51    pub(crate) features: wgpu::Features,
52    /// Bound to a generator's unused image inputs.
53    pub(crate) empty_input: wgpu::TextureView,
54    pub(crate) canaries: crate::canary::Canaries,
55    pub(crate) submission_canaries: crate::canary::SubmissionCanaries,
56    /// GPU errors the embedding saw outside the renderer's own scopes.
57    pub(crate) gpu_errors: crate::GpuErrorReports,
58    pub(crate) frame_lock: crate::Shared<FrameLock>,
59    pub(crate) submission_clock: Arc<crate::submission_clock::SubmissionClock>,
60    pub(crate) last_frame_submissions: Mutex<Option<crate::FrameSubmissions>>,
61    pub(crate) calibration: std::sync::OnceLock<crate::registry::RegisteredEffect>,
62}
63
64/// A command encoder open until submitted.
65///
66/// Pooled resources released meanwhile are destroyed only after submission (see
67/// [`crate::retire`]). It also holds the frame's error scopes, so it must stay on the creating
68/// thread, and the [`FrameLock`]. A heavy frame may be split into several command buffers
69/// ([`crate::submission_planner`]); finished ones wait here for the submission.
70#[derive(Debug)]
71pub(crate) struct RenderEncoder {
72    encoder: wgpu::CommandEncoder,
73    finished: Vec<wgpu::CommandBuffer>,
74    planner: crate::submission_planner::SubmissionPlanner,
75    device: wgpu::Device,
76    label: &'static str,
77    errors: crate::gpu_errors::FrameErrorScope,
78    scope: crate::retire::EncodeScope,
79    frame: FrameGuard,
80}
81
82/// Lets one thread at a time record and submit renderer work.
83///
84/// A graph returns intermediates to the pool once their last reader is encoded, while the
85/// passes that wrote them are still unsubmitted. Holding this lock from encoder creation to
86/// submission stops another thread from reusing such a texture and submitting first.
87/// Re-entrant for the holding thread.
88#[derive(Debug, Default)]
89pub(crate) struct FrameLock {
90    owner: Mutex<Option<(std::thread::ThreadId, usize)>>,
91    released: std::sync::Condvar,
92}
93
94#[derive(Debug)]
95pub(crate) struct FrameGuard {
96    lock: crate::Shared<FrameLock>,
97}
98
99impl FrameLock {
100    pub(crate) fn hold(self: &crate::Shared<Self>) -> FrameGuard {
101        let me = std::thread::current().id();
102        let mut owner = self
103            .owner
104            .lock()
105            .unwrap_or_else(std::sync::PoisonError::into_inner);
106        loop {
107            match owner.as_mut() {
108                None => {
109                    *owner = Some((me, 1));
110                    break;
111                }
112                Some((thread, depth)) if *thread == me => {
113                    *depth += 1;
114                    break;
115                }
116                Some(_) => {
117                    owner = self
118                        .released
119                        .wait(owner)
120                        .unwrap_or_else(std::sync::PoisonError::into_inner);
121                }
122            }
123        }
124        drop(owner);
125        FrameGuard {
126            lock: crate::Shared::clone(self),
127        }
128    }
129}
130
131impl Drop for FrameGuard {
132    fn drop(&mut self) {
133        let mut owner = self
134            .lock
135            .owner
136            .lock()
137            .unwrap_or_else(std::sync::PoisonError::into_inner);
138        if let Some((_, depth)) = owner.as_mut() {
139            *depth -= 1;
140            if *depth == 0 {
141                *owner = None;
142                drop(owner);
143                self.lock.released.notify_all();
144            }
145        }
146    }
147}
148
149impl std::ops::Deref for RenderEncoder {
150    type Target = wgpu::CommandEncoder;
151
152    fn deref(&self) -> &Self::Target {
153        &self.encoder
154    }
155}
156
157impl std::ops::DerefMut for RenderEncoder {
158    fn deref_mut(&mut self) -> &mut Self::Target {
159        &mut self.encoder
160    }
161}
162
163impl RenderEncoder {
164    pub(crate) fn finish(self) -> RenderCommands {
165        let mut buffers = self.finished;
166        buffers.push(self.encoder.finish());
167        RenderCommands {
168            buffers,
169            planner: self.planner,
170            errors: self.errors,
171            scope: self.scope,
172            frame: self.frame,
173        }
174    }
175
176    pub(crate) const fn planner(&mut self) -> &mut crate::submission_planner::SubmissionPlanner {
177        &mut self.planner
178    }
179
180    /// Charges a pass to the plan and returns its band count, finishing the command buffer first
181    /// when the plan says so.
182    pub(crate) fn place_pass(
183        &mut self,
184        cost: crate::effect_cost::EffectCost,
185        pixels: u64,
186        bandable: bool,
187    ) -> u32 {
188        let placement = self.planner.pass(cost, pixels, bandable);
189        if placement.cut_before {
190            self.cut();
191        }
192        placement.bands
193    }
194
195    pub(crate) fn next_band(&mut self) {
196        self.planner.next_band();
197        self.cut();
198    }
199
200    fn cut(&mut self) {
201        #[allow(clippy::disallowed_methods)]
202        let next = self
203            .device
204            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
205                label: Some(self.label),
206            });
207        let done = std::mem::replace(&mut self.encoder, next);
208        self.finished.push(done.finish());
209    }
210}
211
212#[derive(Debug)]
213pub(crate) struct RenderCommands {
214    buffers: Vec<wgpu::CommandBuffer>,
215    planner: crate::submission_planner::SubmissionPlanner,
216    errors: crate::gpu_errors::FrameErrorScope,
217    scope: crate::retire::EncodeScope,
218    frame: FrameGuard,
219}
220
221/// Classifies a loss by the submission times of its renderer.
222#[derive(Clone, Debug)]
223pub struct LossClassifier(Arc<crate::submission_clock::SubmissionClock>);
224
225impl LossClassifier {
226    /// Classifies `error` as [`Renderer::classify_loss`] does.
227    #[must_use]
228    pub fn classify(&self, error: RenderError) -> RenderError {
229        match error {
230            RenderError::GpuWorkDropped
231            | RenderError::GpuDeviceLost
232            | RenderError::GpuTimeout
233            | RenderError::ExternalTextureSync(Some(alpha2_media::GpuFault::DeviceLost)) => self
234                .0
235                .hung()
236                .map_or(error, |report| crate::canary::hung_error(&report)),
237            error => error,
238        }
239    }
240
241    /// The recent submission that kept the GPU busy longest.
242    #[must_use]
243    pub fn longest_submission(&self) -> Option<crate::SubmissionReport> {
244        self.0.longest()
245    }
246}
247
248struct SubmittedBuffers {
249    index: wgpu::SubmissionIndex,
250    timings: SubmitTimings,
251    sequences: std::ops::Range<u64>,
252}
253
254pub(crate) struct MeasuredSubmit {
255    pub(crate) index: wgpu::SubmissionIndex,
256    pub(crate) sequences: std::ops::Range<u64>,
257    pub(crate) timings: SubmitTimings,
258    pub(crate) lease_retire: Duration,
259}
260
261/// Quality controls consumed by graph compilation and pass execution.
262#[derive(Copy, Clone, Debug, Eq, PartialEq)]
263#[non_exhaustive]
264pub struct RenderQualityControls {
265    /// Maximum samples for filter effects and layer minification. Analytic edge coverage stays
266    /// on even with a one-sample budget.
267    pub max_filter_samples: u32,
268    /// Temporal samples used by motion-aware runners.
269    pub motion_blur_subframes: u32,
270}
271
272impl RenderQualityControls {
273    /// Upper bound on filter samples; every pass caps there, so a larger budget changes nothing.
274    pub const MAX_FILTER_SAMPLES: u32 = 64;
275}
276
277impl Default for RenderQualityControls {
278    fn default() -> Self {
279        Self {
280            max_filter_samples: Self::MAX_FILTER_SAMPLES,
281            motion_blur_subframes: 1,
282        }
283    }
284}
285
286#[derive(Copy, Clone, Debug)]
287pub(crate) struct QualityState {
288    applied: RenderQualityControls,
289    requested_filter_samples: u32,
290}
291
292impl QualityState {
293    fn new(limit: u32) -> Self {
294        let requested = RenderQualityControls::default();
295        Self {
296            applied: RenderQualityControls {
297                max_filter_samples: requested.max_filter_samples.min(limit),
298                ..requested
299            },
300            requested_filter_samples: requested.max_filter_samples,
301        }
302    }
303}
304
305impl Renderer {
306    pub(crate) fn validate_size(&self, size: RenderSize) -> Result<(), RenderError> {
307        RenderSize::new(size.width, size.height)?;
308        let maximum = self.limits.max_texture_dimension_2d;
309        if size.width > maximum || size.height > maximum {
310            return Err(RenderError::DimensionTooLarge);
311        }
312        Ok(())
313    }
314
315    /// Creates a renderer that owns the supplied GPU context.
316    #[must_use]
317    pub fn new(gpu: GpuContext) -> Self {
318        #[allow(clippy::disallowed_methods)]
319        let limits = gpu.device().limits();
320        let uniform_alignment = u64::from(limits.min_uniform_buffer_offset_alignment.max(1));
321        let features = gpu.device().features();
322        let filter_sample_limit = crate::filter_sample_limit(gpu.capabilities().tier);
323        let retirement = crate::Shared::new(crate::retire::Retirement::default());
324        let gpu_errors = crate::GpuErrorReports::default();
325        let submission_clock = Arc::new(crate::submission_clock::SubmissionClock::default());
326        let canaries = crate::canary::Canaries::new(
327            gpu_errors.clone(),
328            &retirement,
329            Arc::clone(&submission_clock),
330        );
331        let empty_input =
332            crate::pool::default_view(&gpu.device().create_texture(&wgpu::TextureDescriptor {
333                label: Some("alpha2 generator empty input"),
334                size: wgpu::Extent3d {
335                    width: 1,
336                    height: 1,
337                    depth_or_array_layers: 1,
338                },
339                mip_level_count: 1,
340                sample_count: 1,
341                dimension: wgpu::TextureDimension::D2,
342                format: wgpu::TextureFormat::Rgba8Unorm,
343                usage: wgpu::TextureUsages::TEXTURE_BINDING,
344                view_formats: &[],
345            }));
346        Self {
347            gpu,
348            blend_space: BlendSpace::default(),
349            effects: std::sync::RwLock::default(),
350            effect_resources: std::sync::RwLock::default(),
351            textures: crate::Shared::new(crate::pool::TexturePool::new(crate::Shared::clone(
352                &retirement,
353            ))),
354            upload_textures: crate::Shared::new(crate::pool::UploadTexturePool::new(
355                crate::Shared::clone(&retirement),
356            )),
357            gpu_memory_budget: std::sync::atomic::AtomicU64::new(0),
358            readback_buffers: crate::Shared::new(crate::pool::ReadbackBufferPool::new(
359                crate::Shared::clone(&retirement),
360            )),
361            uniform_buffers: crate::Shared::new(crate::uniform::UniformBufferPool::new(
362                uniform_alignment,
363                crate::Shared::clone(&retirement),
364            )),
365            retirement,
366            pipelines: crate::pipeline::PipelineCache::default(),
367            diagnostics: Arc::new(Mutex::new(crate::diagnostics::DiagnosticsState::default())),
368            quality: Mutex::new(QualityState::new(filter_sample_limit)),
369            result_cache: Mutex::new(crate::result_cache::ResultCache::default()),
370            vector_state: Mutex::default(),
371            timestamp_probe: std::sync::OnceLock::new(),
372            frame_gpu_timer: std::sync::OnceLock::new(),
373            pass_timing: std::sync::atomic::AtomicBool::new(false),
374            #[cfg(test)]
375            full_frame_layers: std::sync::atomic::AtomicBool::new(false),
376            #[cfg(test)]
377            composite_batch_limit: std::sync::atomic::AtomicUsize::new(0),
378            #[cfg(test)]
379            vector_page_rows: std::sync::atomic::AtomicU32::new(0),
380            #[cfg(test)]
381            composite_pipelines: Mutex::new(crate::composite::CompositePipelineLog::default()),
382            #[cfg(test)]
383            fail_next_pipeline: std::sync::atomic::AtomicBool::new(false),
384            retired_leases: Arc::new(crate::yuv::RetiredLeases::default()),
385            gpu_wait_timeout: crate::error::DEFAULT_GPU_WAIT_TIMEOUT,
386            limits,
387            features,
388            empty_input,
389            canaries,
390            submission_canaries: crate::canary::SubmissionCanaries::default(),
391            gpu_errors,
392            frame_lock: crate::Shared::default(),
393            submission_clock,
394            last_frame_submissions: Mutex::new(None),
395            calibration: std::sync::OnceLock::new(),
396        }
397    }
398
399    /// `None` on a device without timestamp queries, and in a browser.
400    pub(crate) fn frame_gpu_timer(&self) -> Option<&crate::frame_gpu_time::FrameGpuTimer> {
401        self.frame_gpu_timer
402            .get_or_init(|| {
403                (cfg!(not(target_arch = "wasm32"))
404                    && self.features.contains(wgpu::Features::TIMESTAMP_QUERY))
405                .then(|| {
406                    crate::frame_gpu_time::FrameGpuTimer::new(self.gpu.device(), self.gpu.queue())
407                })
408            })
409            .as_ref()
410    }
411
412    /// GPU time of the export frames sampled since the last call, then resets the totals.
413    ///
414    /// Every eighth frame of [`Self::render_graph_nv12_timed`] or
415    /// [`Self::render_graph_yuv420p_timed`] is timed and read back later without waiting.
416    ///
417    /// # Errors
418    /// The device has no timestamp queries.
419    pub fn take_frame_gpu_times(&self) -> Result<crate::FrameGpuTimes, &'static str> {
420        let timer = self
421            .frame_gpu_timer()
422            .ok_or("the device has no timestamp queries")?;
423        let _ = self.gpu.device().poll(wgpu::PollType::Poll);
424        Ok(timer.take())
425    }
426
427    /// Where an embedding reports errors from its uncaptured-error handler.
428    ///
429    /// Needed only in a browser, where error scopes resolve after the frame returns. After a
430    /// report the renderer drops its cached results and pooled resources, and treats a missing
431    /// readback canary as that error rather than as dropped work.
432    #[must_use]
433    pub fn gpu_error_reports(&self) -> crate::GpuErrorReports {
434        self.gpu_errors.clone()
435    }
436
437    /// This renderer, using `reports` for GPU errors the embedding saw before it existed.
438    #[must_use]
439    pub fn with_gpu_error_reports(mut self, reports: crate::GpuErrorReports) -> Self {
440        self.canaries.clear();
441        self.canaries = crate::canary::Canaries::new(
442            reports.clone(),
443            &self.retirement,
444            Arc::clone(&self.submission_clock),
445        );
446        self.gpu_errors = reports;
447        self
448    }
449
450    /// Drops pooled resources after the GPU reported an error that may involve them.
451    fn forget_untrusted_resources(&self) {
452        self.retirement.doubt();
453        self.textures.clear();
454        self.upload_textures.clear();
455        self.readback_buffers.clear();
456        self.uniform_buffers.clear();
457        self.canaries.clear();
458    }
459
460    /// Tier, intermediate format, adapter and limits of the GPU.
461    #[must_use]
462    pub fn gpu_capabilities(&self) -> &alpha2_gpu::Capabilities {
463        self.gpu.capabilities()
464    }
465
466    /// The device's limits.
467    #[must_use]
468    #[cfg_attr(not(feature = "wgpu-interop"), doc(hidden))]
469    pub const fn limits(&self) -> &wgpu::Limits {
470        &self.limits
471    }
472
473    /// Sets how long a native GPU wait may take before [`RenderError::GpuTimeout`].
474    pub fn set_gpu_wait_timeout(&mut self, timeout: Duration) {
475        self.gpu_wait_timeout = timeout;
476    }
477
478    /// Why the device can no longer run work, once known.
479    ///
480    /// Either a readback canary showed dropped work ([`RenderError::GpuWorkDropped`]) or resources
481    /// could no longer be created ([`RenderError::GpuDeviceLost`]). Later readbacks and NV12 packs
482    /// fail with this error; a host should report it and restart the process.
483    #[must_use]
484    pub fn gpu_lost(&self) -> Option<RenderError> {
485        self.canaries.lost()
486    }
487
488    /// Marks the frame later submissions render, for [`RenderError::GpuDeviceHung`] reports.
489    pub fn mark_frame(&self, frame: Option<crate::FrameMark>) {
490        self.submission_clock.mark_frame(frame);
491    }
492
493    /// The recent submission, possibly still running, that kept the GPU busy longest.
494    #[must_use]
495    pub fn longest_submission(&self) -> Option<crate::SubmissionReport> {
496        self.submission_clock.longest()
497    }
498
499    /// Classifies `error` using this renderer's submission times.
500    ///
501    /// A device loss or timeout becomes [`RenderError::GpuDeviceHung`] when a recent submission
502    /// ran for at least half the GPU watchdog ([`alpha2_gpu::hung_threshold_ms`]). Other errors
503    /// pass through.
504    #[must_use]
505    pub fn classify_loss(&self, error: RenderError) -> RenderError {
506        self.loss_classifier().classify(error)
507    }
508
509    /// [`Renderer::classify_loss`] as an owned handle, for readbacks finished on an event loop.
510    #[must_use]
511    pub fn loss_classifier(&self) -> LossClassifier {
512        LossClassifier(Arc::clone(&self.submission_clock))
513    }
514
515    pub(crate) fn ensure_gpu_runs_work(&self) -> Result<(), RenderError> {
516        self.canaries.lost().map_or(Ok(()), Err)
517    }
518
519    /// Checks canaries of earlier NV12 packs and repacks that have mapped, without waiting.
520    pub(crate) fn check_submitted_work(&self) -> Result<(), RenderError> {
521        // Map callbacks run only on poll; a hardware-encoder frame loop may not poll otherwise.
522        let _ = self.gpu.device().poll(wgpu::PollType::Poll);
523        self.submission_canaries.check_mapped()?;
524        self.ensure_gpu_runs_work()
525    }
526
527    /// Waits for every submitted NV12 pack and repack and checks that the GPU ran it.
528    ///
529    /// These submissions read nothing back, so a canary is the only proof the planes were written.
530    /// Exports call this after the last frame. Safe while another thread polls the device (the
531    /// macOS `VideoToolbox` worker does).
532    ///
533    /// # Errors
534    /// [`RenderError::GpuWorkDropped`] when a canary is missing, or [`RenderError::GpuTimeout`]
535    /// when work or a mapping report does not arrive in time.
536    #[cfg(not(target_arch = "wasm32"))]
537    pub fn confirm_gpu_work(&self) -> Result<(), RenderError> {
538        let deadline = web_time::Instant::now() + self.gpu_wait_timeout;
539        self.gpu
540            .device()
541            .poll(wgpu::PollType::Wait {
542                submission_index: None,
543                timeout: Some(self.gpu_wait_timeout),
544            })
545            .map_err(crate::error::poll_error)?;
546        let settled = self.settle(&self.submission_canaries.reports, deadline, || {
547            self.check_submitted_work()?;
548            Ok(self.submission_canaries.outstanding() == 0)
549        })?;
550        if settled {
551            Ok(())
552        } else {
553            Err(RenderError::GpuTimeout)
554        }
555    }
556
557    /// How long a native wait on GPU work may take.
558    #[must_use]
559    pub const fn gpu_wait_timeout(&self) -> Duration {
560        self.gpu_wait_timeout
561    }
562
563    /// Releases every native lease whose GPU work has finished, returning how many.
564    ///
565    /// A decoder surface returns only after the submission sampling it completes, so a caller out
566    /// of surface budget can call this and retry. Unsubmitted work is not waited on.
567    ///
568    /// # Errors
569    /// A readback error if the device cannot be polled.
570    #[cfg(not(target_arch = "wasm32"))]
571    pub fn reclaim_external_leases(&self) -> Result<usize, RenderError> {
572        let deadline = web_time::Instant::now() + self.gpu_wait_timeout;
573        self.gpu
574            .device()
575            .poll(wgpu::PollType::Wait {
576                submission_index: None,
577                timeout: Some(self.gpu_wait_timeout),
578            })
579            .map_err(crate::error::poll_error)?;
580        self.settle(&self.retired_leases.parks, deadline, || {
581            Ok(self.retired_leases.awaited() == 0)
582        })?;
583        Ok(self.retired_leases.drain())
584    }
585
586    /// Submits command buffers, then releases completed native leases.
587    ///
588    /// Leases must not be released inside `wgpu`'s submit: a shared-queue backend holds the decoder
589    /// queue lock there, and freeing a frame takes `FFmpeg`'s frame lock, which `FFmpeg` decode
590    /// threads take in the opposite order.
591    ///
592    /// # Errors
593    /// [`RenderError::Gpu`] when a scope caught an error; then nothing in the submission ran.
594    pub(crate) fn submit<I>(&self, commands: I) -> Result<wgpu::SubmissionIndex, RenderError>
595    where
596        I: IntoIterator<Item = RenderCommands>,
597    {
598        self.submit_measured(commands, false)
599            .map(|submitted| submitted.index)
600    }
601
602    /// Opens a command encoder and the error scopes its submission closes.
603    ///
604    /// Open it before acquiring the frame's targets so a failed allocation is the frame's error.
605    pub(crate) fn command_encoder(&self, label: &'static str) -> RenderEncoder {
606        if self.gpu_errors.take_unhandled() {
607            // The browser reported an error for earlier work; cached results may be bad.
608            self.clear_result_cache_for(crate::CacheInvalidation::GpuError);
609            self.forget_untrusted_resources();
610        }
611        // Wait for other frames before opening any scope of this one.
612        let frame = self.frame_lock.hold();
613        // Open first so nothing the encoder uses can be destroyed under it.
614        let scope = self.retirement.open();
615        let errors = crate::gpu_errors::FrameErrorScope::open(
616            self.gpu.device(),
617            crate::Shared::clone(&self.retirement),
618        );
619        #[allow(clippy::disallowed_methods)] // The one place a renderer encoder is created.
620        let encoder = self
621            .gpu
622            .device()
623            .create_command_encoder(&wgpu::CommandEncoderDescriptor { label: Some(label) });
624        RenderEncoder {
625            encoder,
626            finished: Vec::new(),
627            planner: crate::submission_planner::SubmissionPlanner::default(),
628            device: self.gpu.device().clone(),
629            label,
630            errors,
631            scope,
632            frame,
633        }
634    }
635
636    /// Defers destruction of released pool resources until the returned scope is dropped.
637    pub(crate) fn open_encode(&self) -> crate::retire::EncodeScope {
638        self.retirement.open()
639    }
640
641    /// Submits and reports the queue wait, submit and lease drain times.
642    ///
643    /// With `measure` false every span is zero; the submission clock still records it.
644    ///
645    /// # Errors
646    /// [`RenderError::Gpu`] when a scope caught an error; pooled resources are no longer trusted.
647    pub(crate) fn submit_measured<I>(
648        &self,
649        commands: I,
650        measure: bool,
651    ) -> Result<MeasuredSubmit, RenderError>
652    where
653        I: IntoIterator<Item = RenderCommands>,
654    {
655        let mut command_buffers = Vec::new();
656        let mut errors = Vec::new();
657        let mut scopes = Vec::new();
658        let mut frames = Vec::new();
659        let mut planners = Vec::new();
660        for commands in commands {
661            command_buffers.extend(commands.buffers.into_iter().map(|buffer| (buffer, None)));
662            if let Some(buffer_ms) = commands.planner.buffer_ms() {
663                let first = command_buffers.len() - buffer_ms.len();
664                for (slot, ms) in command_buffers[first..].iter_mut().zip(buffer_ms) {
665                    slot.1 = Some(ms);
666                }
667            }
668            planners.push(commands.planner);
669            errors.push(commands.errors);
670            scopes.push(commands.scope);
671            frames.push(commands.frame);
672        }
673        let submitted = self.submit_buffers(command_buffers, measure);
674        self.note_frame_submissions(&planners, &submitted);
675        let SubmittedBuffers {
676            index,
677            timings,
678            sequences,
679        } = submitted;
680        // Scopes close after the submit, in reverse order.
681        let mut caught = None;
682        for scope in errors.into_iter().rev() {
683            caught = match (caught, scope.close()) {
684                (Some(alpha2_gpu::GpuErrorKind::OutOfMemory), _) | (_, None) => caught,
685                (_, kind) => kind,
686            };
687        }
688        drop(scopes);
689        drop(frames);
690        let drain_started = measure.then(web_time::Instant::now);
691        self.retired_leases.drain();
692        if let Some(kind) = caught {
693            self.forget_untrusted_resources();
694            return Err(RenderError::Gpu { kind });
695        }
696        Ok(MeasuredSubmit {
697            index,
698            sequences,
699            timings,
700            lease_retire: drain_started.map_or(Duration::ZERO, |started| started.elapsed()),
701        })
702    }
703
704    /// Submits `buffers` in one submission, or one per buffer when the frame was split so the GPU
705    /// can be preempted between them. Every submission is timed for loss classification.
706    fn submit_buffers(
707        &self,
708        buffers: Vec<(wgpu::CommandBuffer, Option<f64>)>,
709        measure: bool,
710    ) -> SubmittedBuffers {
711        let submit = |buffers: Vec<wgpu::CommandBuffer>, predicted_ms: Option<f64>| {
712            let (index, timings) = if measure {
713                self.gpu.submit_timed(buffers)
714            } else {
715                (self.gpu.submit(buffers), SubmitTimings::default())
716            };
717            let sequence = self
718                .submission_clock
719                .record(web_time::Instant::now(), predicted_ms);
720            let clock = Arc::clone(&self.submission_clock);
721            self.gpu.on_submitted_work_done(move || {
722                clock.complete(sequence, web_time::Instant::now());
723            });
724            (index, timings, sequence)
725        };
726        if buffers.len() <= 1 || buffers.iter().all(|(_, ms)| ms.is_none()) {
727            let predicted_ms = buffers
728                .iter()
729                .filter_map(|(_, ms)| *ms)
730                .reduce(|a, b| a + b);
731            let (index, timings, sequence) = submit(
732                buffers.into_iter().map(|(buffer, _)| buffer).collect(),
733                predicted_ms,
734            );
735            return SubmittedBuffers {
736                index,
737                timings,
738                sequences: sequence..sequence + 1,
739            };
740        }
741        let mut total = SubmitTimings::default();
742        let mut last = None;
743        let mut first_sequence = None;
744        for (buffer, predicted_ms) in buffers {
745            let (index, timings, sequence) = submit(vec![buffer], predicted_ms);
746            total.queue_lock_wait = total
747                .queue_lock_wait
748                .saturating_add(timings.queue_lock_wait);
749            total.queue_submit = total.queue_submit.saturating_add(timings.queue_submit);
750            first_sequence.get_or_insert(sequence);
751            last = Some((index, sequence));
752        }
753        let (index, last_sequence) = last.expect("at least two buffers");
754        SubmittedBuffers {
755            index,
756            timings: total,
757            sequences: first_sequence.unwrap_or(last_sequence)..last_sequence + 1,
758        }
759    }
760
761    /// Records frame submissions and folds measured GPU time into the device rate on completion.
762    fn note_frame_submissions(
763        &self,
764        planners: &[crate::submission_planner::SubmissionPlanner],
765        submitted: &SubmittedBuffers,
766    ) {
767        let Some(planner) = planners.iter().find(|planner| planner.is_frame()) else {
768            return;
769        };
770        let submissions =
771            u32::try_from(submitted.sequences.end - submitted.sequences.start).unwrap_or(u32::MAX);
772        let buffer_ms = planner.buffer_ms();
773        let report = crate::FrameSubmissions {
774            submissions,
775            predicted_ms: buffer_ms.as_ref().map(|buffers| buffers.iter().sum()),
776            cost: planner.cost(),
777        };
778        crate::diagnostics::record_frame_plan(
779            &self.diagnostics,
780            &report,
781            buffer_ms
782                .iter()
783                .flatten()
784                .copied()
785                .fold(None, |most: Option<f64>, ms| {
786                    Some(most.map_or(ms, |most| most.max(ms)))
787                }),
788        );
789        *self
790            .last_frame_submissions
791            .lock()
792            .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(report);
793        if planner.is_planned() {
794            let clock = Arc::clone(&self.submission_clock);
795            let rate = Arc::clone(self.gpu.rate());
796            let sequences = submitted.sequences.clone();
797            let unit_pixels = report.cost.unit_pixels();
798            self.gpu.on_submitted_work_done(move || {
799                if let Some(measured_ms) = clock.gpu_ms(sequences) {
800                    rate.observe(measured_ms, unit_pixels);
801                }
802            });
803        }
804    }
805
806    /// How the last frame was submitted; each frame's is returned once.
807    pub fn take_frame_submissions(&self) -> Option<crate::FrameSubmissions> {
808        self.last_frame_submissions
809            .lock()
810            .unwrap_or_else(std::sync::PoisonError::into_inner)
811            .take()
812    }
813
814    /// Submission split counts since the last call, then resets them.
815    pub fn take_gpu_submission_stats(&self) -> crate::GpuSubmissionStats {
816        crate::diagnostics::take_gpu_submission_stats(&self.diagnostics)
817    }
818
819    /// Returns whether per-pass timing is being collected.
820    #[must_use]
821    pub fn pass_timing_enabled(&self) -> bool {
822        self.pass_timing.load(std::sync::atomic::Ordering::Relaxed)
823    }
824
825    /// Enables or disables per-pass timing collection. Disabled by default.
826    ///
827    /// While off, no clock is read and no timestamp resources are created. Turning it off drops
828    /// the retained timing history. Other diagnostics are always available.
829    pub fn set_pass_timing_enabled(&self, enabled: bool) {
830        self.pass_timing
831            .store(enabled, std::sync::atomic::Ordering::Relaxed);
832        if !enabled {
833            crate::diagnostics::end_timing_run(&self.diagnostics);
834        }
835    }
836
837    /// The timing run a pass encoded now records into, or `None` while timing is off. Read before
838    /// the flag: a run that ends after this read drops the pass's record.
839    pub(crate) fn pass_timing_epoch(&self) -> Option<u64> {
840        let epoch = crate::diagnostics::timing_epoch(&self.diagnostics);
841        self.pass_timing_enabled().then_some(epoch)
842    }
843
844    /// Capability-negotiated storage precision. Graph images hold premultiplied sRGB; layer blends
845    /// may use linear light.
846    #[must_use]
847    #[cfg_attr(not(feature = "wgpu-interop"), doc(hidden))]
848    pub fn intermediate_format(&self) -> wgpu::TextureFormat {
849        match self.gpu.capabilities().intermediate_format {
850            IntermediateFormat::Rgba16Float => wgpu::TextureFormat::Rgba16Float,
851            _ => wgpu::TextureFormat::Rgba8Unorm,
852        }
853    }
854
855    /// Returns allocation and reuse counters for intermediate render targets.
856    #[must_use]
857    pub fn texture_pool_stats(&self) -> crate::TexturePoolStats {
858        self.textures.stats()
859    }
860
861    /// Acquires a pooled RGBA8 source-upload texture.
862    ///
863    /// Submissions using it must be issued before the handle is dropped so later uploads stay
864    /// queue-ordered.
865    ///
866    /// # Errors
867    /// The dimensions exceed device limits.
868    #[cfg_attr(not(feature = "wgpu-interop"), doc(hidden))]
869    pub fn acquire_rgba8_upload_texture(
870        &self,
871        size: RenderSize,
872    ) -> Result<crate::UploadTexture, RenderError> {
873        self.validate_size(size)?;
874        Ok(self.upload_textures.acquire(
875            self.gpu.device(),
876            size,
877            wgpu::TextureFormat::Rgba8Unorm,
878            "alpha2 RGBA upload texture",
879        ))
880    }
881
882    /// Destroys all currently idle intermediate textures.
883    pub fn clear_texture_pool(&self) {
884        self.textures.clear();
885    }
886
887    /// Destroys GPU memory held only for reuse (idle pools and kept graph results) and returns the
888    /// bytes freed.
889    ///
890    /// Resources are destroyed rather than dropped so browser `WebGPU` frees them immediately.
891    /// Nothing still in use is released, and submitted work completes first, so this is safe
892    /// between calls.
893    pub fn release_idle_memory(&self) -> u64 {
894        let before = self.retirement.retired_bytes();
895        self.clear_result_cache();
896        self.textures.clear();
897        self.upload_textures.clear();
898        self.readback_buffers.clear();
899        self.uniform_buffers.clear();
900        self.canaries.clear();
901        self.vector_state
902            .lock()
903            .unwrap_or_else(std::sync::PoisonError::into_inner)
904            .cache
905            .clear();
906        self.retirement.retired_bytes().saturating_sub(before)
907    }
908
909    /// Sets the soft byte budget for idle intermediate textures, evicting down to it now.
910    pub fn set_texture_budget_bytes(&self, budget_bytes: u64) {
911        self.textures
912            .set_budget(budget_bytes.min(self.pool_budget_cap()));
913    }
914
915    /// Records the adapter's memory budget (`None` if unreported) and caps idle pools at a quarter
916    /// of it. Returns whether a pool budget was lowered.
917    pub fn set_gpu_memory_budget(&self, budget_bytes: Option<u64>) -> bool {
918        self.gpu_memory_budget.store(
919            budget_bytes.unwrap_or(0),
920            std::sync::atomic::Ordering::Relaxed,
921        );
922        let cap = self.pool_budget_cap();
923        let textures = self.textures.stats().budget_bytes;
924        let uploads = self.upload_textures.stats().budget_bytes;
925        if textures > cap {
926            self.textures.set_budget(cap);
927        }
928        if uploads > cap {
929            self.upload_textures.set_budget(cap);
930        }
931        textures > cap || uploads > cap
932    }
933
934    /// The adapter's device memory budget, when reported.
935    #[must_use]
936    pub fn gpu_memory_budget(&self) -> Option<u64> {
937        match self
938            .gpu_memory_budget
939            .load(std::sync::atomic::Ordering::Relaxed)
940        {
941            0 => None,
942            bytes => Some(bytes),
943        }
944    }
945
946    /// A quarter of the device memory budget, or unlimited when unknown.
947    fn pool_budget_cap(&self) -> u64 {
948        self.gpu_memory_budget().map_or(u64::MAX, |bytes| bytes / 4)
949    }
950
951    /// Applies filter and temporal sampling controls.
952    ///
953    /// The filter budget is capped at [`Self::filter_sample_limit`]; a reduction is reported as
954    /// [`crate::CapabilityDiagnostic::FilterSamplesReduced`]. Kept results are dropped only when
955    /// the applied values change.
956    pub fn set_quality_controls(&self, max_filter_samples: u32, motion_blur_subframes: u32) {
957        let requested = max_filter_samples.max(1);
958        let next = RenderQualityControls {
959            max_filter_samples: requested.min(self.filter_sample_limit()),
960            motion_blur_subframes: motion_blur_subframes.max(1),
961        };
962        let mut quality = self
963            .quality
964            .lock()
965            .unwrap_or_else(std::sync::PoisonError::into_inner);
966        quality.requested_filter_samples = requested;
967        if quality.applied != next {
968            quality.applied = next;
969            self.clear_result_cache_for(crate::CacheInvalidation::Quality);
970        }
971    }
972
973    /// [`RenderQualityControls::MAX_FILTER_SAMPLES`], or 16 on a Tier-B device.
974    #[must_use]
975    pub fn filter_sample_limit(&self) -> u32 {
976        crate::filter_sample_limit(self.gpu.capabilities().tier)
977    }
978
979    /// Lets kept graph results use up to `budget_bytes` (see
980    /// [`crate::RenderGraph::set_cache_intent`]); zero, the default, disables the cache. The
981    /// texture pool budget does not count these results.
982    pub fn set_result_cache_budget(&self, budget_bytes: u64) {
983        self.lock_result_cache().set_budget(budget_bytes);
984    }
985
986    /// Drops every kept graph result.
987    pub fn clear_result_cache(&self) {
988        self.clear_result_cache_for(crate::CacheInvalidation::Explicit);
989    }
990
991    /// The result cache's counters.
992    #[must_use]
993    pub fn result_cache_stats(&self) -> crate::ResultCacheStats {
994        self.lock_result_cache().stats()
995    }
996
997    /// Changes whenever a graph with an unchanged [`Self::graph_cache_key`] may render differently
998    /// (any result-cache clear or reported GPU error). Equal keys under an equal epoch mean equal
999    /// pixels.
1000    #[must_use]
1001    pub fn content_epoch(&self) -> u64 {
1002        self.lock_result_cache()
1003            .clears()
1004            .wrapping_add(self.gpu_errors.count())
1005    }
1006
1007    pub(crate) fn clear_result_cache_for(&self, reason: crate::CacheInvalidation) {
1008        self.lock_result_cache().clear(reason);
1009    }
1010
1011    pub(crate) fn lock_result_cache(
1012        &self,
1013    ) -> std::sync::MutexGuard<'_, crate::result_cache::ResultCache> {
1014        self.result_cache
1015            .lock()
1016            .unwrap_or_else(std::sync::PoisonError::into_inner)
1017    }
1018
1019    /// Returns the active render quality controls.
1020    #[must_use]
1021    pub fn quality_controls(&self) -> RenderQualityControls {
1022        self.quality_state().applied
1023    }
1024
1025    fn quality_state(&self) -> QualityState {
1026        *self
1027            .quality
1028            .lock()
1029            .unwrap_or_else(std::sync::PoisonError::into_inner)
1030    }
1031
1032    fn degradations(&self) -> Vec<crate::CapabilityDiagnostic> {
1033        let quality = self.quality_state();
1034        let (requested, applied) = (
1035            quality.requested_filter_samples,
1036            quality.applied.max_filter_samples,
1037        );
1038        if requested > applied {
1039            vec![crate::CapabilityDiagnostic::FilterSamplesReduced { requested, applied }]
1040        } else {
1041            Vec::new()
1042        }
1043    }
1044
1045    /// Returns a stable snapshot for telemetry or benchmark output.
1046    #[must_use]
1047    pub fn diagnostics(&self) -> crate::RenderDiagnostics {
1048        let quality = self.quality_controls();
1049        crate::diagnostics::snapshot(
1050            &self.diagnostics,
1051            self.gpu.capabilities(),
1052            &crate::diagnostics::ResourceDiagnostics {
1053                textures: self.texture_pool_stats(),
1054                upload_textures: self.upload_textures.stats(),
1055                readback_buffers: self.readback_buffers.stats(),
1056                uniform_buffers: self.uniform_buffers.stats(),
1057                pipelines: self.pipeline_cache_stats(),
1058                result_cache: self.result_cache_stats(),
1059            },
1060            quality.max_filter_samples,
1061            quality.motion_blur_subframes,
1062            self.degradations(),
1063        )
1064    }
1065
1066    /// Pipeline creations since the last call, oldest first (at most 256), with start and end
1067    /// times.
1068    pub fn take_pipeline_creations(&self) -> Vec<crate::PipelineCreation> {
1069        crate::diagnostics::take_pipeline_creations(&self.diagnostics)
1070    }
1071
1072    /// Records a host presentation outcome without imposing a product clock.
1073    pub fn record_frame_outcome(&self, presented: bool, repeated: bool) {
1074        crate::diagnostics::record_frame(&self.diagnostics, presented, repeated);
1075    }
1076
1077    /// Adds time spent waiting for a host decoder or refill operation.
1078    pub fn record_decoder_wait(&self, duration: Duration) {
1079        crate::diagnostics::record_decoder_wait(&self.diagnostics, duration);
1080    }
1081
1082    /// Returns the number of cached runtime and built-in pipelines.
1083    #[must_use]
1084    pub fn pipeline_cache_stats(&self) -> crate::PipelineCacheStats {
1085        crate::PipelineCacheStats {
1086            runtime_effects: self.effects().len(),
1087            builtins: self.pipelines.builtin_count(),
1088        }
1089    }
1090
1091    /// Selects the single color space used by all layer blending.
1092    #[must_use]
1093    pub const fn with_blend_space(mut self, blend_space: BlendSpace) -> Self {
1094        self.blend_space = blend_space;
1095        self
1096    }
1097
1098    /// Returns the configured layer-compositing color space.
1099    #[must_use]
1100    pub const fn blend_space(&self) -> BlendSpace {
1101        self.blend_space
1102    }
1103
1104    /// Clears an offscreen RGBA texture and submits it to the GPU queue.
1105    ///
1106    /// # Errors
1107    ///
1108    /// Returns [`RenderError`] for an invalid size or color.
1109    pub fn render_solid(
1110        &self,
1111        size: RenderSize,
1112        color: Color,
1113    ) -> Result<RenderedTexture, RenderError> {
1114        self.validate_size(size)?;
1115        if !color.is_valid() {
1116            return Err(RenderError::InvalidColor);
1117        }
1118        let format = self.intermediate_format();
1119        let mut encoder = self.command_encoder("alpha2 solid encoder");
1120        let texture = self.textures.acquire(
1121            self.gpu.device(),
1122            size,
1123            format,
1124            "alpha2 solid render target",
1125        );
1126        {
1127            let _pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1128                label: Some("alpha2 solid clear pass"),
1129                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1130                    view: texture.view(),
1131                    depth_slice: None,
1132                    resolve_target: None,
1133                    ops: wgpu::Operations {
1134                        load: wgpu::LoadOp::Clear(wgpu::Color {
1135                            r: color.red,
1136                            g: color.green,
1137                            b: color.blue,
1138                            a: color.alpha,
1139                        }),
1140                        store: wgpu::StoreOp::Store,
1141                    },
1142                })],
1143                depth_stencil_attachment: None,
1144                timestamp_writes: None,
1145                occlusion_query_set: None,
1146                multiview_mask: None,
1147            });
1148        }
1149        self.submit([encoder.finish()])?;
1150        Ok(RenderedTexture::pooled(size, format, texture))
1151    }
1152}