laser-dac 0.14.1

//! Frame-first presentation types and engine.
//!
//! This module provides:
//! - [`Frame`]: immutable frame type for submission
//! - [`TransitionFn`] / [`default_transition`]: blanking between frames
//! - `PresentationEngine`: core frame lifecycle manager (internal)
//! - [`FrameSession`] / [`FrameSessionConfig`]: public frame-mode API

pub(crate) mod content_source;
pub(crate) mod driver;
mod engine;
mod output_model;
mod session;
mod slice_pipeline;

pub use session::FrameSessionMetrics;
pub use session::{FrameSession, FrameSessionConfig};

// Shared by `SlicePipeline` and the streaming path (`ChunkProducer`).
pub(crate) use engine::ColorDelayLine;

// Re-export internal types for tests (they live in sub-modules but tests use `super::*`)
#[cfg(all(test, not(feature = "testutils")))]
pub(crate) use engine::PresentationEngine;

// Re-export narrow internals used by the feature-gated benchmark fixtures.
#[cfg(feature = "testutils")]
pub use engine::PresentationEngine;
#[cfg(feature = "testutils")]
pub(crate) use slice_pipeline::SlicePipeline;

use crate::config::IdlePolicy;
use crate::point::LaserPoint;
use std::sync::Arc;
use std::time::Duration;

// =============================================================================
// Shared time & blanking helpers (used by SlicePipeline and ChunkProducer)
// =============================================================================

/// Convert a duration to a point count at the given rate, rounded up.
/// Zero duration or zero pps yields zero points.
pub(crate) fn duration_to_points(d: Duration, pps: u32) -> usize {
    if d.is_zero() || pps == 0 {
        return 0;
    }

    // Use integer nanoseconds so sub-microsecond precision is preserved and
    // the documented ceil(delay * pps) behavior is exact. Duration's maximum
    // multiplied by u32::MAX fits in u128; saturating the final conversion
    // avoids wrapping on platforms whose usize cannot represent the result.
    const NANOS_PER_SEC: u128 = 1_000_000_000;
    let nanos = u128::from(d.as_secs()) * NANOS_PER_SEC + u128::from(d.subsec_nanos());
    let points = (nanos * u128::from(pps)).div_ceil(NANOS_PER_SEC);
    usize::try_from(points).unwrap_or(usize::MAX)
}

/// The blank park point implied by an idle policy: `Park { x, y }` parks at the
/// given position; every other policy parks at the origin.
pub(crate) fn park_point(idle_policy: &IdlePolicy) -> LaserPoint {
    match idle_policy {
        IdlePolicy::Park { x, y } => LaserPoint::blanked(*x, *y),
        _ => LaserPoint::blanked(0.0, 0.0),
    }
}

/// Blank (zero all four color channels of) every point in `buffer`.
/// Coordinates are left untouched so positions stay continuous.
pub(crate) fn blank_prefix(buffer: &mut [LaserPoint]) {
    for p in buffer {
        p.r = 0;
        p.g = 0;
        p.b = 0;
        p.intensity = 0;
    }
}

// =============================================================================
// OutputFilter
// =============================================================================

/// Why an [`OutputFilter`] was reset.
///
/// Resets happen at output continuity boundaries where downstream processing
/// should discard history and treat the next presented slice as a fresh stream.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum OutputResetReason {
    /// The session scheduler started.
    SessionStart,
    /// The backend reconnected and presentation state was replayed.
    Reconnect,
    /// Output was armed and startup blanking is about to resume visible content.
    Arm,
    /// Output was disarmed and presented output becomes forced-blanked.
    Disarm,
}

/// The delivery mode of the presented slice passed to an [`OutputFilter`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PresentedSliceKind {
    /// A FIFO chunk materialized by the frame session.
    FifoChunk,
    /// A complete frame-swap hardware frame.
    FrameSwapFrame,
}

/// Metadata describing the final presented slice seen by an [`OutputFilter`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OutputFilterContext {
    /// Output rate for the presented slice.
    pub pps: u32,
    /// Whether the slice is a FIFO chunk or a frame-swap frame.
    pub kind: PresentedSliceKind,
    /// Whether the slice should be interpreted as cyclic.
    pub is_cyclic: bool,
}

/// Hook for advanced output-space processing in frame mode.
///
/// The filter runs on the final point sequence immediately before backend
/// write, after transition composition, blanking, and color delay.
///
/// `WouldBlock` retries reuse the already-filtered buffer verbatim. The filter
/// is only called again when a new presented slice is materialized.
pub trait OutputFilter: Send + 'static {
    /// Reset internal continuity state after a stream break.
    fn reset(&mut self, _reason: OutputResetReason) {}

    /// Transform the final presented output in place.
    fn filter(&mut self, points: &mut [LaserPoint], ctx: &OutputFilterContext);
}

// =============================================================================
// Frame
// =============================================================================

/// A complete frame of laser points authored by the application.
///
/// This is the unit of submission for frame-mode output. Frames are immutable
/// once created and cheaply cloneable via `Arc`.
///
/// # Example
///
/// ```
/// use laser_dac::presentation::Frame;
/// use laser_dac::LaserPoint;
///
/// let frame = Frame::new(vec![
///     LaserPoint::new(0.0, 0.0, 65535, 0, 0, 65535),
///     LaserPoint::new(1.0, 0.0, 0, 65535, 0, 65535),
/// ]);
/// assert_eq!(frame.len(), 2);
/// ```
#[derive(Clone, Debug)]
pub struct Frame {
    points: Arc<Vec<LaserPoint>>,
}

impl Frame {
    /// Create a new frame from a vector of points.
    pub fn new(points: Vec<LaserPoint>) -> Self {
        Self {
            points: Arc::new(points),
        }
    }

    /// Returns a reference to the frame's points.
    pub fn points(&self) -> &[LaserPoint] {
        &self.points
    }

    /// Returns the first point, or `None` if the frame is empty.
    pub fn first_point(&self) -> Option<&LaserPoint> {
        self.points.first()
    }

    /// Returns the last point, or `None` if the frame is empty.
    pub fn last_point(&self) -> Option<&LaserPoint> {
        self.points.last()
    }

    /// Returns the number of points in the frame.
    pub fn len(&self) -> usize {
        self.points.len()
    }

    /// Returns true if the frame contains no points.
    pub fn is_empty(&self) -> bool {
        self.points.is_empty()
    }

    /// Create a frame from an already-shared point buffer, without copying.
    pub fn from_shared(points: Arc<Vec<LaserPoint>>) -> Self {
        Self { points }
    }
}

impl From<Vec<LaserPoint>> for Frame {
    fn from(points: Vec<LaserPoint>) -> Self {
        Self::new(points)
    }
}

impl From<Arc<Vec<LaserPoint>>> for Frame {
    fn from(points: Arc<Vec<LaserPoint>>) -> Self {
        Self { points }
    }
}

// =============================================================================
// TransitionFn
// =============================================================================

/// Describes how to handle the seam between two adjacent frame endpoints.
///
/// Returned by [`TransitionFn`] to tell the engine what to do at each seam —
/// including self-loops (A→A) and frame changes (A→B).
#[derive(Clone, Debug)]
pub enum TransitionPlan {
    /// Keep both seam endpoints and insert these points between them.
    /// An empty vec keeps both endpoints with nothing in between.
    Transition(Vec<LaserPoint>),
    /// The two seam endpoints are the same logical point — coalesce them
    /// so only one copy appears in the output.
    Coalesce,
}

/// Callback that generates a transition plan between frames.
///
/// Called with the last point of the outgoing frame and the first point of
/// the incoming frame. Returns a [`TransitionPlan`] describing how to handle
/// the seam.
///
/// Self-loops (A→A) also run through this callback, so transition planning
/// is consistent regardless of whether the frame changed.
/// Runtime values available when a seam is newly composed.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct TransitionContext {
    /// Current session output rate.
    pub pps: u32,
}

pub type TransitionFn =
    Box<dyn Fn(&LaserPoint, &LaserPoint, &TransitionContext) -> TransitionPlan + Send>;

/// Default blanking transition settings (microseconds).
///
/// Converted to point counts via `round(µs × pps / 1_000_000)`.
const END_DWELL_US: f64 = 100.0;
const START_DWELL_US: f64 = 400.0;

/// Create the default transition function.
///
/// Dwell point counts are calculated from the current [`TransitionContext`]
/// each time a seam is composed, so runtime PPS changes affect the next seam.
///
/// Produces a 3-phase blanking sequence between frames:
///
/// 1. **End dwell** — repeat `from` with laser OFF. Lets the galvo settle
///    at the endpoint before moving.
/// 2. **Transit** — quintic ease-in-out interpolation from→to with laser OFF.
///    Point count scales with L∞ distance (0–64 points).
/// 3. **Start dwell** — repeat `to` with laser OFF. Lets the galvo settle
///    at the new position before the next frame lights up.
///
/// All points are blanked. The on-beam dwell phases (post-on, pre-on) from
/// the full 5-phase sequence are omitted — those are the frame's responsibility.
pub fn default_transition() -> TransitionFn {
    Box::new(
        move |from: &LaserPoint, to: &LaserPoint, context: &TransitionContext| {
            let end_dwell = (END_DWELL_US * context.pps as f64 / 1_000_000.0).round() as usize;
            let start_dwell = (START_DWELL_US * context.pps as f64 / 1_000_000.0).round() as usize;
            let dx = to.x - from.x;
            let dy = to.y - from.y;

            // L-infinity distance (correct for independent galvo axes)
            let d_inf = dx.abs().max(dy.abs());
            let transit = (32.0 * d_inf).ceil().clamp(0.0, 64.0) as usize;

            let total = end_dwell + transit + start_dwell;
            let mut points = Vec::with_capacity(total);

            // Phase 1: end dwell — blanked at source
            for _ in 0..end_dwell {
                points.push(LaserPoint::blanked(from.x, from.y));
            }

            // Phase 2: transit — quintic ease-in-out from→to, blanked
            for i in 0..transit {
                let t = (i as f32 + 1.0) / (transit as f32 + 1.0);
                let t = quintic_ease_in_out(t);
                points.push(LaserPoint::blanked(from.x + dx * t, from.y + dy * t));
            }

            // Phase 3: start dwell — blanked at destination
            for _ in 0..start_dwell {
                points.push(LaserPoint::blanked(to.x, to.y));
            }

            TransitionPlan::Transition(points)
        },
    )
}

/// Quintic ease-in-out: smooth acceleration/deceleration for galvo transit.
///
/// `t` in [0, 1] → output in [0, 1].
/// First half:  `16t⁵`
/// Second half: `0.5(2t−2)⁵ + 1`
fn quintic_ease_in_out(t: f32) -> f32 {
    if t < 0.5 {
        16.0 * t * t * t * t * t
    } else {
        let u = 2.0 * t - 2.0;
        0.5 * u * u * u * u * u + 1.0
    }
}

#[cfg(test)]
mod tests;