Skip to main content

alpha2_render/cpu/
source.rs

1//! CPU graph sources, and the CPU port of yuv-to-linear.wesl and rgba-present.wesl that turns a
2//! decoded frame into a source picture.
3//!
4//! Planes are not copied: a source holds the decoder's buffers and converts on first draw.
5
6use std::fmt;
7use std::sync::atomic::Ordering;
8use std::sync::{Arc, OnceLock};
9
10use alpha2_media::{ColorMetadata, YuvFormat};
11
12use super::CpuRenderer;
13use super::curves::{self, extended_linear_to_srgb, linear_to_srgb};
14use super::half;
15use super::image::{CpuImage, PixelBox};
16use super::renderer::add_elapsed;
17use crate::hdr::HdrToneMap;
18use crate::yuv::{
19    HdrHandling, PlaneStorage, PresentedEncoding, hdr_handling, presentation_uniform_bytes,
20    uniform_bytes, validate_presentation,
21};
22use crate::{
23    ColorDiagnostic, ColorPolicy, RenderError, RenderSize, SourceAlpha, SourcePlane,
24    SourcePresentation, YuvFrame,
25};
26
27/// Decoded YCbCr planes owned by the decoder and kept unchanged while any source holds them.
28pub trait YuvPlanes: Send + Sync + fmt::Debug {
29    /// The frame the planes hold.
30    fn frame(&self) -> YuvFrame<'_>;
31}
32
33/// RGBA pixels a source converts from: 8-bit, or half-float bits for linear sources.
34pub trait RgbaPixels: Send + Sync + fmt::Debug {
35    /// The pixel bytes, rows `stride` bytes apart.
36    fn plane(&self) -> SourcePlane<'_>;
37}
38
39impl RgbaPixels for Vec<u8> {
40    fn plane(&self) -> SourcePlane<'_> {
41        SourcePlane {
42            bytes: self,
43            stride: 0,
44        }
45    }
46}
47
48/// A CPU graph source ([`crate::SourceView::cpu`]) holding premultiplied sRGB RGBA, like every
49/// GPU source texture. Decoded frames convert on first draw and the result is kept.
50#[derive(Clone)]
51pub struct CpuSource {
52    inner: Arc<SourceInner>,
53}
54
55struct SourceInner {
56    content: Content,
57    presented: OnceLock<Arc<CpuImage>>,
58}
59
60enum Content {
61    Image(Arc<CpuImage>),
62    Yuv {
63        planes: Arc<dyn YuvPlanes>,
64        conversion: Box<YuvConversion>,
65    },
66    Rgba {
67        pixels: Arc<dyn RgbaPixels>,
68        stride: u32,
69        size: RenderSize,
70        geometry: Geometry,
71        encoding: PresentedEncoding,
72    },
73}
74
75impl fmt::Debug for CpuSource {
76    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
77        let kind = match &self.inner.content {
78            Content::Image(_) => "image",
79            Content::Yuv { .. } => "yuv",
80            Content::Rgba { .. } => "rgba",
81        };
82        formatter
83            .debug_struct("CpuSource")
84            .field("kind", &kind)
85            .field("presented", &self.inner.presented.get().is_some())
86            .finish()
87    }
88}
89
90impl CpuSource {
91    /// A source that shows `picture` as it is.
92    #[must_use]
93    pub fn image(picture: Arc<CpuImage>) -> Self {
94        Self::new(Content::Image(picture))
95    }
96
97    fn new(content: Content) -> Self {
98        Self {
99            inner: Arc::new(SourceInner {
100                content,
101                presented: OnceLock::new(),
102            }),
103        }
104    }
105
106    /// Bytes held: the picture once presented.
107    #[must_use]
108    pub fn retained_bytes(&self) -> u64 {
109        match &self.inner.content {
110            Content::Image(image) => image.retained_bytes(),
111            _ => self
112                .inner
113                .presented
114                .get()
115                .map_or(0, |image| image.retained_bytes()),
116        }
117    }
118
119    /// The picture the source shows, converting it on first use.
120    pub(crate) fn presented(&self, renderer: &CpuRenderer) -> Arc<CpuImage> {
121        if let Content::Image(image) = &self.inner.content {
122            return Arc::clone(image);
123        }
124        if let Some(image) = self.inner.presented.get() {
125            return Arc::clone(image);
126        }
127        let started = web_time::Instant::now();
128        let image = Arc::new(match &self.inner.content {
129            Content::Image(_) => unreachable!("handled above"),
130            Content::Yuv { planes, conversion } => {
131                present_yuv(renderer, &planes.frame(), conversion, Path::Fastest)
132            }
133            Content::Rgba {
134                pixels,
135                stride,
136                size,
137                geometry,
138                encoding,
139            } => present_rgba(
140                renderer,
141                &RgbaSource {
142                    bytes: pixels.plane().bytes,
143                    stride: *stride as usize,
144                    size: *size,
145                    encoding: *encoding,
146                },
147                geometry,
148                Path::Fastest,
149            ),
150        });
151        add_elapsed(&renderer.stats.present_micros, started);
152        renderer
153            .stats
154            .presented_sources
155            .fetch_add(1, Ordering::Relaxed);
156        Arc::clone(self.inner.presented.get_or_init(|| image))
157    }
158
159    /// The picture drawn by the table path where it applies (`tables`), or by the per-pixel
160    /// shader port, which the table path must equal.
161    #[cfg(test)]
162    pub(crate) fn presented_by(&self, renderer: &CpuRenderer, tables: bool) -> CpuImage {
163        let path = if tables { Path::Tables } else { Path::PerPixel };
164        match &self.inner.content {
165            Content::Image(image) => (**image).clone(),
166            Content::Yuv { planes, conversion } => {
167                present_yuv(renderer, &planes.frame(), conversion, path)
168            }
169            Content::Rgba {
170                pixels,
171                stride,
172                size,
173                geometry,
174                encoding,
175            } => present_rgba(
176                renderer,
177                &RgbaSource {
178                    bytes: pixels.plane().bytes,
179                    stride: *stride as usize,
180                    size: *size,
181                    encoding: *encoding,
182                },
183                geometry,
184                path,
185            ),
186        }
187    }
188}
189
190/// Presentation uniforms parsed from the same bytes the GPU path binds, so both paths match.
191#[derive(Clone, Copy, Debug)]
192struct Geometry {
193    output: [f32; 2],
194    source: [f32; 2],
195    visible: [f32; 4],
196    draw: [f32; 4],
197    orientation: u32,
198    max_filter_samples: f32,
199}
200
201#[derive(Clone, Debug)]
202#[allow(clippy::struct_excessive_bools)]
203struct YuvConversion {
204    rows: [[f32; 3]; 3],
205    range_scale: [f32; 3],
206    range_offset: [f32; 3],
207    transfer: u32,
208    alpha: f32,
209    alpha_plane: bool,
210    alpha_scale: f32,
211    geometry: Geometry,
212    chroma_size: [f32; 2],
213    chroma_offset: [f32; 2],
214    interleaved: bool,
215    chroma_scale: [f32; 2],
216    gamut: [[f32; 3]; 3],
217    tone: [f32; 4],
218    hlg_gamma: f32,
219    chroma_window: [f32; 4],
220    format: YuvFormat,
221    /// SDR BT.709 without an alpha plane: decoding and re-encoding with sRGB is the identity, so
222    /// the encoded value is kept.
223    encoded_identity: bool,
224    /// The HDR policy skipped the source, so it shows nothing.
225    skipped: bool,
226}
227
228fn word(bytes: &[u8], offset: usize) -> [u8; 4] {
229    bytes[offset..offset + 4].try_into().expect("four bytes")
230}
231
232fn float(bytes: &[u8], offset: usize) -> f32 {
233    f32::from_ne_bytes(word(bytes, offset))
234}
235
236fn unsigned(bytes: &[u8], offset: usize) -> u32 {
237    u32::from_ne_bytes(word(bytes, offset))
238}
239
240fn floats<const N: usize>(bytes: &[u8], offset: usize) -> [f32; N] {
241    std::array::from_fn(|index| float(bytes, offset + index * 4))
242}
243
244impl YuvConversion {
245    /// Parses `YuvUniforms` (yuv-to-linear.wesl) as `uniform_bytes` writes them.
246    fn from_uniform(bytes: &[u8], format: YuvFormat) -> Self {
247        let rows = [floats::<3>(bytes, 0), floats(bytes, 16), floats(bytes, 32)];
248        let gamut = [
249            floats::<3>(bytes, 176),
250            floats(bytes, 192),
251            floats(bytes, 208),
252        ];
253        let transfer = unsigned(bytes, 80);
254        let alpha_plane = unsigned(bytes, 88) != 0;
255        let identity = gamut.iter().enumerate().all(|(row, values)| {
256            values.iter().enumerate().all(|(column, value)| {
257                let expected = if row == column { 1.0 } else { 0.0 };
258                (value - expected).abs() <= 1.0e-6
259            })
260        });
261        let size = floats::<4>(bytes, 96);
262        Self {
263            rows,
264            range_scale: floats(bytes, 48),
265            range_offset: floats(bytes, 64),
266            transfer,
267            alpha: float(bytes, 84),
268            alpha_plane,
269            alpha_scale: float(bytes, 92),
270            geometry: Geometry {
271                output: [size[0], size[1]],
272                source: [size[2], size[3]],
273                visible: floats(bytes, 112),
274                draw: floats(bytes, 128),
275                orientation: unsigned(bytes, 160),
276                max_filter_samples: float(bytes, 272),
277            },
278            chroma_size: floats(bytes, 144),
279            chroma_offset: floats(bytes, 152),
280            interleaved: unsigned(bytes, 164) == 1,
281            chroma_scale: floats(bytes, 168),
282            gamut,
283            tone: floats(bytes, 224),
284            hlg_gamma: float(bytes, 240),
285            chroma_window: floats(bytes, 256),
286            format,
287            encoded_identity: transfer == 0 && identity && !alpha_plane,
288            skipped: false,
289        }
290    }
291}
292
293impl Geometry {
294    /// From `PresentationParams` (rgba-present.wesl).
295    fn from_uniform(bytes: &[u8]) -> Self {
296        let size = floats::<4>(bytes, 0);
297        Self {
298            output: [size[0], size[1]],
299            source: [size[2], size[3]],
300            visible: floats(bytes, 16),
301            draw: floats(bytes, 32),
302            orientation: unsigned(bytes, 48),
303            max_filter_samples: float(bytes, 56),
304        }
305    }
306
307    /// Output pixels inside the drawn rectangle; everything else is transparent.
308    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
309    fn bounds(&self, size: RenderSize) -> PixelBox {
310        // Pixel centres p + 0.5 inside [draw.x, draw.x + draw.w).
311        let first = |origin: f32| (origin - 0.5).ceil().max(0.0) as u32;
312        let end = |origin: f32, extent: f32| ((origin + extent - 0.5).ceil()).max(0.0) as u32;
313        let x = first(self.draw[0]);
314        let y = first(self.draw[1]);
315        let right = end(self.draw[0], self.draw[2]).min(size.width);
316        let bottom = end(self.draw[1], self.draw[3]).min(size.height);
317        if right <= x || bottom <= y {
318            return PixelBox::EMPTY;
319        }
320        PixelBox {
321            x,
322            y,
323            width: right - x,
324            height: bottom - y,
325        }
326    }
327
328    fn inside(&self, destination: [f32; 2]) -> bool {
329        destination[0] >= self.draw[0]
330            && destination[1] >= self.draw[1]
331            && destination[0] < self.draw[0] + self.draw[2]
332            && destination[1] < self.draw[1] + self.draw[3]
333    }
334
335    /// `source_pixel_at`: the stored pixel shown at output `destination`, clamped to the visible
336    /// rect.
337    fn source_pixel_at(&self, destination: [f32; 2]) -> [f32; 2] {
338        let local = [
339            (destination[0] - self.draw[0]) / self.draw[2],
340            (destination[1] - self.draw[1]) / self.draw[3],
341        ];
342        let mut source = match self.orientation & 3 {
343            1 => [local[1], 1.0 - local[0]],
344            2 => [1.0 - local[0], 1.0 - local[1]],
345            3 => [1.0 - local[1], local[0]],
346            _ => local,
347        };
348        if self.orientation & 4 != 0 {
349            source[0] = 1.0 - source[0];
350        }
351        let [origin_x, origin_y, width, height] = self.visible;
352        [
353            (origin_x + source[0] * width).clamp(origin_x + 0.5, origin_x + width - 0.5),
354            (origin_y + source[1] * height).clamp(origin_y + 0.5, origin_y + height - 0.5),
355        ]
356    }
357
358    /// `filter_grid`: samples per output pixel along each axis.
359    fn filter_grid(&self) -> [f32; 2] {
360        let mut extent = [self.visible[2], self.visible[3]];
361        if self.orientation & 1 != 0 {
362            extent.swap(0, 1);
363        }
364        let wanted = |extent: f32, drawn: f32| {
365            let footprint = extent / drawn;
366            if footprint > 2.0 {
367                (footprint - 0.0001).ceil().clamp(1.0, 8.0)
368            } else {
369                1.0
370            }
371        };
372        let wanted = [
373            wanted(extent[0], self.draw[2]),
374            wanted(extent[1], self.draw[3]),
375        ];
376        let budget = self.max_filter_samples.clamp(1.0, 64.0);
377        let columns = wanted[0].min(budget);
378        let rows = wanted[1].min((budget / columns).floor().max(1.0));
379        [columns, rows]
380    }
381
382    /// The source axis that output axis `axis` (0 = x) drives.
383    const fn source_axis(&self, axis: usize) -> usize {
384        if self.orientation & 1 == 0 {
385            axis
386        } else {
387            1 - axis
388        }
389    }
390
391    /// The coordinate along [`Self::source_axis`] that [`Self::source_pixel_at`] gives output
392    /// position `destination` on `axis`, with the same arithmetic.
393    fn source_coordinate(&self, axis: usize, destination: f32) -> f32 {
394        let local = (destination - self.draw[axis]) / self.draw[axis + 2];
395        let reflected = match (self.orientation & 3, axis) {
396            (1, 0) | (2, _) | (3, 1) => 1.0 - local,
397            _ => local,
398        };
399        let source_axis = self.source_axis(axis);
400        let value = if source_axis == 0 && self.orientation & 4 != 0 {
401            1.0 - reflected
402        } else {
403            reflected
404        };
405        let origin = self.visible[source_axis];
406        let extent = self.visible[source_axis + 2];
407        (origin + value * extent).clamp(origin + 0.5, origin + extent - 0.5)
408    }
409
410    /// Whether output position `destination` on `axis` is inside the drawn rectangle.
411    fn inside_axis(&self, axis: usize, destination: f32) -> bool {
412        destination >= self.draw[axis] && destination < self.draw[axis] + self.draw[axis + 2]
413    }
414
415    /// The offsets of `filtered`'s samples from a pixel centre along `axis`, in grid order.
416    fn grid_offsets(grid: [f32; 2], axis: usize) -> Vec<f32> {
417        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
418        (0..grid[axis] as u32)
419            .map(|index| {
420                #[allow(clippy::cast_precision_loss)]
421                let offset = (index as f32 + 0.5) / grid[axis] - 0.5;
422                offset
423            })
424            .collect()
425    }
426
427    /// `filtered_stored` around `stored_sample`.
428    fn filtered(&self, destination: [f32; 2], sample: impl Fn([f32; 2]) -> [f32; 4]) -> [f32; 4] {
429        let grid = self.filter_grid();
430        #[allow(clippy::float_cmp)]
431        if grid == [1.0, 1.0] {
432            return sample(self.source_pixel_at(destination));
433        }
434        let mut sum = [0.0_f32; 4];
435        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
436        for row in 0..grid[1] as u32 {
437            for column in 0..grid[0] as u32 {
438                #[allow(clippy::cast_precision_loss)]
439                let offset = [
440                    (column as f32 + 0.5) / grid[0] - 0.5,
441                    (row as f32 + 0.5) / grid[1] - 0.5,
442                ];
443                let value = sample(
444                    self.source_pixel_at([destination[0] + offset[0], destination[1] + offset[1]]),
445                );
446                for channel in 0..4 {
447                    sum[channel] += value[channel];
448                }
449            }
450        }
451        let count = grid[0] * grid[1];
452        sum.map(|value| value / count)
453    }
454}
455
456/// Converts the presented picture row by row with `pixel` into a stored picture.
457fn present_rows(
458    renderer: &CpuRenderer,
459    size: RenderSize,
460    geometry: &Geometry,
461    pixel: impl Fn([f32; 2]) -> [f32; 4] + Sync + Send,
462) -> CpuImage {
463    let bounds = geometry.bounds(size);
464    if bounds.is_empty() {
465        return CpuImage::transparent(size);
466    }
467    let width = bounds.width as usize;
468    let mut pixels = renderer.frame_pool.take(bounds.pixels());
469    renderer
470        .workers
471        .bands(&mut pixels, width, |first_row, band| {
472            for (index, line) in band.chunks_mut(width).enumerate() {
473                #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
474                let y = (bounds.y as usize + first_row + index) as f32 + 0.5;
475                for (offset, out) in line.iter_mut().enumerate() {
476                    #[allow(clippy::cast_precision_loss)]
477                    let x = (bounds.x as usize + offset) as f32 + 0.5;
478                    let destination = [x, y];
479                    *out = if geometry.inside(destination) {
480                        half::store4(pixel(destination))
481                    } else {
482                        [0; 4]
483                    };
484                }
485            }
486        });
487    CpuImage::pooled(size, bounds, pixels, &renderer.frame_pool)
488}
489
490/// One plane sampled like a clamp-to-edge texture: 8-bit codes as `code / 255`, 16-bit
491/// containers as `container / 65535`.
492struct Plane<'a> {
493    bytes: &'a [u8],
494    stride: usize,
495    width: u32,
496    height: u32,
497    wide: bool,
498    /// Samples per texel: 2 for interleaved chroma.
499    components: usize,
500}
501
502impl Plane<'_> {
503    #[inline]
504    fn texel(&self, x: i64, y: i64, component: usize) -> f32 {
505        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
506        let (x, y) = (
507            x.clamp(0, i64::from(self.width) - 1) as usize,
508            y.clamp(0, i64::from(self.height) - 1) as usize,
509        );
510        let sample = x * self.components + component;
511        if self.wide {
512            let offset = y * self.stride + sample * 2;
513            f32::from(u16::from_le_bytes([
514                self.bytes[offset],
515                self.bytes[offset + 1],
516            ])) / 65535.0
517        } else {
518            half::unorm8_value(self.bytes[y * self.stride + sample])
519        }
520    }
521
522    /// Bilinear sample at normalized `position`.
523    #[inline]
524    fn sample(&self, position: [f32; 2], component: usize) -> f32 {
525        #[allow(clippy::cast_precision_loss)]
526        let texel = [
527            position[0] * self.width as f32 - 0.5,
528            position[1] * self.height as f32 - 0.5,
529        ];
530        let origin = [texel[0].floor(), texel[1].floor()];
531        let weight = [texel[0] - origin[0], texel[1] - origin[1]];
532        #[allow(clippy::cast_possible_truncation)]
533        let (x, y) = (origin[0] as i64, origin[1] as i64);
534        let top = self.texel(x, y, component)
535            + (self.texel(x + 1, y, component) - self.texel(x, y, component)) * weight[0];
536        let bottom = self.texel(x, y + 1, component)
537            + (self.texel(x + 1, y + 1, component) - self.texel(x, y + 1, component)) * weight[0];
538        top + (bottom - top) * weight[1]
539    }
540}
541
542/// The transfer functions the presenter evaluates per sample.
543trait Transfer {
544    fn srgb_eotf(value: f32) -> f32;
545    fn pq_eotf(code: f32) -> f32;
546    fn pq_inverse_eotf(nits: f32) -> f32;
547    fn hlg_inverse_oetf(code: f32) -> f32;
548    fn pow(base: f32, exponent: f32) -> f32;
549}
550
551/// The presenter's curves: `libm`-built tables, identical on every target.
552struct Tabled;
553
554impl Transfer for Tabled {
555    #[inline]
556    fn srgb_eotf(value: f32) -> f32 {
557        curves::srgb_to_linear(value.clamp(0.0, 1.0))
558    }
559
560    #[inline]
561    fn pq_eotf(code: f32) -> f32 {
562        curves::pq_eotf(code)
563    }
564
565    #[inline]
566    fn pq_inverse_eotf(nits: f32) -> f32 {
567        curves::pq_inverse_eotf(nits)
568    }
569
570    #[inline]
571    fn hlg_inverse_oetf(code: f32) -> f32 {
572        curves::hlg_inverse_oetf(code)
573    }
574
575    #[inline]
576    fn pow(base: f32, exponent: f32) -> f32 {
577        curves::table_pow(curves::pow_tables(), base, exponent)
578    }
579}
580
581/// The references the tables are built from.
582#[cfg(test)]
583struct Exact;
584
585#[cfg(test)]
586impl Transfer for Exact {
587    fn srgb_eotf(value: f32) -> f32 {
588        curves::exact_srgb_to_linear(value.clamp(0.0, 1.0))
589    }
590
591    fn pq_eotf(code: f32) -> f32 {
592        crate::hdr::pq_eotf(code)
593    }
594
595    fn pq_inverse_eotf(nits: f32) -> f32 {
596        crate::hdr::pq_inverse_eotf(nits)
597    }
598
599    fn hlg_inverse_oetf(code: f32) -> f32 {
600        crate::hdr::hlg_inverse_oetf(code)
601    }
602
603    #[allow(clippy::cast_possible_truncation)]
604    fn pow(base: f32, exponent: f32) -> f32 {
605        libm::pow(f64::from(base), f64::from(exponent)) as f32
606    }
607}
608
609impl YuvConversion {
610    fn bt2390_eetf<T: Transfer>(&self, nits: f32) -> f32 {
611        let source = self.tone[2];
612        let value = T::pq_inverse_eotf(nits.min(self.tone[0])) / source;
613        let max_lum = self.tone[3] / source;
614        let knee = 1.5 * max_lum - 0.5;
615        let mut mapped = value;
616        if value >= knee && knee < 1.0 {
617            let t = (value - knee) / (1.0 - knee);
618            let t2 = t * t;
619            let t3 = t2 * t;
620            mapped = (2.0 * t3 - 3.0 * t2 + 1.0) * knee
621                + (t3 - 2.0 * t2 + t) * (1.0 - knee)
622                + (-2.0 * t3 + 3.0 * t2) * max_lum;
623        }
624        T::pq_eotf(mapped * source)
625    }
626
627    fn to_bt709(&self, rgb: [f32; 3]) -> [f32; 3] {
628        self.gamut
629            .map(|row| row[0] * rgb[0] + row[1] * rgb[1] + row[2] * rgb[2])
630    }
631
632    fn hdr_to_working<T: Transfer>(&self, encoded: [f32; 3]) -> [f32; 3] {
633        let nits = if self.transfer == 2 {
634            let scene = encoded.map(T::hlg_inverse_oetf);
635            let luma = (0.2627 * scene[0] + 0.678 * scene[1] + 0.0593 * scene[2]).max(0.0);
636            let gain = self.tone[0] * T::pow(luma.max(1.0e-10), self.hlg_gamma - 1.0);
637            scene.map(|value| value * gain)
638        } else {
639            encoded.map(T::pq_eotf)
640        };
641        let converted = self.to_bt709(nits);
642        let largest = converted[0].max(converted[1].max(converted[2]));
643        let scale = if largest > 0.0 {
644            self.bt2390_eetf::<T>(largest) / largest
645        } else {
646            0.0
647        };
648        converted.map(|value| (value * scale / self.tone[1]).clamp(0.0, 1.0))
649    }
650
651    /// YCbCr at a luma and chroma position, decoded by range and matrix to sRGB-encoded R'G'B'.
652    fn encoded(&self, planes: &Planes<'_>, luma: [f32; 2], chroma: [f32; 2]) -> [f32; 3] {
653        let u = planes.u.sample(chroma, 0);
654        let v = if self.interleaved {
655            planes.u.sample(chroma, 1)
656        } else {
657            planes
658                .v
659                .as_ref()
660                .map_or(0.0, |plane| plane.sample(chroma, 0))
661        };
662        self.encoded_from([planes.y.sample(luma, 0), u, v])
663    }
664
665    /// Sampled codes decoded by range and matrix to sRGB-encoded R'G'B'.
666    #[inline]
667    fn encoded_from(&self, codes: [f32; 3]) -> [f32; 3] {
668        let yuv = [
669            codes[0] * self.range_scale[0] + self.range_offset[0],
670            codes[1] * self.range_scale[1] + self.range_offset[1],
671            codes[2] * self.range_scale[2] + self.range_offset[2],
672        ];
673        self.rows
674            .map(|row| row[0] * yuv[0] + row[1] * yuv[1] + row[2] * yuv[2])
675    }
676
677    /// `linear_rgb`.
678    fn linear_rgb(&self, planes: &Planes<'_>, luma: [f32; 2], chroma: [f32; 2]) -> [f32; 3] {
679        self.linear_from_encoded(self.encoded(planes, luma, chroma))
680    }
681
682    /// Encoded R'G'B' converted to the linear working space.
683    fn linear_from_encoded(&self, encoded: [f32; 3]) -> [f32; 3] {
684        self.linear_from_encoded_with::<Tabled>(encoded)
685    }
686
687    fn linear_from_encoded_with<T: Transfer>(&self, encoded: [f32; 3]) -> [f32; 3] {
688        if self.transfer != 0 {
689            return self.hdr_to_working::<T>(encoded.map(|value| value.clamp(0.0, 1.0)));
690        }
691        self.to_bt709(encoded.map(T::srgb_eotf))
692            .map(|value| value.clamp(0.0, 1.0))
693    }
694
695    /// `coordinates_at`: luma and chroma positions of `source_pixel`.
696    fn coordinates(&self, source_pixel: [f32; 2]) -> ([f32; 2], [f32; 2]) {
697        let chroma_pixel = [
698            ((source_pixel[0] + self.chroma_offset[0]) * self.chroma_scale[0])
699                .clamp(self.chroma_window[0], self.chroma_window[2]),
700            ((source_pixel[1] + self.chroma_offset[1]) * self.chroma_scale[1])
701                .clamp(self.chroma_window[1], self.chroma_window[3]),
702        ];
703        (
704            [
705                source_pixel[0] / self.geometry.source[0],
706                source_pixel[1] / self.geometry.source[1],
707            ],
708            [
709                chroma_pixel[0] / self.chroma_size[0],
710                chroma_pixel[1] / self.chroma_size[1],
711            ],
712        )
713    }
714
715    fn alpha_at(&self, planes: &Planes<'_>, luma: [f32; 2]) -> f32 {
716        planes.alpha.as_ref().map_or(1.0, |plane| {
717            (plane.sample(luma, 0) * self.alpha_scale).clamp(0.0, 1.0)
718        })
719    }
720
721    /// `premultiplied_linear`: straight alpha premultiplied before filtering.
722    fn premultiplied_linear(&self, planes: &Planes<'_>, source_pixel: [f32; 2]) -> [f32; 4] {
723        let (luma, chroma) = self.coordinates(source_pixel);
724        let texel = [
725            luma[0] * self.geometry.source[0] - 0.5,
726            luma[1] * self.geometry.source[1] - 0.5,
727        ];
728        let origin = [texel[0].floor(), texel[1].floor()];
729        let weight = [texel[0] - origin[0], texel[1] - origin[1]];
730        let first = [self.geometry.visible[0], self.geometry.visible[1]];
731        let last = [
732            first[0] + self.geometry.visible[2] - 1.0,
733            first[1] + self.geometry.visible[3] - 1.0,
734        ];
735        let corner = |dx: f32, dy: f32| {
736            self.coordinates([
737                (origin[0] + dx).clamp(first[0], last[0]) + 0.5,
738                (origin[1] + dy).clamp(first[1], last[1]) + 0.5,
739            ])
740        };
741        let corners = [
742            corner(0.0, 0.0),
743            corner(1.0, 0.0),
744            corner(0.0, 1.0),
745            corner(1.0, 1.0),
746        ];
747        let alphas = corners.map(|(luma, _)| self.alpha_at(planes, luma));
748        if alphas.iter().all(|alpha| *alpha >= 1.0) {
749            let rgb = self.linear_rgb(planes, luma, chroma);
750            return [rgb[0], rgb[1], rgb[2], 1.0];
751        }
752        // Four clear texels mix to zero whatever their color, and zero alpha stores as zero.
753        if alphas.iter().all(|alpha| *alpha <= 0.0) {
754            return [0.0; 4];
755        }
756        let texels: [[f32; 4]; 4] = std::array::from_fn(|index| {
757            let ((luma, chroma), alpha) = (corners[index], alphas[index]);
758            let rgb = self.linear_rgb(planes, luma, chroma);
759            [rgb[0] * alpha, rgb[1] * alpha, rgb[2] * alpha, alpha]
760        });
761        let mix = |a: [f32; 4], b: [f32; 4], t: f32| {
762            [0, 1, 2, 3].map(|channel| a[channel] * (1.0 - t) + b[channel] * t)
763        };
764        mix(
765            mix(texels[0], texels[1], weight[0]),
766            mix(texels[2], texels[3], weight[0]),
767            weight[1],
768        )
769    }
770
771    /// `stored_sample`: one position as the intermediate stores presented sources (sRGB-encoded,
772    /// then premultiplied).
773    fn stored_sample(&self, planes: &Planes<'_>, source_pixel: [f32; 2]) -> [f32; 4] {
774        if !self.alpha_plane {
775            let (luma, chroma) = self.coordinates(source_pixel);
776            return self.stored_opaque(self.encoded(planes, luma, chroma));
777        }
778        Self::stored_linear(self.premultiplied_linear(planes, source_pixel))
779    }
780
781    /// An opaque sample's encoded R'G'B' as stored.
782    #[inline]
783    fn stored_opaque(&self, encoded: [f32; 3]) -> [f32; 4] {
784        if self.encoded_identity {
785            return [
786                encoded[0].clamp(0.0, 1.0),
787                encoded[1].clamp(0.0, 1.0),
788                encoded[2].clamp(0.0, 1.0),
789                1.0,
790            ];
791        }
792        let rgb = self.linear_from_encoded(encoded);
793        Self::stored_linear([rgb[0], rgb[1], rgb[2], 1.0])
794    }
795
796    /// Premultiplied linear light as stored.
797    fn stored_linear(linear: [f32; 4]) -> [f32; 4] {
798        if linear[3] <= 0.0 {
799            return [0.0; 4];
800        }
801        let alpha = linear[3];
802        [
803            encode_srgb(linear[0] / alpha) * alpha,
804            encode_srgb(linear[1] / alpha) * alpha,
805            encode_srgb(linear[2] / alpha) * alpha,
806            alpha,
807        ]
808    }
809}
810
811/// `encode_srgb` of yuv-to-linear.wesl; the input is already clamped.
812fn encode_srgb(value: f32) -> f32 {
813    linear_to_srgb(value)
814}
815
816struct Planes<'a> {
817    y: Plane<'a>,
818    u: Plane<'a>,
819    v: Option<Plane<'a>>,
820    alpha: Option<Plane<'a>>,
821}
822
823impl<'a> Planes<'a> {
824    /// The planes of `frame`, stored as `format` says.
825    fn of(frame: &YuvFrame<'a>, format: YuvFormat) -> Self {
826        fn plane<'a>(
827            source: &SourcePlane<'a>,
828            (width, height): (u32, u32),
829            wide: bool,
830            components: usize,
831        ) -> Plane<'a> {
832            Plane {
833                bytes: source.bytes,
834                stride: source.stride as usize,
835                width,
836                height,
837                wide,
838                components,
839            }
840        }
841        let wide = format.bytes_per_sample() == 2;
842        let (chroma_width, chroma_height) = format.chroma_size(frame.size.width, frame.size.height);
843        Self {
844            y: plane(
845                &frame.planes[0],
846                (frame.size.width, frame.size.height),
847                wide,
848                1,
849            ),
850            u: plane(
851                &frame.planes[1],
852                (chroma_width, chroma_height),
853                wide,
854                if format.interleaved_chroma { 2 } else { 1 },
855            ),
856            v: (!format.interleaved_chroma)
857                .then(|| plane(&frame.planes[2], (chroma_width, chroma_height), wide, 1)),
858            alpha: frame
859                .alpha_plane
860                .as_ref()
861                .map(|alpha| plane(alpha, (frame.size.width, frame.size.height), wide, 1)),
862        }
863    }
864}
865
866/// How `present_yuv` converts: the fastest path that applies, the table path alone, or the
867/// per-pixel shader port the table path must match bit for bit.
868#[derive(Clone, Copy, PartialEq)]
869enum Path {
870    Fastest,
871    #[cfg(test)]
872    Tables,
873    #[cfg(test)]
874    PerPixel,
875}
876
877impl Path {
878    /// Whether the table paths may run.
879    const fn tables(self) -> bool {
880        match self {
881            #[cfg(test)]
882            Self::PerPixel => false,
883            _ => true,
884        }
885    }
886}
887
888fn present_yuv(
889    renderer: &CpuRenderer,
890    frame: &YuvFrame<'_>,
891    conversion: &YuvConversion,
892    path: Path,
893) -> CpuImage {
894    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
895    let output = RenderSize {
896        width: conversion.geometry.output[0] as u32,
897        height: conversion.geometry.output[1] as u32,
898    };
899    if conversion.skipped {
900        return CpuImage::transparent(output);
901    }
902    let planes = Planes::of(frame, conversion.format);
903    if path == Path::Fastest
904        && let Some(image) = present_separable(renderer, output, &planes, conversion)
905    {
906        return image;
907    }
908    if path.tables()
909        && let Some(image) = present_tables(renderer, output, &planes, conversion)
910    {
911        return image;
912    }
913    let geometry = conversion.geometry;
914    let alpha = conversion.alpha;
915    present_rows(renderer, output, &geometry, |destination| {
916        geometry
917            .filtered(destination, |source_pixel| {
918                conversion.stored_sample(&planes, source_pixel)
919            })
920            .map(|value| value * alpha)
921    })
922}
923
924/// Filters each output column between the two vertically filtered texels its tap names.
925fn lerp_into(values: &[f32], taps: &[(usize, usize, f32)], out: &mut [f32]) {
926    for (out, &(first, second, weight)) in out.iter_mut().zip(taps) {
927        let a = values[first];
928        *out = a + (values[second] - a) * weight;
929    }
930}
931
932/// A sample's texels either side and the weight between, along one source axis.
933type Tap = (u32, u32, f32);
934
935/// Where one output column or row reads along the source axis it drives: texels either side and
936/// the weight between, for luma and chroma.
937#[derive(Clone, Copy, Default)]
938struct AxisTap {
939    inside: bool,
940    luma: Tap,
941    chroma: Tap,
942}
943
944/// The texels a bilinear sample at normalized `position` reads along an axis `size` texels long,
945/// clamped to the edge as `Plane::sample` clamps them.
946fn plane_tap(position: f32, size: u32) -> Tap {
947    #[allow(clippy::cast_precision_loss)]
948    let texel = position * size as f32 - 0.5;
949    let floor = texel.floor();
950    let last = i64::from(size) - 1;
951    #[allow(clippy::cast_possible_truncation)]
952    let first = floor as i64;
953    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
954    (
955        first.clamp(0, last) as u32,
956        (first + 1).clamp(0, last) as u32,
957        texel - floor,
958    )
959}
960
961impl YuvConversion {
962    /// Taps of output `destination` along output `axis` (0 = x), using exactly the arithmetic of
963    /// `source_pixel_at`, `coordinates_at` and a bilinear sample, which are separable: each
964    /// output axis drives one source axis.
965    fn axis_tap(&self, axis: usize, destination: f32, planes: &Planes<'_>) -> AxisTap {
966        let geometry = &self.geometry;
967        let source = geometry.source_axis(axis);
968        let source_pixel = geometry.source_coordinate(axis, destination);
969        let chroma_pixel = ((source_pixel + self.chroma_offset[source])
970            * self.chroma_scale[source])
971            .clamp(self.chroma_window[source], self.chroma_window[source + 2]);
972        let (luma_size, chroma_size) = if source == 0 {
973            (planes.y.width, planes.u.width)
974        } else {
975            (planes.y.height, planes.u.height)
976        };
977        AxisTap {
978            inside: geometry.inside_axis(axis, destination),
979            luma: plane_tap(source_pixel / geometry.source[source], luma_size),
980            chroma: plane_tap(chroma_pixel / self.chroma_size[source], chroma_size),
981        }
982    }
983}
984
985impl Plane<'_> {
986    /// Normalized `component` of texel `x` in row `y`.
987    #[inline]
988    fn at(&self, x: u32, y: u32, component: usize) -> f32 {
989        let sample = x as usize * self.components + component;
990        let row = y as usize * self.stride;
991        if self.wide {
992            let offset = row + sample * 2;
993            f32::from(u16::from_le_bytes([
994                self.bytes[offset],
995                self.bytes[offset + 1],
996            ])) / 65535.0
997        } else {
998            half::unorm8_value(self.bytes[row + sample])
999        }
1000    }
1001
1002    /// `component` of texels from `first` in the rows `row` names, filtered between them, into
1003    /// `out`.
1004    fn vertical(&self, row: Tap, first: u32, component: usize, out: &mut [f32]) {
1005        if !self.wide {
1006            let count = out.len();
1007            let line = |y: u32| {
1008                let start = y as usize * self.stride + first as usize * self.components + component;
1009                self.bytes[start..]
1010                    .iter()
1011                    .step_by(self.components)
1012                    .take(count)
1013                    .map(|&code| half::unorm8_value(code))
1014            };
1015            if row.2 == 0.0 {
1016                for (value, top) in out.iter_mut().zip(line(row.0)) {
1017                    *value = top;
1018                }
1019            } else {
1020                for ((value, top), bottom) in out.iter_mut().zip(line(row.0)).zip(line(row.1)) {
1021                    *value = top + (bottom - top) * row.2;
1022                }
1023            }
1024            return;
1025        }
1026        for (offset, value) in out.iter_mut().enumerate() {
1027            #[allow(clippy::cast_possible_truncation)]
1028            let x = first + offset as u32;
1029            let top = self.at(x, row.0, component);
1030            *value = if row.2 == 0.0 {
1031                top
1032            } else {
1033                top + (self.at(x, row.1, component) - top) * row.2
1034            };
1035        }
1036    }
1037}
1038
1039/// Row-wise fast path for an upright or half-turned source with no alpha plane or
1040/// minification: taps are computed once per column and row, planes filtered vertically once
1041/// per output row, then horizontally per pixel. Same taps as the per-pixel path, summed in the
1042/// other order; `None` for other presentations.
1043#[allow(clippy::too_many_lines)]
1044fn present_separable(
1045    renderer: &CpuRenderer,
1046    output: RenderSize,
1047    planes: &Planes<'_>,
1048    conversion: &YuvConversion,
1049) -> Option<CpuImage> {
1050    let geometry = &conversion.geometry;
1051    if conversion.alpha_plane || geometry.orientation & 1 != 0 || {
1052        #[allow(clippy::float_cmp)]
1053        let unfiltered = geometry.filter_grid() == [1.0, 1.0];
1054        !unfiltered
1055    } {
1056        return None;
1057    }
1058    let bounds = geometry.bounds(output);
1059    if bounds.is_empty() {
1060        return Some(CpuImage::transparent(output));
1061    }
1062    #[allow(clippy::cast_precision_loss)]
1063    let columns = (bounds.x..bounds.right())
1064        .map(|x| conversion.axis_tap(0, x as f32 + 0.5, planes))
1065        .collect::<Vec<_>>();
1066    let all_inside = columns.iter().all(|column| column.inside);
1067    // Column taps relative to the first texel of each plane's row.
1068    let (luma_base, chroma_base) = (
1069        columns.iter().map(|tap| tap.luma.0).min().unwrap_or(0),
1070        columns.iter().map(|tap| tap.chroma.0).min().unwrap_or(0),
1071    );
1072    let relative = |(first, second, weight): Tap, base: u32| {
1073        ((first - base) as usize, (second - base) as usize, weight)
1074    };
1075    let luma_taps = columns
1076        .iter()
1077        .map(|tap| relative(tap.luma, luma_base))
1078        .collect::<Vec<_>>();
1079    let chroma_taps = columns
1080        .iter()
1081        .map(|tap| relative(tap.chroma, chroma_base))
1082        .collect::<Vec<_>>();
1083    let alpha = conversion.alpha;
1084    let width = bounds.width as usize;
1085    let reach = |pick: fn(&AxisTap) -> Tap| {
1086        let first = columns.iter().map(|tap| pick(tap).0).min().unwrap_or(0);
1087        let last = columns.iter().map(|tap| pick(tap).1).max().unwrap_or(0);
1088        (first, last)
1089    };
1090    let (luma_first, luma_last) = reach(|tap| tap.luma);
1091    let (chroma_first, chroma_last) = reach(|tap| tap.chroma);
1092    let chroma_len = (chroma_last - chroma_first + 1) as usize;
1093    let scratch = || {
1094        [
1095            vec![0.0_f32; (luma_last - luma_first + 1) as usize],
1096            vec![0.0_f32; chroma_len],
1097            vec![0.0_f32; chroma_len],
1098            vec![0.0_f32; width],
1099            vec![0.0_f32; width],
1100            vec![0.0_f32; width],
1101        ]
1102    };
1103    let mut pixels = renderer.frame_pool.take(bounds.pixels());
1104    renderer
1105        .workers
1106        .bands_with(&mut pixels, width, scratch, |scratch, first_row, band| {
1107            // Filter one output row's planes vertically, then each pixel horizontally.
1108            band.fill([0; 4]);
1109            for buffer in scratch.iter_mut() {
1110                buffer.fill(0.0);
1111            }
1112            let [luma, u, v, sample_y, sample_u, sample_v] =
1113                scratch.each_mut().map(Vec::as_mut_slice);
1114            for (index, line) in band.chunks_mut(width).enumerate() {
1115                #[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
1116                let y = (bounds.y as usize + first_row + index) as f32 + 0.5;
1117                let row = conversion.axis_tap(1, y, planes);
1118                if !row.inside {
1119                    continue;
1120                }
1121                planes.y.vertical(row.luma, luma_first, 0, luma);
1122                planes.u.vertical(row.chroma, chroma_first, 0, u);
1123                if conversion.interleaved {
1124                    planes.u.vertical(row.chroma, chroma_first, 1, v);
1125                } else if let Some(plane) = planes.v.as_ref() {
1126                    plane.vertical(row.chroma, chroma_first, 0, v);
1127                }
1128                let between = |values: &[f32], (first, second, weight): Tap, base: u32| {
1129                    let a = values[(first - base) as usize];
1130                    a + (values[(second - base) as usize] - a) * weight
1131                };
1132                if conversion.encoded_identity && all_inside {
1133                    // Inlined conversion, one pass at a time: samples, then range, matrix and
1134                    // clamp.
1135                    let [scale_y, scale_u, scale_v] = conversion.range_scale;
1136                    let [offset_y, offset_u, offset_v] = conversion.range_offset;
1137                    let [red, green, blue] = conversion.rows;
1138                    let alpha_bits = half::store(alpha);
1139                    lerp_into(luma, &luma_taps, sample_y);
1140                    lerp_into(u, &chroma_taps, sample_u);
1141                    lerp_into(v, &chroma_taps, sample_v);
1142                    for (((out, y), cb), cr) in line
1143                        .iter_mut()
1144                        .zip(sample_y.iter())
1145                        .zip(sample_u.iter())
1146                        .zip(sample_v.iter())
1147                    {
1148                        let y = y * scale_y + offset_y;
1149                        let cb = cb * scale_u + offset_u;
1150                        let cr = cr * scale_v + offset_v;
1151                        let channel = |row: [f32; 3]| {
1152                            half::store(
1153                                (row[0] * y + row[1] * cb + row[2] * cr).clamp(0.0, 1.0) * alpha,
1154                            )
1155                        };
1156                        *out = [channel(red), channel(green), channel(blue), alpha_bits];
1157                    }
1158                    continue;
1159                }
1160                for (out, column) in line.iter_mut().zip(&columns) {
1161                    if !column.inside {
1162                        continue;
1163                    }
1164                    let codes = [
1165                        between(luma, column.luma, luma_first),
1166                        between(u, column.chroma, chroma_first),
1167                        between(v, column.chroma, chroma_first),
1168                    ];
1169                    let stored = conversion.stored_opaque(conversion.encoded_from(codes));
1170                    *out = half::store4(stored.map(|value| value * alpha));
1171                }
1172            }
1173        });
1174    Some(CpuImage::pooled(
1175        output,
1176        bounds,
1177        pixels,
1178        &renderer.frame_pool,
1179    ))
1180}
1181
1182/// Taps of every filter sample of every output position along one output axis.
1183struct AxisTable {
1184    /// Per output position, whether its centre is inside the drawn rectangle.
1185    inside: Vec<bool>,
1186    /// Per output position, one tap per sample in grid order.
1187    taps: Vec<AxisTap>,
1188    samples: usize,
1189}
1190
1191impl AxisTable {
1192    /// `tap` at each of `offsets` from the centre of each position `first..first + count`.
1193    fn new(
1194        geometry: &Geometry,
1195        axis: usize,
1196        (first, count): (u32, u32),
1197        offsets: &[f32],
1198        tap: impl Fn(usize, f32) -> AxisTap,
1199    ) -> Self {
1200        let mut inside = Vec::with_capacity(count as usize);
1201        let mut taps = Vec::with_capacity(count as usize * offsets.len());
1202        for position in first..first + count {
1203            #[allow(clippy::cast_precision_loss)]
1204            let destination = position as f32 + 0.5;
1205            inside.push(geometry.inside_axis(axis, destination));
1206            taps.extend(offsets.iter().map(|offset| tap(axis, destination + offset)));
1207        }
1208        Self {
1209            inside,
1210            taps,
1211            samples: offsets.len(),
1212        }
1213    }
1214
1215    fn at(&self, position: usize) -> &[AxisTap] {
1216        &self.taps[position * self.samples..(position + 1) * self.samples]
1217    }
1218
1219    /// The first and last texel any tap reads, for luma and chroma.
1220    fn reach(&self) -> [(u32, u32); 2] {
1221        let span = |pick: fn(&AxisTap) -> Tap| {
1222            let first = self.taps.iter().map(|tap| pick(tap).0).min().unwrap_or(0);
1223            let last = self.taps.iter().map(|tap| pick(tap).1).max().unwrap_or(0);
1224            (first, last)
1225        };
1226        [span(|tap| tap.luma), span(|tap| tap.chroma)]
1227    }
1228}
1229
1230/// The line of texels a fixed tap selects across the other source axis, decoded once.
1231struct Lines {
1232    /// Texels `first..` of the two lines the tap names (rows when upright, columns when turned).
1233    near: Vec<f32>,
1234    far: Vec<f32>,
1235    first: u32,
1236}
1237
1238impl Lines {
1239    fn new(first: u32, last: u32) -> Self {
1240        let length = (last - first + 1) as usize;
1241        Self {
1242            near: vec![0.0; length],
1243            far: vec![0.0; length],
1244            first,
1245        }
1246    }
1247
1248    /// Decodes rows `tap.0` and `tap.1` of `component`.
1249    fn rows(&mut self, plane: &Plane<'_>, tap: Tap, component: usize) {
1250        for (offset, (near, far)) in self.near.iter_mut().zip(self.far.iter_mut()).enumerate() {
1251            #[allow(clippy::cast_possible_truncation)]
1252            let x = self.first + offset as u32;
1253            *near = plane.at(x, tap.0, component);
1254            *far = plane.at(x, tap.1, component);
1255        }
1256    }
1257
1258    /// Decodes columns `tap.0` and `tap.1` of `component` and lerps between them, as
1259    /// `Plane::sample` lerps horizontally before it lerps vertically.
1260    fn columns(&mut self, plane: &Plane<'_>, tap: Tap, component: usize) {
1261        for (offset, near) in self.near.iter_mut().enumerate() {
1262            #[allow(clippy::cast_possible_truncation)]
1263            let y = self.first + offset as u32;
1264            let left = plane.at(tap.0, y, component);
1265            *near = left + (plane.at(tap.1, y, component) - left) * tap.2;
1266        }
1267    }
1268
1269    /// `Plane::sample` from rows decoded by [`Self::rows`], at column tap `across` and `weight`.
1270    #[inline]
1271    fn between_rows(&self, across: Tap, weight: f32) -> f32 {
1272        let (left, right) = (
1273            (across.0 - self.first) as usize,
1274            (across.1 - self.first) as usize,
1275        );
1276        let top = self.near[left] + (self.near[right] - self.near[left]) * across.2;
1277        let bottom = self.far[left] + (self.far[right] - self.far[left]) * across.2;
1278        top + (bottom - top) * weight
1279    }
1280
1281    /// `Plane::sample` from columns lerped by [`Self::columns`], at row tap `across`.
1282    #[inline]
1283    fn between_columns(&self, across: Tap) -> f32 {
1284        let (top, bottom) = (
1285            (across.0 - self.first) as usize,
1286            (across.1 - self.first) as usize,
1287        );
1288        let top_value = self.near[top];
1289        top_value + (self.near[bottom] - top_value) * across.2
1290    }
1291}
1292
1293/// Table path for the presentations `present_separable` declines, except alpha planes:
1294/// quarter turns and minification. Each output axis drives one source axis, so one table per
1295/// output axis holds every sample's taps; for each output row and filter row the two source
1296/// lines it reads are decoded once. Every sample is evaluated in the per-pixel path's order
1297/// (horizontal lerp, vertical lerp, conversion, grid sum), so the bits are the same.
1298#[allow(clippy::too_many_lines)]
1299fn present_tables(
1300    renderer: &CpuRenderer,
1301    output: RenderSize,
1302    planes: &Planes<'_>,
1303    conversion: &YuvConversion,
1304) -> Option<CpuImage> {
1305    if conversion.alpha_plane {
1306        return None;
1307    }
1308    let geometry = &conversion.geometry;
1309    let bounds = geometry.bounds(output);
1310    if bounds.is_empty() {
1311        return Some(CpuImage::transparent(output));
1312    }
1313    let grid = geometry.filter_grid();
1314    #[allow(clippy::float_cmp)]
1315    let single = grid == [1.0, 1.0];
1316    let count = grid[0] * grid[1];
1317    let tap = |axis, destination| conversion.axis_tap(axis, destination, planes);
1318    let columns = AxisTable::new(
1319        geometry,
1320        0,
1321        (bounds.x, bounds.width),
1322        &Geometry::grid_offsets(grid, 0),
1323        tap,
1324    );
1325    let rows = AxisTable::new(
1326        geometry,
1327        1,
1328        (bounds.y, bounds.height),
1329        &Geometry::grid_offsets(grid, 1),
1330        tap,
1331    );
1332    // Upright and half-turned rows fix a source row pair; quarter-turned rows fix a column pair.
1333    let turned = geometry.source_axis(1) == 0;
1334    let [(luma_first, luma_last), (chroma_first, chroma_last)] = columns.reach();
1335    let alpha = conversion.alpha;
1336    let width = bounds.width as usize;
1337    let scratch = || {
1338        (
1339            [
1340                Lines::new(luma_first, luma_last),
1341                Lines::new(chroma_first, chroma_last),
1342                Lines::new(chroma_first, chroma_last),
1343            ],
1344            vec![[0.0_f32; 4]; width],
1345        )
1346    };
1347    let mut pixels = renderer.frame_pool.take(bounds.pixels());
1348    renderer.workers.bands_with(
1349        &mut pixels,
1350        width,
1351        scratch,
1352        |([luma, u, v], sums), first_row, band| {
1353            band.fill([0; 4]);
1354            for (index, line) in band.chunks_mut(width).enumerate() {
1355                let row = first_row + index;
1356                if !rows.inside[row] {
1357                    continue;
1358                }
1359                sums.fill([0.0; 4]);
1360                for row_tap in rows.at(row) {
1361                    if turned {
1362                        luma.columns(&planes.y, row_tap.luma, 0);
1363                        u.columns(&planes.u, row_tap.chroma, 0);
1364                    } else {
1365                        luma.rows(&planes.y, row_tap.luma, 0);
1366                        u.rows(&planes.u, row_tap.chroma, 0);
1367                    }
1368                    let v_plane = if conversion.interleaved {
1369                        Some((&planes.u, 1))
1370                    } else {
1371                        planes.v.as_ref().map(|plane| (plane, 0))
1372                    };
1373                    if let Some((plane, component)) = v_plane {
1374                        if turned {
1375                            v.columns(plane, row_tap.chroma, component);
1376                        } else {
1377                            v.rows(plane, row_tap.chroma, component);
1378                        }
1379                    }
1380                    for (offset, (out, sum)) in line.iter_mut().zip(sums.iter_mut()).enumerate() {
1381                        if !columns.inside[offset] {
1382                            continue;
1383                        }
1384                        for column_tap in columns.at(offset) {
1385                            let sample = |lines: &Lines, across: Tap, weight: f32| {
1386                                if turned {
1387                                    lines.between_columns(across)
1388                                } else {
1389                                    lines.between_rows(across, weight)
1390                                }
1391                            };
1392                            let codes = [
1393                                sample(luma, column_tap.luma, row_tap.luma.2),
1394                                sample(u, column_tap.chroma, row_tap.chroma.2),
1395                                if v_plane.is_some() {
1396                                    sample(v, column_tap.chroma, row_tap.chroma.2)
1397                                } else {
1398                                    0.0
1399                                },
1400                            ];
1401                            let value = conversion.stored_opaque(conversion.encoded_from(codes));
1402                            if single {
1403                                *out = half::store4(value.map(|channel| channel * alpha));
1404                            } else {
1405                                for (total, channel) in sum.iter_mut().zip(value) {
1406                                    *total += channel;
1407                                }
1408                            }
1409                        }
1410                    }
1411                }
1412                if !single {
1413                    for (offset, (out, sum)) in line.iter_mut().zip(sums.iter()).enumerate() {
1414                        if columns.inside[offset] {
1415                            *out = half::store4(sum.map(|total| total / count * alpha));
1416                        }
1417                    }
1418                }
1419            }
1420        },
1421    );
1422    Some(CpuImage::pooled(
1423        output,
1424        bounds,
1425        pixels,
1426        &renderer.frame_pool,
1427    ))
1428}
1429
1430struct RgbaSource<'a> {
1431    bytes: &'a [u8],
1432    stride: usize,
1433    size: RenderSize,
1434    encoding: PresentedEncoding,
1435}
1436
1437impl RgbaSource<'_> {
1438    /// Texel at `(x, y)` with edge repeat: 8-bit codes, or half floats for linear sources.
1439    fn texel(&self, x: i64, y: i64) -> [f32; 4] {
1440        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
1441        let (x, y) = (
1442            x.clamp(0, i64::from(self.size.width) - 1) as usize,
1443            y.clamp(0, i64::from(self.size.height) - 1) as usize,
1444        );
1445        if self.encoding == PresentedEncoding::Linear {
1446            let offset = y * self.stride + x * 8;
1447            std::array::from_fn(|channel| {
1448                half::load(u16::from_le_bytes([
1449                    self.bytes[offset + channel * 2],
1450                    self.bytes[offset + channel * 2 + 1],
1451                ]))
1452            })
1453        } else {
1454            let offset = y * self.stride + x * 4;
1455            std::array::from_fn(|channel| half::unorm8_value(self.bytes[offset + channel]))
1456        }
1457    }
1458
1459    /// `filtered_sample` of rgba-present.wesl: bilinear premultiplied color in the filtering space.
1460    fn filtered_sample(&self, source_pixel: [f32; 2]) -> [f32; 4] {
1461        let texel = [source_pixel[0] - 0.5, source_pixel[1] - 0.5];
1462        let origin = [texel[0].floor(), texel[1].floor()];
1463        let weight = [texel[0] - origin[0], texel[1] - origin[1]];
1464        #[allow(clippy::cast_possible_truncation)]
1465        let (x, y) = (origin[0] as i64, origin[1] as i64);
1466        let corners = [
1467            self.texel(x, y),
1468            self.texel(x + 1, y),
1469            self.texel(x, y + 1),
1470            self.texel(x + 1, y + 1),
1471        ];
1472        self.filtered_corners(&corners, weight)
1473    }
1474
1475    /// The texels a bilinear sample at source coordinate `position` reads along an axis `size`
1476    /// texels long, clamped as [`Self::texel`] clamps them.
1477    fn axis_tap(position: f32, size: u32) -> Tap {
1478        let texel = position - 0.5;
1479        let floor = texel.floor();
1480        let last = i64::from(size) - 1;
1481        #[allow(clippy::cast_possible_truncation)]
1482        let first = floor as i64;
1483        #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
1484        (
1485            first.clamp(0, last) as u32,
1486            (first + 1).clamp(0, last) as u32,
1487            texel - floor,
1488        )
1489    }
1490
1491    /// `filtered_sample` from its four texels (left to right, then top to bottom) and weights.
1492    #[inline]
1493    fn filtered_corners(&self, corners: &[[f32; 4]; 4], weight: [f32; 2]) -> [f32; 4] {
1494        let mix = |a: [f32; 4], b: [f32; 4], t: f32| {
1495            [0, 1, 2, 3].map(|channel| a[channel] + (b[channel] - a[channel]) * t)
1496        };
1497        let bilinear = |texels: &[[f32; 4]; 4]| {
1498            mix(
1499                mix(texels[0], texels[1], weight[0]),
1500                mix(texels[2], texels[3], weight[0]),
1501                weight[1],
1502            )
1503        };
1504        if self.encoding != PresentedEncoding::Srgb(SourceAlpha::Straight) {
1505            return bilinear(corners);
1506        }
1507        // Straight alpha is premultiplied before filtering.
1508        let premultiplied = corners.map(|texel| {
1509            [
1510                texel[0] * texel[3],
1511                texel[1] * texel[3],
1512                texel[2] * texel[3],
1513                texel[3],
1514            ]
1515        });
1516        if premultiplied.iter().all(|texel| texel[3] >= 1.0) {
1517            let source = bilinear(corners);
1518            return [
1519                source[0] * source[3],
1520                source[1] * source[3],
1521                source[2] * source[3],
1522                source[3],
1523            ];
1524        }
1525        bilinear(&premultiplied)
1526    }
1527
1528    /// `stored_sample`.
1529    fn stored_sample(&self, source_pixel: [f32; 2]) -> [f32; 4] {
1530        self.stored(self.filtered_sample(source_pixel))
1531    }
1532
1533    /// A filtered sample as stored.
1534    #[inline]
1535    fn stored(&self, filtered: [f32; 4]) -> [f32; 4] {
1536        if self.encoding != PresentedEncoding::Linear {
1537            return filtered;
1538        }
1539        if filtered[3] <= 0.0 {
1540            return [0.0; 4];
1541        }
1542        let alpha = filtered[3];
1543        [
1544            extended_linear_to_srgb(filtered[0] / alpha) * alpha,
1545            extended_linear_to_srgb(filtered[1] / alpha) * alpha,
1546            extended_linear_to_srgb(filtered[2] / alpha) * alpha,
1547            alpha,
1548        ]
1549    }
1550}
1551
1552fn present_rgba(
1553    renderer: &CpuRenderer,
1554    source: &RgbaSource<'_>,
1555    geometry: &Geometry,
1556    path: Path,
1557) -> CpuImage {
1558    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
1559    let output = RenderSize {
1560        width: geometry.output[0] as u32,
1561        height: geometry.output[1] as u32,
1562    };
1563    if path.tables() {
1564        return present_rgba_tables(renderer, output, source, geometry);
1565    }
1566    present_rows(renderer, output, geometry, |destination| {
1567        geometry.filtered(destination, |source_pixel| {
1568            source.stored_sample(source_pixel)
1569        })
1570    })
1571}
1572
1573/// Two lines of RGBA texels a fixed tap selects across the other source axis.
1574struct RgbaLines {
1575    near: Vec<[f32; 4]>,
1576    far: Vec<[f32; 4]>,
1577    first: u32,
1578}
1579
1580/// [`present_tables`] for RGBA sources: the same tables, with each sample's four texels read from
1581/// two decoded lines and filtered by `filtered_sample`'s own arithmetic.
1582#[allow(clippy::too_many_lines)]
1583fn present_rgba_tables(
1584    renderer: &CpuRenderer,
1585    output: RenderSize,
1586    source: &RgbaSource<'_>,
1587    geometry: &Geometry,
1588) -> CpuImage {
1589    let bounds = geometry.bounds(output);
1590    if bounds.is_empty() {
1591        return CpuImage::transparent(output);
1592    }
1593    let grid = geometry.filter_grid();
1594    #[allow(clippy::float_cmp)]
1595    let single = grid == [1.0, 1.0];
1596    let count = grid[0] * grid[1];
1597    let tap = |axis, destination| {
1598        let source_axis = geometry.source_axis(axis);
1599        let size = if source_axis == 0 {
1600            source.size.width
1601        } else {
1602            source.size.height
1603        };
1604        let taps = RgbaSource::axis_tap(geometry.source_coordinate(axis, destination), size);
1605        AxisTap {
1606            inside: geometry.inside_axis(axis, destination),
1607            luma: taps,
1608            chroma: taps,
1609        }
1610    };
1611    let columns = AxisTable::new(
1612        geometry,
1613        0,
1614        (bounds.x, bounds.width),
1615        &Geometry::grid_offsets(grid, 0),
1616        tap,
1617    );
1618    let rows = AxisTable::new(
1619        geometry,
1620        1,
1621        (bounds.y, bounds.height),
1622        &Geometry::grid_offsets(grid, 1),
1623        tap,
1624    );
1625    let turned = geometry.source_axis(1) == 0;
1626    let [(first, last), _] = columns.reach();
1627    let width = bounds.width as usize;
1628    let scratch = || {
1629        let length = (last - first + 1) as usize;
1630        (
1631            RgbaLines {
1632                near: vec![[0.0; 4]; length],
1633                far: vec![[0.0; 4]; length],
1634                first,
1635            },
1636            vec![[0.0_f32; 4]; width],
1637        )
1638    };
1639    let mut pixels = renderer.frame_pool.take(bounds.pixels());
1640    renderer.workers.bands_with(
1641        &mut pixels,
1642        width,
1643        scratch,
1644        |(lines, sums), first_row, band| {
1645            band.fill([0; 4]);
1646            for (index, line) in band.chunks_mut(width).enumerate() {
1647                let row = first_row + index;
1648                if !rows.inside[row] {
1649                    continue;
1650                }
1651                sums.fill([0.0; 4]);
1652                for row_tap in rows.at(row) {
1653                    let fixed = row_tap.luma;
1654                    for (offset, (near, far)) in
1655                        lines.near.iter_mut().zip(lines.far.iter_mut()).enumerate()
1656                    {
1657                        #[allow(clippy::cast_possible_truncation)]
1658                        let along = i64::from(lines.first + offset as u32);
1659                        let (a, b) = (i64::from(fixed.0), i64::from(fixed.1));
1660                        (*near, *far) = if turned {
1661                            (source.texel(a, along), source.texel(b, along))
1662                        } else {
1663                            (source.texel(along, a), source.texel(along, b))
1664                        };
1665                    }
1666                    for (offset, (out, sum)) in line.iter_mut().zip(sums.iter_mut()).enumerate() {
1667                        if !columns.inside[offset] {
1668                            continue;
1669                        }
1670                        for column_tap in columns.at(offset) {
1671                            let across = column_tap.luma;
1672                            let (low, high) = (
1673                                (across.0 - lines.first) as usize,
1674                                (across.1 - lines.first) as usize,
1675                            );
1676                            // Corners left to right, then top to bottom, and the x and y weights.
1677                            let (corners, weight) = if turned {
1678                                (
1679                                    [
1680                                        lines.near[low],
1681                                        lines.far[low],
1682                                        lines.near[high],
1683                                        lines.far[high],
1684                                    ],
1685                                    [fixed.2, across.2],
1686                                )
1687                            } else {
1688                                (
1689                                    [
1690                                        lines.near[low],
1691                                        lines.near[high],
1692                                        lines.far[low],
1693                                        lines.far[high],
1694                                    ],
1695                                    [across.2, fixed.2],
1696                                )
1697                            };
1698                            let value = source.stored(source.filtered_corners(&corners, weight));
1699                            if single {
1700                                *out = half::store4(value);
1701                            } else {
1702                                for (total, channel) in sum.iter_mut().zip(value) {
1703                                    *total += channel;
1704                                }
1705                            }
1706                        }
1707                    }
1708                }
1709                if !single {
1710                    for (offset, (out, sum)) in line.iter_mut().zip(sums.iter()).enumerate() {
1711                        if columns.inside[offset] {
1712                            *out = half::store4(sum.map(|total| total / count));
1713                        }
1714                    }
1715                }
1716            }
1717        },
1718    );
1719    CpuImage::pooled(output, bounds, pixels, &renderer.frame_pool)
1720}
1721
1722impl CpuRenderer {
1723    /// A source showing decoded YCbCr `planes` placed by `presentation`, converted on first draw;
1724    /// the CPU counterpart of [`crate::Renderer::prepare_yuv_presented`].
1725    ///
1726    /// # Errors
1727    /// [`RenderError::InvalidImageData`] for an unsupported format or short planes, and
1728    /// [`RenderError::UnsupportedHdr`] when [`ColorPolicy::RejectHdr`] meets an HDR source.
1729    pub fn present_yuv(
1730        &self,
1731        planes: Arc<dyn YuvPlanes>,
1732        presentation: SourcePresentation,
1733        policy: ColorPolicy,
1734    ) -> Result<(CpuSource, Vec<ColorDiagnostic>), RenderError> {
1735        let frame = planes.frame();
1736        let mut diagnostics = Vec::new();
1737        let color = frame.color.unwrap_or_else(|| {
1738            diagnostics.push(ColorDiagnostic::MissingMetadataFallback);
1739            ColorMetadata::UNDECLARED
1740        });
1741        let tone: Option<HdrToneMap> = match hdr_handling(color, policy, &mut diagnostics)? {
1742            HdrHandling::Sdr => None,
1743            HdrHandling::ToneMap(tone) => Some(tone),
1744            HdrHandling::Skip => {
1745                return Ok((
1746                    CpuSource::image(Arc::new(CpuImage::transparent(presentation.output_size))),
1747                    diagnostics,
1748                ));
1749            }
1750        };
1751        let format = frame.format;
1752        if !frame.alpha.is_finite()
1753            || !(0.0..=1.0).contains(&frame.alpha)
1754            || !format.is_supported()
1755            || format.alpha != frame.alpha_plane.is_some()
1756        {
1757            return Err(RenderError::InvalidImageData);
1758        }
1759        validate_presentation(frame.size, presentation)?;
1760        let (chroma_width, chroma_height) = format.chroma_size(frame.size.width, frame.size.height);
1761        let pairs = if format.interleaved_chroma { 2 } else { 1 };
1762        let specs = [
1763            (frame.size.width, frame.size.height, 1_u32),
1764            (chroma_width, chroma_height, pairs),
1765            (chroma_width, chroma_height, 1),
1766        ];
1767        for (plane, (width, height, samples)) in frame
1768            .planes
1769            .iter()
1770            .zip(specs)
1771            .take(format.color_plane_count())
1772            .chain(
1773                frame
1774                    .alpha_plane
1775                    .iter()
1776                    .map(|plane| (plane, (frame.size.width, frame.size.height, 1))),
1777            )
1778        {
1779            let row_bytes = width
1780                .checked_mul(samples)
1781                .and_then(|row| row.checked_mul(format.bytes_per_sample()))
1782                .ok_or(RenderError::InvalidImageData)?;
1783            crate::yuv::validate_plane(plane.bytes, plane.stride, row_bytes, height)?;
1784        }
1785        let storage = if format.bytes_per_sample() == 1 {
1786            PlaneStorage::Unorm8
1787        } else {
1788            PlaneStorage::Unorm16
1789        };
1790        #[allow(clippy::cast_precision_loss)]
1791        let bytes = uniform_bytes(
1792            color,
1793            tone,
1794            frame.alpha,
1795            frame.size,
1796            presentation,
1797            format,
1798            storage.code_scale(format),
1799            self.quality_controls().max_filter_samples as f32,
1800        );
1801        let conversion = Box::new(YuvConversion::from_uniform(&bytes, format));
1802        Ok((
1803            CpuSource::new(Content::Yuv { planes, conversion }),
1804            diagnostics,
1805        ))
1806    }
1807
1808    /// A source showing RGBA8 `pixels` placed by `presentation`; the CPU counterpart of
1809    /// [`crate::Renderer::prepare_rgba_presented`]. A zero `stride` means packed rows.
1810    ///
1811    /// # Errors
1812    /// [`RenderError::InvalidImageData`] for short pixels or an invalid presentation.
1813    pub fn present_rgba8(
1814        &self,
1815        pixels: Arc<dyn RgbaPixels>,
1816        size: RenderSize,
1817        stride: u32,
1818        presentation: SourcePresentation,
1819        alpha: SourceAlpha,
1820    ) -> Result<CpuSource, RenderError> {
1821        self.present_rgba(
1822            pixels,
1823            size,
1824            stride,
1825            4,
1826            presentation,
1827            PresentedEncoding::Srgb(alpha),
1828        )
1829    }
1830
1831    /// A source showing premultiplied linear BT.709 RGBA half-float bits (`1.0` = SDR white); the
1832    /// CPU counterpart of [`crate::Renderer::prepare_linear_presented`]. A zero `stride` means
1833    /// packed rows.
1834    ///
1835    /// # Errors
1836    /// [`RenderError::InvalidImageData`] for short pixels or an invalid presentation.
1837    pub fn present_linear_rgba16f(
1838        &self,
1839        pixels: Arc<dyn RgbaPixels>,
1840        size: RenderSize,
1841        stride: u32,
1842        presentation: SourcePresentation,
1843    ) -> Result<CpuSource, RenderError> {
1844        self.present_rgba(
1845            pixels,
1846            size,
1847            stride,
1848            8,
1849            presentation,
1850            PresentedEncoding::Linear,
1851        )
1852    }
1853
1854    fn present_rgba(
1855        &self,
1856        pixels: Arc<dyn RgbaPixels>,
1857        size: RenderSize,
1858        stride: u32,
1859        bytes_per_pixel: u32,
1860        presentation: SourcePresentation,
1861        encoding: PresentedEncoding,
1862    ) -> Result<CpuSource, RenderError> {
1863        validate_presentation(size, presentation)?;
1864        let row_bytes = size
1865            .width
1866            .checked_mul(bytes_per_pixel)
1867            .ok_or(RenderError::InvalidImageData)?;
1868        let stride = if stride == 0 { row_bytes } else { stride };
1869        crate::yuv::validate_plane(pixels.plane().bytes, stride, row_bytes, size.height)?;
1870        #[allow(clippy::cast_precision_loss)]
1871        let bytes = presentation_uniform_bytes(
1872            size,
1873            presentation,
1874            encoding,
1875            self.quality_controls().max_filter_samples as f32,
1876        );
1877        Ok(CpuSource::new(Content::Rgba {
1878            pixels,
1879            stride,
1880            size,
1881            geometry: Geometry::from_uniform(&bytes),
1882            encoding,
1883        }))
1884    }
1885}
1886
1887#[cfg(test)]
1888mod tests {
1889    use alpha2_media::{
1890        ColorMatrix, ColorMetadata, ColorPrimaries, ColorRange, DynamicRange, TransferFunction,
1891        YuvFormat,
1892    };
1893
1894    use super::{Exact, Planes, Tabled, Transfer, YuvConversion, half};
1895    use crate::hdr::HdrToneMap;
1896    use crate::yuv::{PlaneStorage, uniform_bytes};
1897    use crate::{RenderSize, SourcePlane, SourcePresentation, YuvFrame};
1898
1899    fn conversion(
1900        primaries: ColorPrimaries,
1901        transfer: TransferFunction,
1902        peak: u32,
1903    ) -> YuvConversion {
1904        let hdr = matches!(transfer, TransferFunction::Pq | TransferFunction::Hlg);
1905        let color = ColorMetadata {
1906            primaries,
1907            transfer,
1908            matrix: ColorMatrix::Bt2020Ncl,
1909            range: ColorRange::Limited,
1910            dynamic_range: if hdr {
1911                DynamicRange::Hdr
1912            } else {
1913                DynamicRange::Sdr
1914            },
1915        };
1916        let size = RenderSize::new(16, 16).expect("size");
1917        let format = YuvFormat::P010;
1918        let bytes = uniform_bytes(
1919            color,
1920            hdr.then_some(HdrToneMap {
1921                source_peak_nits: peak,
1922            }),
1923            1.0,
1924            size,
1925            SourcePresentation::identity(size),
1926            format,
1927            PlaneStorage::Unorm16.code_scale(format),
1928            64.0,
1929        );
1930        YuvConversion::from_uniform(&bytes, format)
1931    }
1932
1933    /// The stored value of encoded R'G'B' `encoded` with the curves of `T`.
1934    fn stored<T: Transfer>(conversion: &YuvConversion, encoded: [f32; 3]) -> [f32; 4] {
1935        let rgb = conversion.linear_from_encoded_with::<T>(encoded);
1936        YuvConversion::stored_linear([rgb[0], rgb[1], rgb[2], 1.0])
1937    }
1938
1939    /// One half-float step at `value`'s magnitude.
1940    fn half_step(value: f32) -> f32 {
1941        let exponent = (half::store(value.abs()) >> 10) & 0x1f;
1942        libm::exp2f(f32::from(exponent.max(1)) - 25.0)
1943    }
1944
1945    #[test]
1946    fn the_presentation_tables_stay_far_below_a_half_float_step() {
1947        let cases = [
1948            (ColorPrimaries::Bt2020, TransferFunction::Pq, 1_000),
1949            (ColorPrimaries::Bt2020, TransferFunction::Pq, 4_000),
1950            (ColorPrimaries::Bt2020, TransferFunction::Hlg, 1_000),
1951            (ColorPrimaries::Bt2020, TransferFunction::Hlg, 400),
1952            (ColorPrimaries::Bt2020, TransferFunction::Bt709, 0),
1953            (ColorPrimaries::Bt601, TransferFunction::Bt709, 0),
1954        ];
1955        let mut state = 0x9e37_79b9_u32;
1956        for (primaries, transfer, peak) in cases {
1957            let conversion = conversion(primaries, transfer, peak);
1958            let (mut worst, mut worst_raw) = (0.0_f32, 0.0_f32);
1959            let (mut changed, mut values) = (0_u32, 0_u32);
1960            // Every 10-bit grey, then random 10-bit colors.
1961            let codes = (0..1024_u32)
1962                .map(|code| [code; 3])
1963                .chain((0..200_000).map(|_| {
1964                    [0; 3].map(|_| {
1965                        state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
1966                        state >> 22
1967                    })
1968                }));
1969            for code in codes {
1970                #[allow(clippy::cast_precision_loss)]
1971                let encoded = code.map(|code| code as f32 / 1023.0);
1972                let exact = stored::<Exact>(&conversion, encoded);
1973                let tabled = stored::<Tabled>(&conversion, encoded);
1974                let brightest = exact[0].max(exact[1]).max(exact[2]);
1975                for (exact, tabled) in exact.iter().zip(tabled) {
1976                    let error = (tabled - exact).abs();
1977                    worst = worst.max(error / half_step(exact.max(brightest)));
1978                    worst_raw = worst_raw.max(error / half_step(*exact));
1979                    changed += u32::from(half::store(tabled) != half::store(*exact));
1980                    values += 1;
1981                }
1982            }
1983            println!(
1984                "{transfer:?} {primaries:?} peak {peak}: worst {worst:.4} half steps of the \
1985                 brightest channel, {worst_raw:.4} of the channel, {changed} of {values} \
1986                 stored values differ"
1987            );
1988            assert!(worst < 0.05, "{transfer:?} {primaries:?} {peak}: {worst}");
1989        }
1990    }
1991
1992    /// `premultiplied_linear` without its early return for transparent neighbourhoods.
1993    fn premultiplied_linear_reference(
1994        conversion: &YuvConversion,
1995        planes: &Planes<'_>,
1996        source_pixel: [f32; 2],
1997    ) -> [f32; 4] {
1998        let (luma, chroma) = conversion.coordinates(source_pixel);
1999        let geometry = &conversion.geometry;
2000        let texel = [
2001            luma[0] * geometry.source[0] - 0.5,
2002            luma[1] * geometry.source[1] - 0.5,
2003        ];
2004        let origin = [texel[0].floor(), texel[1].floor()];
2005        let weight = [texel[0] - origin[0], texel[1] - origin[1]];
2006        let first = [geometry.visible[0], geometry.visible[1]];
2007        let last = [
2008            first[0] + geometry.visible[2] - 1.0,
2009            first[1] + geometry.visible[3] - 1.0,
2010        ];
2011        let corner = |dx: f32, dy: f32| {
2012            conversion.coordinates([
2013                (origin[0] + dx).clamp(first[0], last[0]) + 0.5,
2014                (origin[1] + dy).clamp(first[1], last[1]) + 0.5,
2015            ])
2016        };
2017        let corners = [
2018            corner(0.0, 0.0),
2019            corner(1.0, 0.0),
2020            corner(0.0, 1.0),
2021            corner(1.0, 1.0),
2022        ];
2023        let alphas = corners.map(|(luma, _)| conversion.alpha_at(planes, luma));
2024        if alphas.iter().all(|alpha| *alpha >= 1.0) {
2025            let rgb = conversion.linear_rgb(planes, luma, chroma);
2026            return [rgb[0], rgb[1], rgb[2], 1.0];
2027        }
2028        let texels: Vec<[f32; 4]> = corners
2029            .iter()
2030            .zip(alphas)
2031            .map(|((luma, chroma), alpha)| {
2032                let rgb = conversion.linear_rgb(planes, *luma, *chroma);
2033                [rgb[0] * alpha, rgb[1] * alpha, rgb[2] * alpha, alpha]
2034            })
2035            .collect();
2036        let mix = |a: [f32; 4], b: [f32; 4], t: f32| {
2037            [0, 1, 2, 3].map(|channel| a[channel] * (1.0 - t) + b[channel] * t)
2038        };
2039        mix(
2040            mix(texels[0], texels[1], weight[0]),
2041            mix(texels[2], texels[3], weight[0]),
2042            weight[1],
2043        )
2044    }
2045
2046    #[test]
2047    fn alpha_plane_samples_keep_their_bits_without_the_clear_ones() {
2048        let (width, height) = (48_u32, 32_u32);
2049        let format = YuvFormat::I420.with_alpha();
2050        #[allow(clippy::cast_possible_truncation)]
2051        let ramp = |count: u32, step: u32| (0..count).map(|index| (index * step) as u8).collect();
2052        let luma: Vec<u8> = ramp(width * height, 7);
2053        let u: Vec<u8> = ramp(width * height / 4, 3);
2054        let v: Vec<u8> = ramp(width * height / 4, 5);
2055        // Clear, then a soft edge, then opaque, across the frame.
2056        #[allow(clippy::cast_possible_truncation)]
2057        let alpha = (0..width * height)
2058            .map(|index| ((index % width).saturating_sub(16) * 16).min(255) as u8)
2059            .collect::<Vec<u8>>();
2060        let plane = |bytes, stride| SourcePlane { bytes, stride };
2061        let size = RenderSize::new(width, height).expect("size");
2062        let frame = YuvFrame {
2063            format,
2064            planes: [
2065                plane(&luma, width),
2066                plane(&u, width / 2),
2067                plane(&v, width / 2),
2068            ],
2069            alpha_plane: Some(plane(&alpha, width)),
2070            size,
2071            alpha: 1.0,
2072            color: Some(ColorMetadata::EXPORT),
2073        };
2074        let bytes = uniform_bytes(
2075            ColorMetadata::EXPORT,
2076            None,
2077            1.0,
2078            size,
2079            SourcePresentation::identity(size),
2080            format,
2081            PlaneStorage::Unorm8.code_scale(format),
2082            64.0,
2083        );
2084        let conversion = YuvConversion::from_uniform(&bytes, format);
2085        let planes = Planes::of(&frame, format);
2086        let (mut clear, mut soft) = (0, 0);
2087        #[allow(clippy::cast_precision_loss)]
2088        for step in 0..(width * 3) * (height * 3) {
2089            let source_pixel = [
2090                (step % (width * 3)) as f32 / 3.0 + 0.17,
2091                (step / (width * 3)) as f32 / 3.0 + 0.11,
2092            ];
2093            let new = conversion.premultiplied_linear(&planes, source_pixel);
2094            let old = premultiplied_linear_reference(&conversion, &planes, source_pixel);
2095            assert_eq!(
2096                new.map(f32::to_bits),
2097                old.map(f32::to_bits),
2098                "{source_pixel:?}"
2099            );
2100            clear += usize::from(new[3] == 0.0);
2101            soft += usize::from(new[3] > 0.0 && new[3] < 1.0);
2102        }
2103        assert!(clear > 0 && soft > 0, "{clear} clear, {soft} soft samples");
2104    }
2105}