Skip to main content

alpha2_render/cpu/
renderer.rs

1//! The CPU renderer: its built-in catalog, controls and result cache.
2
3use std::collections::{HashMap, HashSet};
4use std::sync::atomic::{AtomicU64, Ordering};
5use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
6
7use super::frames::FramePool;
8use super::image::CpuImage;
9use super::kernels::{CpuKernel, CpuLut, kernel};
10use super::workers::Workers;
11use crate::result_cache::{CachedPicture, ResultCache};
12use crate::{
13    BlendSpace, CacheInvalidation, EffectCatalog, EffectDef, EffectId, GraphError, Lut3dData,
14    RenderCacheKey, RenderControls, RenderError, RenderGraph, RenderQualityControls,
15    ResultCacheStats,
16};
17
18impl CachedPicture for Arc<CpuImage> {
19    fn cached_bytes(&self) -> u64 {
20        self.retained_bytes()
21    }
22}
23
24pub(crate) struct CatalogEntry {
25    pub(crate) definition: Arc<EffectDef>,
26    pub(crate) reads_time: bool,
27    pub(crate) kernel: &'static dyn CpuKernel,
28}
29
30/// Counts of what the CPU renderer has drawn, for metrics.
31#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
32pub struct CpuRenderStats {
33    /// Graphs drawn.
34    pub graphs: u64,
35    /// Nodes drawn (not found in the result cache).
36    pub nodes: u64,
37    /// Time spent drawing graphs, in microseconds.
38    pub render_micros: u64,
39    /// Part of `render_micros` spent converting decoded frames to source pictures.
40    pub present_micros: u64,
41    /// Part of `render_micros` spent in effect, transition and generator passes.
42    pub kernel_micros: u64,
43    /// Part of `render_micros` spent compositing layers.
44    pub composite_micros: u64,
45    /// Part of `render_micros` spent drawing vector scenes.
46    pub vector_micros: u64,
47    /// Part of `render_micros` spent packing pictures into encoder planes.
48    pub pack_micros: u64,
49    /// Sources presented: decoded frames converted to pictures.
50    pub presented_sources: u64,
51    /// Bytes of the largest picture set one graph held at once.
52    pub image_high_water_bytes: u64,
53    /// Pictures drawn into a frame buffer kept from an earlier picture.
54    pub reused_frame_buffers: u64,
55}
56
57#[derive(Default)]
58pub(crate) struct StatCounters {
59    pub(crate) graphs: AtomicU64,
60    pub(crate) nodes: AtomicU64,
61    pub(crate) render_micros: AtomicU64,
62    pub(crate) present_micros: AtomicU64,
63    pub(crate) kernel_micros: AtomicU64,
64    pub(crate) composite_micros: AtomicU64,
65    pub(crate) vector_micros: AtomicU64,
66    pub(crate) pack_micros: AtomicU64,
67    pub(crate) presented_sources: AtomicU64,
68    pub(crate) image_high_water_bytes: AtomicU64,
69}
70
71/// Adds the microseconds since `started` to `counter`.
72pub(crate) fn add_elapsed(counter: &AtomicU64, started: web_time::Instant) {
73    counter.fetch_add(
74        u64::try_from(started.elapsed().as_micros()).unwrap_or(u64::MAX),
75        Ordering::Relaxed,
76    );
77}
78
79/// A renderer that draws [`RenderGraph`]s on the CPU with no GPU or driver.
80///
81/// It draws every built-in of the GPU [`crate::Renderer`] to the same contract: same graph,
82/// same stages, same half-float storage. Runtime WGSL effects have no CPU implementation and
83/// fail with [`RenderError::UnknownEffect`]. Output is identical for any thread count and target.
84pub struct CpuRenderer {
85    pub(crate) workers: Workers,
86    pub(crate) blend_space: BlendSpace,
87    pub(crate) frame_pool: Arc<FramePool>,
88    quality: Mutex<RenderQualityControls>,
89    cache: Mutex<ResultCache<Arc<CpuImage>>>,
90    catalog: HashMap<EffectId, CatalogEntry>,
91    internal: HashSet<EffectId>,
92    resources: std::sync::RwLock<HashMap<String, Arc<CpuLut>>>,
93    /// Vector coverage cached between frames, as on the GPU.
94    pub(crate) coverage: Mutex<alpha2_geometry::raster::CoverageCache>,
95    pub(crate) stats: StatCounters,
96    frames: AtomicU64,
97    repeated: AtomicU64,
98}
99
100impl std::fmt::Debug for CpuRenderer {
101    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
102        formatter
103            .debug_struct("CpuRenderer")
104            .field("threads", &self.workers.threads())
105            .field("blend_space", &self.blend_space)
106            .finish_non_exhaustive()
107    }
108}
109
110impl CpuRenderer {
111    /// A CPU renderer on `threads` threads (one means the calling thread), with every built-in
112    /// registered.
113    #[must_use]
114    pub fn new(threads: usize) -> Self {
115        Self::with_workers(Workers::new(threads))
116    }
117
118    /// As [`Self::new`], with every band `rows` rows high (`usize::MAX` for one band).
119    #[cfg(test)]
120    pub(crate) fn with_band_rows(threads: usize, rows: usize) -> Self {
121        Self::with_workers(Workers::with_band_rows(threads, rows))
122    }
123
124    fn with_workers(workers: Workers) -> Self {
125        let mut catalog = HashMap::new();
126        let mut internal = HashSet::new();
127        for (definition, is_internal) in crate::builtins::internal_effect_definitions()
128            .into_iter()
129            .map(|definition| (definition, true))
130            .chain(
131                crate::builtin_effect_definitions()
132                    .into_iter()
133                    .chain(crate::builtin_transition_definitions())
134                    .map(|definition| (definition, false)),
135            )
136        {
137            let Some(kernel) = kernel(&definition.id, definition.version) else {
138                continue;
139            };
140            let id = EffectId::new(definition.id.clone(), definition.version);
141            if is_internal {
142                internal.insert(id.clone());
143            }
144            catalog.insert(
145                id,
146                CatalogEntry {
147                    reads_time: crate::registry::body_reads_time(&definition.wgsl_body),
148                    definition: Arc::new(definition),
149                    kernel,
150                },
151            );
152        }
153        Self {
154            workers,
155            blend_space: BlendSpace::default(),
156            frame_pool: Arc::default(),
157            quality: Mutex::new(RenderQualityControls::default()),
158            cache: Mutex::new(ResultCache::default()),
159            catalog,
160            internal,
161            resources: std::sync::RwLock::default(),
162            coverage: Mutex::new(alpha2_geometry::raster::CoverageCache::default()),
163            stats: StatCounters::default(),
164            frames: AtomicU64::new(0),
165            repeated: AtomicU64::new(0),
166        }
167    }
168
169    /// Blends composites in `blend_space` unless a graph sets its own.
170    #[must_use]
171    pub const fn with_blend_space(mut self, blend_space: BlendSpace) -> Self {
172        self.blend_space = blend_space;
173        self
174    }
175
176    /// Threads the renderer draws on.
177    #[must_use]
178    pub const fn threads(&self) -> usize {
179        self.workers.threads()
180    }
181
182    /// The quality controls passes use now.
183    #[must_use]
184    pub fn quality_controls(&self) -> RenderQualityControls {
185        *self.quality.lock().unwrap_or_else(PoisonError::into_inner)
186    }
187
188    /// Built-ins the GPU registers that this renderer cannot draw, as `(id, version)`; currently
189    /// empty.
190    #[must_use]
191    pub fn unsupported_builtins() -> Vec<(String, u32)> {
192        crate::builtin_effect_definitions()
193            .into_iter()
194            .chain(crate::builtin_transition_definitions())
195            .chain(crate::builtins::internal_effect_definitions())
196            .filter(|definition| kernel(&definition.id, definition.version).is_none())
197            .map(|definition| (definition.id, definition.version))
198            .collect()
199    }
200
201    /// Keeps up to `budget_bytes` of node results for reuse, like
202    /// [`crate::Renderer::set_result_cache_budget`].
203    pub fn set_result_cache_budget(&self, budget_bytes: u64) {
204        self.lock_cache().set_budget(budget_bytes);
205    }
206
207    /// The result cache's counters.
208    #[must_use]
209    pub fn result_cache_stats(&self) -> ResultCacheStats {
210        self.lock_cache().stats()
211    }
212
213    /// Drops every cached result.
214    pub fn clear_result_cache(&self) {
215        self.lock_cache().clear(CacheInvalidation::Explicit);
216    }
217
218    /// What the renderer has drawn so far.
219    #[must_use]
220    pub fn stats(&self) -> CpuRenderStats {
221        CpuRenderStats {
222            graphs: self.stats.graphs.load(Ordering::Relaxed),
223            nodes: self.stats.nodes.load(Ordering::Relaxed),
224            render_micros: self.stats.render_micros.load(Ordering::Relaxed),
225            present_micros: self.stats.present_micros.load(Ordering::Relaxed),
226            kernel_micros: self.stats.kernel_micros.load(Ordering::Relaxed),
227            composite_micros: self.stats.composite_micros.load(Ordering::Relaxed),
228            vector_micros: self.stats.vector_micros.load(Ordering::Relaxed),
229            pack_micros: self.stats.pack_micros.load(Ordering::Relaxed),
230            presented_sources: self.stats.presented_sources.load(Ordering::Relaxed),
231            image_high_water_bytes: self.stats.image_high_water_bytes.load(Ordering::Relaxed),
232            reused_frame_buffers: self.frame_pool.reused(),
233        }
234    }
235
236    /// Frames presented and frames that repeated the previous one, as recorded via
237    /// [`RenderControls::record_frame_outcome`].
238    #[must_use]
239    pub fn frame_outcomes(&self) -> (u64, u64) {
240        (
241            self.frames.load(Ordering::Relaxed),
242            self.repeated.load(Ordering::Relaxed),
243        )
244    }
245
246    /// Registers or replaces 3D LUT `id`, like [`crate::Renderer::register_lut3d`].
247    ///
248    /// # Errors
249    /// [`RenderError::InvalidEffectResource`] for an empty id or an invalid cube.
250    pub fn register_lut3d(
251        &self,
252        id: impl Into<String>,
253        data: &Lut3dData,
254    ) -> Result<(), RenderError> {
255        let id = id.into();
256        if id.is_empty() || !data.is_valid(u32::MAX) {
257            return Err(RenderError::InvalidEffectResource);
258        }
259        // Stored as the GPU's half-float texture stores it.
260        let values = data
261            .values
262            .iter()
263            .map(|rgb| rgb.map(|value| half::f16::from_f32(value).to_f32()))
264            .collect();
265        self.resources_mut().insert(
266            id,
267            Arc::new(CpuLut {
268                edge: data.edge_length,
269                domain_min: data.domain_min,
270                domain_max: data.domain_max,
271                values,
272            }),
273        );
274        self.lock_cache().clear(CacheInvalidation::EffectResources);
275        Ok(())
276    }
277
278    /// Removes every resource and clears the cached results.
279    pub fn clear_effect_resources(&self) {
280        self.resources_mut().clear();
281        self.lock_cache().clear(CacheInvalidation::EffectResources);
282    }
283
284    /// Drops the cached results and idle frame buffers and returns the bytes they held.
285    pub fn release_idle_memory(&self) -> u64 {
286        let mut cache = self.lock_cache();
287        let bytes = cache.stats().bytes;
288        cache.clear(CacheInvalidation::Explicit);
289        drop(cache);
290        bytes + self.frame_pool.release()
291    }
292
293    /// Drops the frame buffers kept for the next frame and returns their bytes; the result cache
294    /// stays.
295    pub fn release_frame_buffers(&self) -> u64 {
296        self.frame_pool.release()
297    }
298
299    /// Removes the resource `id` and returns whether it existed.
300    pub fn unregister_effect_resource(&self, id: &str) -> bool {
301        let removed = self.resources_mut().remove(id).is_some();
302        if removed {
303            self.lock_cache().clear(CacheInvalidation::EffectResources);
304        }
305        removed
306    }
307
308    pub(crate) fn resource(&self, id: &str) -> Option<Arc<CpuLut>> {
309        self.resources
310            .read()
311            .unwrap_or_else(PoisonError::into_inner)
312            .get(id)
313            .cloned()
314    }
315
316    fn resources_mut(&self) -> std::sync::RwLockWriteGuard<'_, HashMap<String, Arc<CpuLut>>> {
317        self.resources
318            .write()
319            .unwrap_or_else(PoisonError::into_inner)
320    }
321
322    pub(crate) fn entry(&self, id: &EffectId) -> Option<&CatalogEntry> {
323        self.catalog.get(id)
324    }
325
326    pub(crate) fn lock_cache(&self) -> MutexGuard<'_, ResultCache<Arc<CpuImage>>> {
327        self.cache.lock().unwrap_or_else(PoisonError::into_inner)
328    }
329}
330
331impl EffectCatalog for CpuRenderer {
332    fn effect_definition(&self, id: &EffectId) -> Option<Arc<EffectDef>> {
333        self.catalog
334            .get(id)
335            .map(|entry| Arc::clone(&entry.definition))
336    }
337
338    fn effect_reads_time(&self, id: &EffectId) -> bool {
339        if let Some(passes) = crate::gaussian_blur::expanded_passes(id.as_str()) {
340            return passes
341                .iter()
342                .any(|pass| self.effect_reads_time(&EffectId::from_static(pass, 1)));
343        }
344        self.catalog.get(id).is_none_or(|entry| entry.reads_time)
345    }
346
347    fn project_effect_id(&self, id: &str, version: u32) -> Option<EffectId> {
348        let key = EffectId::new(id.to_owned(), version);
349        self.catalog
350            .get_key_value(&key)
351            .map(|(id, _)| id)
352            .filter(|id| !self.internal.contains(*id))
353            .cloned()
354    }
355}
356
357impl RenderControls for CpuRenderer {
358    fn set_quality_controls(&self, max_filter_samples: u32, motion_blur_subframes: u32) {
359        let next = RenderQualityControls {
360            max_filter_samples: max_filter_samples
361                .clamp(1, RenderQualityControls::MAX_FILTER_SAMPLES),
362            motion_blur_subframes: motion_blur_subframes.max(1),
363        };
364        let mut quality = self.quality.lock().unwrap_or_else(PoisonError::into_inner);
365        if *quality != next {
366            *quality = next;
367            drop(quality);
368            // Results under other controls are different pictures.
369            self.lock_cache().clear(CacheInvalidation::Quality);
370        }
371    }
372
373    fn set_texture_budget_bytes(&self, budget_bytes: u64) {
374        self.frame_pool.set_budget(budget_bytes);
375    }
376
377    fn content_epoch(&self) -> u64 {
378        self.lock_cache().clears()
379    }
380
381    fn record_frame_outcome(&self, presented: bool, repeated: bool) {
382        if presented {
383            self.frames.fetch_add(1, Ordering::Relaxed);
384        }
385        if repeated {
386            self.repeated.fetch_add(1, Ordering::Relaxed);
387        }
388    }
389
390    fn graph_cache_key(&self, graph: &RenderGraph<'_>) -> Result<RenderCacheKey, GraphError> {
391        let quality = self.quality_controls();
392        let plan = graph.compile_with_quality(quality)?;
393        Ok(crate::graph_cache::cpu_renderer_cache_key(
394            plan.cache_key,
395            graph.blend_space.unwrap_or(self.blend_space).shader_value(),
396            quality,
397        ))
398    }
399}