rp_cvideo_core/

config.rs

#![allow(clippy::neg_cmp_op_on_partial_ord)]

#[cfg(test)]
#[path = "../test/test_config_from_constraints.rs"]
mod test_constraints;

use crate::buffer::Buffer;
use crate::buffer_preparation::{LabelAddresses, prepare_buffer};
use crate::display_buffer::{DisplayBuffer, NoFields, OneField, TwoFields};
use crate::signal_description::{
    INTERLACED_PATTERN, PROGRESSIVE_PATTERN, SignalDescription, SignalSection, sync_lines_count,
};
use const_soft_float::soft_f64::SoftF64 as SF;
use core::marker::PhantomData;
use defmt::Format;

// Based on the size of the delay field in PIO instructions
const MAX_PIXEL_CLOCK_CYCLES: u16 = 15; // In number of PIO clock cycles

type Result<T> = core::result::Result<T, &'static str>;

// Like assert, but makes you return an Err instead of panicking
macro_rules! blyat {
    ($expression:expr, $msg:literal) => {
        if !$expression {
            return Result::Err($msg);
        }
    };
}

// Macro that mimics the ? operator's functionality, but const compatible
macro_rules! blin {
    ($option:expr) => {
        match $option {
            Ok(x) => x,
            Err(err) => {
                return Err(err);
            }
        }
    };
}

#[allow(missing_docs)]
#[derive(Copy, Clone, Debug, Format)]
pub enum BufferingMode {
    /// There will be only one DisplayBuffer which can be drawn on while the vertical-sync portion
    /// is being streamed
    SingleBuffered,

    /// There will be two full frames. You can draw on one, while the other one is being streamed.
    /// After commiting a frame and waiting for the previous one to be finished, you get it back.
    ///
    /// Commited buffers will not be modified, so in case of double buffering, the buffer you get back
    /// does not have the contents of the one you commited last.
    DoubleBuffered,

    /// A special blend of double-buffering which can only be combined with interlaced video.
    ///
    /// With this option, you get to always have one buffer to draw one, but it contains only one field
    /// of the interlaced buffer, instead of a whole frame consisting of two fields.
    /// This means you get both the resolution and high refresh-rate of interlaced video.
    InterlacedSemiDoubleBuffered,
}

#[allow(missing_docs)]
#[derive(Copy, Clone, Debug, Format)]
pub struct CVideoConfig<'t, NF: NoFields> {
    pub(crate) signal_descr: SignalDescription<'t>,
    pub(crate) buffering_mode: BufferingMode,
    pub(crate) pio_prescaler: u16,
    _nf: PhantomData<NF>,
}

impl<'t, NF: NoFields> CVideoConfig<'t, NF> {
    /// Some basic checks on the provided values.
    pub const fn check(&self) -> bool {
        self.signal_descr.check()
    }

    /// The amount of display columns, i.e. the width in number of pixels
    pub const fn display_columns(&self) -> u32 {
        self.signal_descr.display_columns()
    }

    /// The number of CPU clock cycles per field
    ///
    /// In case of progressive video, this is the duration for one frame. In case of interlaced, this
    /// indicates the exact mean duration of the two fields.
    pub const fn cpu_ticks_per_field(&self) -> u32 {
        self.signal_descr.ticks_per_field() * self.pio_prescaler as u32
    }

    /// Pixel height
    ///
    /// In case of interlaced, includes both the odd and even lines
    pub const fn display_lines(&self) -> u32 {
        self.signal_descr.display_lines()
    }

    /// Number of u32 words needed for this configuration
    ///
    /// Includes optional double buffering. Function is const so this can be used to allocate
    /// static buffers
    pub const fn needed_buffer_size(&self) -> usize {
        let single_buffer_size = self.signal_descr.needed_buffer_size();
        let multiplication = match self.buffering_mode {
            BufferingMode::SingleBuffered | BufferingMode::InterlacedSemiDoubleBuffered => 1,
            BufferingMode::DoubleBuffered => 2,
        };

        single_buffer_size * multiplication
    }

    #[doc(hidden)]
    pub const fn pio_prescaler(&self) -> u16 {
        self.pio_prescaler
    }

    #[doc(hidden)]
    pub fn prepare_buffer<'buf>(
        &self,
        buffer: &'buf mut [u32],
        labels: LabelAddresses,
    ) -> Result<(Buffer<'buf, NF>, Buffer<'buf, NF>)> {
        blyat!(
            buffer.len() >= self.needed_buffer_size(),
            "Given buffer not big enough"
        );

        match self.buffering_mode {
            BufferingMode::SingleBuffered => {
                let (buffer, _) = prepare_buffer::<NF>(&self.signal_descr, buffer, labels);
                let split_point = buffer.buffer_pixel_offsets[0];

                let (buffer_rest, buffer_display) = buffer.buffer.split_at_mut(split_point);

                Ok((
                    Buffer::SyncStuff(buffer_rest),
                    Buffer::DisplayBuffer(DisplayBuffer {
                        buffer: buffer_display,
                        buffer_pixel_offsets: [
                            0,
                            buffer.buffer_pixel_offsets[1].saturating_sub(split_point),
                        ],
                        columns: buffer.columns,
                        stride: buffer.stride,
                        lines: buffer.lines,
                        _fc: Default::default(),
                    }),
                ))
            }

            BufferingMode::DoubleBuffered => {
                let (buffer_a, buffer_b) =
                    buffer.split_at_mut(self.signal_descr.needed_buffer_size());
                assert!(buffer_b.len() >= self.signal_descr.needed_buffer_size());

                let (buffer_a, _) = prepare_buffer(&self.signal_descr, buffer_a, labels);
                let (buffer_b, _) = prepare_buffer(&self.signal_descr, buffer_b, labels);

                Ok((
                    Buffer::DisplayBuffer(buffer_a),
                    Buffer::DisplayBuffer(buffer_b),
                ))
            }

            BufferingMode::InterlacedSemiDoubleBuffered => {
                assert_eq!(NF::N, OneField::N); // The resulting display buffers have one field each
                assert_eq!(self.signal_descr.no_fields(), 2); // Make sure this is an interlaced video signal description

                let (buffer, split_at) = prepare_buffer::<NF>(&self.signal_descr, buffer, labels);
                let (buffer_a, buffer_b) = buffer.buffer.split_at_mut(split_at);

                assert_eq!(buffer.lines % 2, 0);

                Ok((
                    Buffer::DisplayBuffer(DisplayBuffer {
                        buffer: buffer_a,
                        buffer_pixel_offsets: [buffer.buffer_pixel_offsets[0], 0],
                        columns: buffer.columns,
                        stride: buffer.stride,
                        lines: buffer.lines / 2,
                        _fc: Default::default(),
                    }),
                    Buffer::DisplayBuffer(DisplayBuffer {
                        buffer: buffer_b,
                        buffer_pixel_offsets: [buffer.buffer_pixel_offsets[1] - split_at, 0],
                        columns: buffer.columns,
                        stride: buffer.stride,
                        lines: buffer.lines / 2,
                        _fc: Default::default(),
                    }),
                ))
            }
        }
    }

    #[doc(hidden)]
    pub const fn ticks_per_pixel(&self) -> u32 {
        self.signal_descr.ticks_per_pixel
    }
}

/// Standard timings that we probably shouldn't mess with
///
/// But we still can :)
///
/// All durations are in seconds
///
/// There are two standard timings defined as consts: [PAL_STD_DURATIONS] and [NTSC_STD_DURATIONS]
#[derive(Copy, Clone)]
pub struct StandardDurations {
    pub scanline_duration: f64,
    pub short_vsync_duration: f64,
    pub long_vsync_duration: f64,
    pub hsync_pulse_duration: f64,
    pub min_back_porch_duration: f64,
    pub min_front_porch_duration: f64,
}

impl StandardDurations {
    const fn max_display_length(&self) -> f64 {
        SF(self.scanline_duration)
            .sub(SF(self.hsync_pulse_duration))
            .sub(SF(self.min_back_porch_duration))
            .sub(SF(self.min_front_porch_duration))
            .to_f64()
    }

    /// Does some basic checks on the numbers
    pub const fn ok(&self) -> bool {
        self.scanline_duration > 0.0
            && self.short_vsync_duration > 0.0
            && self.long_vsync_duration > 0.0
            && self.hsync_pulse_duration > 0.0
            && self.min_back_porch_duration > 0.0
            && self.min_front_porch_duration > 0.0
            && self.short_vsync_duration < SF(self.scanline_duration).div(SF(2.0)).to_f64()
            && self.long_vsync_duration < SF(self.scanline_duration).div(SF(2.0)).to_f64()
            && self.hsync_pulse_duration
                + self.min_back_porch_duration
                + self.min_front_porch_duration
                < self.scanline_duration
    }
}

pub const PAL_STD_DURATIONS: StandardDurations = StandardDurations {
    scanline_duration: 64e-6,
    short_vsync_duration: 2.35e-6,
    long_vsync_duration: 27.3e-6,
    hsync_pulse_duration: 4.7e-6,
    min_back_porch_duration: 5.7e-6,
    min_front_porch_duration: 1.65e-6,
};

pub const NTSC_STD_DURATIONS: StandardDurations = StandardDurations {
    scanline_duration: 63.55e-6,
    short_vsync_duration: 2.35e-6,
    long_vsync_duration: 27.075e-6,
    hsync_pulse_duration: 4.7e-6,
    min_back_porch_duration: 4.5e-6,
    min_front_porch_duration: 1.5e-6,
};

#[derive(Copy, Clone)]
pub enum HorizontalConstraint {
    MarginsAndPixelCount {
        margin_left: f64,
        margin_right: f64,
        pixels: u32,
    },
    ExactData(HorizontalTiming),
}

/// Horizontal timings, in clock ticks
#[derive(Copy, Clone)]
pub struct HorizontalTiming {
    pub scanline: u32,
    pub vsync_long_pulse: u32,
    pub vsync_short_pulse: u32,
    pub hsync_pulse: u32,

    pub pixel_width: u32,
    pub back_porch: u32,
    pub front_porch: u32,
    pub pio_prescaler: u16,
}

impl HorizontalTiming {
    const fn from_constraints(
        constraints: HorizontalConstraint,
        standard_durations: StandardDurations,
        cpu_freg: u64,
    ) -> Result<Self> {
        const fn ticks(x: SF, f: SF) -> u32 {
            f.mul(x).round().to_f64() as u32
        }
        const fn ticks_per_pixel(display_duration: SF, pio_freq: SF, pixel_count: u32) -> u32 {
            display_duration
                .mul(pio_freq)
                .div(SF(pixel_count as f64))
                .round()
                .to_f64() as u32
        }

        let cpu_freq = SF(cpu_freg as f64);

        match constraints {
            HorizontalConstraint::MarginsAndPixelCount {
                margin_left,
                margin_right,
                pixels,
            } => {
                blyat!(pixels > 0, "Number of pixels is 0");
                blyat!(
                    0.0 <= margin_left && margin_left <= 1.0,
                    "Margin left out of range (0 .. 1)"
                );
                blyat!(
                    0.0 <= margin_right && margin_right <= 1.0,
                    "Margin right of out range (0 ..1)"
                );

                let scanline_length = SF(standard_durations.scanline_duration);
                let max_display_length = SF(standard_durations.max_display_length());
                let back_porch_length = SF(standard_durations.min_back_porch_duration)
                    .add(max_display_length.mul(SF(margin_left).div(SF(2.0))));
                let front_porch_length = SF(standard_durations.min_front_porch_duration)
                    .add(max_display_length.mul(SF(margin_left).div(SF(2.0))));
                let hsync_length = SF(standard_durations.hsync_pulse_duration);

                let display_length = scanline_length
                    .sub(hsync_length)
                    .sub(back_porch_length)
                    .sub(front_porch_length);

                blyat!(
                    ticks_per_pixel(display_length, cpu_freq, pixels) > 0,
                    "Pixel duration too short for CPU frequency"
                );

                let mut found_prescaler = None;
                {
                    let mut try_prescaler = 1;
                    'try_loop: while try_prescaler < 1000 {
                        let ticks = ticks_per_pixel(
                            display_length,
                            cpu_freq.div(SF(try_prescaler as f64)),
                            pixels,
                        );
                        if ticks <= MAX_PIXEL_CLOCK_CYCLES as u32 && ticks > 0 {
                            found_prescaler = Some(try_prescaler);
                            break 'try_loop;
                        }

                        try_prescaler += 1
                    }
                }

                blyat!(found_prescaler.is_some(), "Could not find PIO prescaler");
                let pio_prescaler = found_prescaler.unwrap();
                let pio_freq = cpu_freq.div(SF(pio_prescaler as f64));

                let scanline_ticks = ticks(scanline_length, pio_freq);
                let back_porch_ticks = ticks(back_porch_length, pio_freq);
                let front_porch_ticks = ticks(front_porch_length, pio_freq);
                let hsync_ticks = ticks(hsync_length, pio_freq);

                blyat!(display_length.to_f64() > 0.0, "Scanline too short");
                let pixel_length = display_length.div(SF(pixels as f64));
                let corrected_pixel_length = ticks(pixel_length, pio_freq);
                blyat!(corrected_pixel_length > 0, "Pixel duration is 0");
                let corrected_display_ticks = corrected_pixel_length * pixels;
                let scanline_length_missfit = corrected_display_ticks as i32
                    - (scanline_ticks as i32
                        - hsync_ticks as i32
                        - back_porch_ticks as i32
                        - front_porch_ticks as i32);

                // Adjustments to the back- and front porch needed to keep the whole line
                // exactly as given with the corrected display length.
                let offset_back_porch = scanline_length_missfit / 2;
                let offset_front_porch = scanline_length_missfit - offset_back_porch;

                let corrected_back_porch = back_porch_ticks as i32 - offset_back_porch;
                let corrected_front_porch = front_porch_ticks as i32 - offset_front_porch;

                blyat!(corrected_back_porch > 0, "Back-porch became 0");
                blyat!(corrected_front_porch > 0, "Front-porch became 0");

                Ok(Self {
                    scanline: scanline_ticks,
                    vsync_long_pulse: ticks(SF(standard_durations.long_vsync_duration), pio_freq),
                    vsync_short_pulse: ticks(SF(standard_durations.short_vsync_duration), pio_freq),
                    hsync_pulse: hsync_ticks,
                    pixel_width: corrected_pixel_length,
                    back_porch: corrected_back_porch as u32,
                    front_porch: corrected_front_porch as u32,
                    pio_prescaler,
                })
            }

            HorizontalConstraint::ExactData(x) => Ok(x),
        }
    }
}

#[derive(Copy, Clone)]
pub enum VerticalConstraint {
    DisplayLinesAndFps {
        /// Note: For interlaced video, the number of total lines is double this
        number_of_lines_per_field: u32,

        offset: i32,

        /// Note: For interlaced video, fields per second is double the frame-rate
        fields_per_second: f64,
    },

    MarginsAndFps {
        margin_top: f64,
        margin_bottom: f64,

        /// Note: For interlaced video, fields per second is double the frame-rate
        fields_per_second: f64,
    },
    ExactLineCount(VerticalTiming),
}

/// Vertical timings, in number of lines
#[derive(Copy, Clone)]
pub struct VerticalTiming {
    pub display_lines: u32,
    pub top_blank_lines: u32,
    pub bottom_blank_lines: u32,
}

impl VerticalTiming {
    const fn from_constraints(
        constraints: VerticalConstraint,
        scanline_length_ticks: u32,
        pio_freq: SF,
        signal_pattern: &[SignalSection],
    ) -> Result<Self> {
        let sync_lines = sync_lines_count(signal_pattern);

        match constraints {
            VerticalConstraint::DisplayLinesAndFps {
                number_of_lines_per_field: number_of_display_lines,
                offset,
                fields_per_second: fps,
            } => {
                blyat!(fps > 0.0, "FPS is 0");
                let fps = SF(fps);
                let total_lines = pio_freq
                    .div(fps.mul(SF(scanline_length_ticks as f64)))
                    .round()
                    .to_f64() as u32;

                blyat!(
                    total_lines > (sync_lines + number_of_display_lines),
                    "Not enough lines available"
                );
                let blank_lines = total_lines - sync_lines - number_of_display_lines;

                blyat!(
                    (blank_lines / 2) as i32 >= offset,
                    "Vertical offset too large"
                );
                let top_blank_lines = ((blank_lines / 2) as i32 - offset) as u32;

                assert!(blank_lines >= top_blank_lines);
                let bottom_blank_lines = blank_lines - top_blank_lines;

                Ok(Self {
                    display_lines: number_of_display_lines,
                    top_blank_lines,
                    bottom_blank_lines,
                })
            }
            VerticalConstraint::MarginsAndFps {
                margin_top,
                margin_bottom,
                fields_per_second: fps,
            } => {
                blyat!(
                    0.0 <= margin_top && margin_top <= 1.0,
                    "Top margin out of range (0 .. 1)"
                );
                blyat!(
                    0.0 <= margin_bottom && margin_bottom <= 1.0,
                    "Bottom margin out of range (0 .. 1)"
                );

                blyat!(fps > 0.0, "FPS is 0");
                let fps = SF(fps);
                let total_lines = pio_freq
                    .div(fps.mul(SF(scanline_length_ticks as f64)))
                    .round()
                    .to_f64() as u32;
                let max_display_lines = total_lines - sync_lines;
                let top_blank_lines = SF(margin_top)
                    .mul(SF(max_display_lines as f64))
                    .div(SF(2.0))
                    .round()
                    .to_f64() as u32;
                let bottom_blank_lines = SF(margin_bottom)
                    .mul(SF(max_display_lines as f64))
                    .div(SF(2.0))
                    .round()
                    .to_f64() as u32;

                blyat!(
                    total_lines >= top_blank_lines + bottom_blank_lines + sync_lines,
                    "Not enough lines available"
                );

                Ok(Self {
                    display_lines: total_lines - top_blank_lines - bottom_blank_lines - sync_lines,
                    top_blank_lines,
                    bottom_blank_lines,
                })
            }
            VerticalConstraint::ExactLineCount(x) => Ok(x),
        }
    }
}

const fn config_from_constraints<NF: NoFields>(
    buffering_mode: BufferingMode,
    horizontal: HorizontalConstraint,
    vertical: VerticalConstraint,
    standard_durations: StandardDurations,
    cpu_freq: u64,
    signal_pattern: &'static [SignalSection],
) -> Result<CVideoConfig<'static, NF>> {
    blyat!(cpu_freq > 0, "CPU frequency is 0");
    blyat!(standard_durations.ok(), "Standard durations not valid");

    let horizontal_timing = blin!(HorizontalTiming::from_constraints(
        horizontal,
        standard_durations,
        cpu_freq
    ));
    let pio_freq = SF(cpu_freq as f64).div(SF(horizontal_timing.pio_prescaler as f64));

    let vertical_timing = blin!(VerticalTiming::from_constraints(
        vertical,
        horizontal_timing.scanline,
        pio_freq,
        signal_pattern
    ));

    Ok(CVideoConfig {
        signal_descr: SignalDescription {
            ticks_per_pixel: horizontal_timing.pixel_width,
            scanline_length: horizontal_timing.scanline,
            vsync_long_pulse_length: horizontal_timing.vsync_long_pulse,
            vsync_short_pulse_length: horizontal_timing.vsync_short_pulse,
            hsync_pulse_length: horizontal_timing.hsync_pulse,
            back_porch_length: horizontal_timing.back_porch,
            front_porch_length: horizontal_timing.front_porch,

            display_lines: vertical_timing.display_lines,
            top_blank_lines: vertical_timing.top_blank_lines,
            bottom_blank_lines: vertical_timing.bottom_blank_lines,
            pattern: signal_pattern,
        },
        buffering_mode,
        pio_prescaler: horizontal_timing.pio_prescaler,
        _nf: PhantomData::<NF> {},
    })
}

impl CVideoConfig<'static, OneField> {
    pub const fn from_constraints_semi_double_buffered(
        horizontal: HorizontalConstraint,
        vertical: VerticalConstraint,
        standard_durations: StandardDurations,
        pio_freq: u64,
    ) -> Result<Self> {
        config_from_constraints::<OneField>(
            BufferingMode::InterlacedSemiDoubleBuffered,
            horizontal,
            vertical,
            standard_durations,
            pio_freq,
            INTERLACED_PATTERN,
        )
    }

    pub const fn from_constraints_progressive(
        buffering_mode: BufferingMode,
        horizontal: HorizontalConstraint,
        vertical: VerticalConstraint,
        standard_durations: StandardDurations,
        pio_freq: u64,
    ) -> Result<Self> {
        blyat!(
            !matches!(buffering_mode, BufferingMode::InterlacedSemiDoubleBuffered),
            "Buffering mode not compatible"
        );
        config_from_constraints::<OneField>(
            buffering_mode,
            horizontal,
            vertical,
            standard_durations,
            pio_freq,
            PROGRESSIVE_PATTERN,
        )
    }
}

impl CVideoConfig<'static, TwoFields> {
    pub const fn from_constraints_interlaced(
        buffering_mode: BufferingMode,
        horizontal: HorizontalConstraint,
        vertical: VerticalConstraint,
        standard_durations: StandardDurations,
        pio_freq: u64,
    ) -> Result<Self> {
        blyat!(
            !matches!(buffering_mode, BufferingMode::InterlacedSemiDoubleBuffered),
            "Buffering mode not compatible"
        );
        config_from_constraints::<TwoFields>(
            buffering_mode,
            horizontal,
            vertical,
            standard_durations,
            pio_freq,
            INTERLACED_PATTERN,
        )
    }
}