//! 图像几何变换模块（纯坐标运算，不涉及像素缓冲区）。
//!
//! 对应 Wayland `wl_output::Transform` 的 8 种旋转变体（旋转 + 翻转），
//! 为屏幕捕获提供 ROI（Region of Interest）裁剪与坐标系换算。
//!
//! # 与 Go 的对照
//!
//! - Go 标准库 `image/geom.go` 的 `Rectangle` 仅支持轴对齐矩形；本模块额外处理
//!   90°/180°/270° 旋转与水平/垂直翻转下的矩形映射。
//! - Go 用 `int` 表示坐标；本模块用 `i32`（与 `wl_output` 协议一致）。
//! - Wayland 协议要求捕获 ROI 在变换后的"帧坐标"中给出，本模块负责
//!   "屏坐标 → 帧坐标"的换算（见 [`screen_to_frame`]）。
//!
//! 注意：本模块**不操作像素缓冲区**（无 `&[u8]` / `Vec::with_capacity`），
//! 只做整数算术；真正的像素拷贝在 `state.rs` / `cap_portal.rs` 中通过
//! DMA-BUF 或 shm 完成。计划文档中提到的 `&[u8]` slice / `Vec` 预分配
//! 等模式不属于本模块，本模块的"重量级"Rust 模式聚焦在 `match` 穷尽匹配、
//! 元组解构、if 表达式、or-pattern 与整数 helper 方法（`.abs()`/`.clamp()`）。

// Wayland `wl_output::Transform` 的 8 种变体：4 种纯旋转（Normal*）+ 4 种
// "先水平翻转再旋转"（Flipped*）。单元 enum（无关联数据），`Copy + Eq` 派生
// 使其可在 `match` / `==` 中零开销使用。
//
// Go 没有内置 enum，等价于 `type Transform int` + `const ( Normal = iota; ... )`；
// Rust 的 enum 是真代数类型，编译期保证 `match` 穷尽性（漏写一个 variant
// 会直接编译失败，而 Go 的 switch 不强制 default）。
//
// `#[derive(...)]` 宏说明：`Debug`→允许 `{:?}` 调试输出；`Clone, Copy`→
// 单元 enum 按位复制即可（等价于 Go 整数值语义）；`PartialEq, Eq`→自动生成
// `==`/`!=`，基于 variant tag 比较。
/// Coordinate transformation module for Wayland output transforms.
///
/// Handles the 8 `wl_output` transform variants (rotation + reflection)
/// and ROI clipping for screen capture.
///
/// Wayland output transform enum, matching `wl_output::Transform`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Transform {
    Normal,
    Normal90,
    Normal180,
    Normal270,
    Flipped,
    Flipped90,
    Flipped180,
    Flipped270,
}

// 轴对齐矩形（Axis-Aligned Bounding Box，AABB）。
//
// 所有字段 `i32`（与 Wayland 协议一致）；Go 类比 `image.Rectangle` 但
// 用 `(x, y, w, h)` 而非 `(Min, Max)`，便于直接喂给 FFmpeg VAAPI 的 ROI 参数。
// `Copy + Eq`：值语义，函数传参/返回零开销（无 `&Rect` 借用开销）。
/// Axis-aligned rectangle in integer coordinates.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Rect {
    pub x: i32,
    pub y: i32,
    pub w: i32,
    pub h: i32,
}

// 返回变换对应的 2×2 基础矩阵 `(a, b, c, d)`。
//
// 这是纯算术查表，无副作用，编译器很容易内联到调用点。返回值用 4-tuple 而非
// `[i32; 4]` 数组：Rust 元组每字段可有不同类型（此处都是 i32 但语义不同），
// 模式匹配解构时更显式（`let (a, b, c, d) = ...`）。
/// Returns the 2×2 basis matrix (a, b, c, d) for the given transform.
///
/// The matrix represents the affine mapping from screen coordinates to
/// frame coordinates:
///
/// ```text
/// [new_x]   [a  b] [x]
/// [new_y] = [c  d] [y]
/// ```
pub fn transform_basis(transform: Transform) -> (i32, i32, i32, i32) {
    // `match` 是 Rust 的模式匹配控制流，对 enum 必须**穷尽**（exhaustive）：
    // 漏写任意 variant 会直接编译失败。Go 的 `switch` 不强制 default，
    // 此处 8 个 variant 必须全部列出，编译器即充当完整性检查器。
    //
    // 每个 arm 形如 `Pattern => expr,`，返回的 4-tuple 编码矩阵系数。
    // 这些数值来自 Wayland `wl_output::Transform` 协议规范，不可随意修改。
    match transform {
        // 单位矩阵：屏幕坐标 = 帧坐标。
        Transform::Normal => (1, 0, 0, 1),
        // 顺时针 90°：x/y 互换并取反。
        Transform::Normal90 => (0, 1, -1, 0),
        // 180°：两轴都取反。
        Transform::Normal180 => (-1, 0, 0, -1),
        // 顺时针 270°（= 逆时针 90°）。
        Transform::Normal270 => (0, -1, 1, 0),
        // 水平翻转（沿 Y 轴镜像）：x 取反。
        Transform::Flipped => (-1, 0, 0, 1),
        // 翻转 + 90°。
        Transform::Flipped90 => (0, 1, 1, 0),
        // 翻转 + 180°（等价于垂直翻转）。
        Transform::Flipped180 => (1, 0, 0, -1),
        // 翻转 + 270°。
        Transform::Flipped270 => (0, -1, -1, 0),
    }
}

// 将矩形从"屏幕坐标"映射到"帧坐标"，并平移到第一象限（[0, frame_w) × [0, frame_h)）。
//
// 这是 ROI（捕获区域）参数换算的核心：用户在屏幕上选了一块 `(x, y, w, h)`，
// 但 Wayland 帧已应用了 output transform（例如 90° 旋转），编码器看到的帧
// 坐标与屏幕坐标不同，必须先变换再喂给 VAAPI。
/// Transform a rectangle from screen space to frame space.
///
/// Applies the 2×2 basis matrix and computes offsets so the result
/// fits within the frame dimensions `(frame_w, frame_h)`.
///
/// ```text
/// new_x = a * x + b * y + offset_x
/// new_y = c * x + d * y + offset_y
/// ```
pub fn screen_to_frame(transform: Transform, rect: Rect, frame_w: i32, frame_h: i32) -> Rect {
    // 元组解构（tuple destructuring）：4-tuple 一次性拆成 4 个 `i32` 变量。
    // 类比 Go 的 `a, b, c, d := transformBasis(transform)`，但 Rust 的元组
    // 是真类型（可作为参数/返回值），Go 只能用多返回值模拟。
    let (a, b, c, d) = transform_basis(transform);

    // Compute the offset so that the transformed origin maps correctly.
    // For transforms with negative components, we need to shift by the
    // frame dimension to keep coordinates in [0, frame_w) × [0, frame_h).
    // `if ... { ... } else { ... }` 在 Rust 中是**表达式**（而非语句），
    // 直接产出值赋给 `offset_x`。Go 没有 ternary，必须 `var offset_x int;
    // if ... { offset_x = frame_w }`，Rust 这种写法更紧凑。
    let offset_x = if a + b < 0 { frame_w } else { 0 };
    let offset_y = if c + d < 0 { frame_h } else { 0 };

    let new_x = a * rect.x + b * rect.y + offset_x;
    let new_y = c * rect.x + d * rect.y + offset_y;
    let new_w = a * rect.w + b * rect.h;
    let new_h = c * rect.w + d * rect.h;

    // 结构体字面量（struct literal）：`Rect { x: ..., y: ..., ... }`。
    // 类比 Go 的 `image.Rectangle{Min: ..., Max: ...}`；Rust 允许字段简写
    //（变量名与字段名相同时只写一个，例如 `x` 而非 `x: x`）。
    //
    // `.abs()` 是 `i32` 的内置方法（取绝对值）：
    // 旋转后 `new_w`/`new_h` 可能为负（例如 90° 下宽变成原高取反），
    // 矩形尺寸必须非负，故取绝对值。
    Rect {
        x: new_x,
        y: new_y,
        w: new_w.abs(),
        h: new_h.abs(),
    }
}

// 90°/270° 旋转变换下，输出画布的宽高需要交换（横向屏幕旋转后变纵向）。
//
// 辅助函数：是则返回 `(h, w)`，否则原样返回 `(w, h)`。Go 类比：
// ```go
//   func transposeIf(t Transform, w, h int) (int, int) {
//       switch t { case Normal90, Normal270, Flipped90, Flipped270: return h, w }
//       return w, h
//   }
// ```
/// Swap width and height for 90° or 270° rotations.
///
/// After a quarter-turn rotation the output dimensions are transposed
/// relative to the input. This helper returns `(h, w)` for those cases
/// and `(w, h)` unchanged otherwise.
pub fn transpose_if_transform_transposed(transform: Transform, w: i32, h: i32) -> (i32, i32) {
    // `match` 配合 **or-pattern**：用 `|` 把多个 variant 合并为一个 arm，
    // 共享同一个表达式分支。Go 的 `switch` 用 `case A, B, C:` fallthrough 等价。
    // 注意 Rust 的 match 不存在隐式 fallthrough，每个 arm 必须 `=>` 显式给出表达式。
    match transform {
        // 四种"四分之一圈"旋转：宽高必须互换。
        Transform::Normal90
        | Transform::Normal270
        | Transform::Flipped90
        | Transform::Flipped270 => (h, w),
        // `_` 是通配符（wildcard），匹配所有未列出的 variant。
        // Rust 要求 match 穷尽，最后用 `_ =>` 兜底等价于 Go `default:` 分支。
        // 此处涵盖 `Normal` / `Normal180` / `Flipped` / `Flipped180`。
        _ => (w, h),
    }
}

// 将矩形裁剪到 `(0, 0) .. (bounds_w, bounds_h)` 范围内。
//
// 用于 ROI 校验：用户给的坐标可能为负或越界，编码器不接受这样的区域，
// 必须先 clamp 到合法范围。Go 标准库没有 `clamp` 内置函数（Go 1.21 才加入
// `min`/`max` 内置），通常要手写 `if x < lo { x = lo } else if x > hi { x = hi }`；
// Rust 的 `i32::clamp(lo, hi)` 是方法调用，语义更直观。
/// Clip a rectangle so it stays inside `(0, 0) .. (bounds_w, bounds_h)`.
///
/// The resulting rectangle has non-negative origin and its extent does
/// not exceed the bounds.
pub fn fit_inside_bounds(rect: Rect, bounds_w: i32, bounds_h: i32) -> Rect {
    // `.clamp(lo, hi)`：将值限制在 `[lo, hi]` 闭区间内（小于 lo 返回 lo，
    // 大于 hi 返回 hi，否则原值）。返回 `i32`（self by value）。
    let x = rect.x.clamp(0, bounds_w);
    let y = rect.y.clamp(0, bounds_h);
    // `.min(other)`：返回 `self` 与 `other` 的较小值（等价 Go 的 `if a < b` 三元）。
    // 此处把矩形的右边界限制到 `bounds_w`，避免越界。
    let right = (rect.x + rect.w).min(bounds_w);
    let bottom = (rect.y + rect.h).min(bounds_h);
    // `.max(other)`：返回较大值。此处保证宽高非负（`right - x` 在
    // 完全越界的退化情形下可能为负，取 max(0) 兜底）。
    let w = (right - x).max(0);
    let h = (bottom - y).max(0);
    // 字段简写：`x`/`y`/`w`/`h` 变量名与 `Rect` 字段名相同，可省略 `field: value`。
    Rect { x, y, w, h }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── transform_basis ───────────────────────────────────────────

    #[test]
    fn basis_normal_is_identity() {
        assert_eq!(transform_basis(Transform::Normal), (1, 0, 0, 1));
    }

    #[test]
    fn basis_90_cw_rotation() {
        assert_eq!(transform_basis(Transform::Normal90), (0, 1, -1, 0));
    }

    #[test]
    fn basis_180_rotation() {
        assert_eq!(transform_basis(Transform::Normal180), (-1, 0, 0, -1));
    }

    #[test]
    fn basis_270_cw_rotation() {
        assert_eq!(transform_basis(Transform::Normal270), (0, -1, 1, 0));
    }

    #[test]
    fn basis_flipped_horizontal() {
        assert_eq!(transform_basis(Transform::Flipped), (-1, 0, 0, 1));
    }

    #[test]
    fn basis_flipped_90() {
        assert_eq!(transform_basis(Transform::Flipped90), (0, 1, 1, 0));
    }

    #[test]
    fn basis_flipped_180() {
        assert_eq!(transform_basis(Transform::Flipped180), (1, 0, 0, -1));
    }

    #[test]
    fn basis_flipped_270() {
        assert_eq!(transform_basis(Transform::Flipped270), (0, -1, -1, 0));
    }

    // ── screen_to_frame ───────────────────────────────────────────

    #[test]
    fn screen_to_frame_identity_unchanged() {
        let rect = Rect {
            x: 10,
            y: 20,
            w: 100,
            h: 50,
        };
        let result = screen_to_frame(Transform::Normal, rect, 1920, 1080);
        assert_eq!(
            result,
            Rect {
                x: 10,
                y: 20,
                w: 100,
                h: 50
            }
        );
    }

    #[test]
    fn screen_to_frame_90_rotates_origin() {
        // 90° CW: top-left (0,0) in screen should map to bottom-left in frame
        let rect = Rect {
            x: 0,
            y: 0,
            w: 100,
            h: 50,
        };
        let result = screen_to_frame(Transform::Normal90, rect, 1080, 1920);
        // a=0,b=1,c=-1,d=0 => offset_x=0, offset_y=1920 (c+d=-1<0)
        // new_x = 0*0 + 1*0 + 0 = 0
        // new_y = -1*0 + 0*0 + 1920 = 1920
        assert_eq!(result.x, 0);
        assert_eq!(result.y, 1920);
        // w' = 0*100 + 1*50 = 50, h' = -1*100 + 0*50 = -100 -> abs=100
        assert_eq!(result.w, 50);
        assert_eq!(result.h, 100);
    }

    #[test]
    fn screen_to_frame_180_rotates() {
        let rect = Rect {
            x: 100,
            y: 200,
            w: 300,
            h: 400,
        };
        let result = screen_to_frame(Transform::Normal180, rect, 1920, 1080);
        // a=-1,b=0,c=0,d=-1, offset_x=1920, offset_y=1080
        assert_eq!(result.x, -100 + 1920);
        assert_eq!(result.y, -200 + 1080);
        assert_eq!(result.w, 300);
        assert_eq!(result.h, 400);
    }

    #[test]
    fn screen_to_frame_flipped_horizontal() {
        let rect = Rect {
            x: 50,
            y: 30,
            w: 200,
            h: 100,
        };
        let result = screen_to_frame(Transform::Flipped, rect, 1920, 1080);
        // a=-1,b=0,c=0,d=1, offset_x=1920, offset_y=0
        assert_eq!(result.x, -50 + 1920);
        assert_eq!(result.y, 30);
        assert_eq!(result.w, 200);
        assert_eq!(result.h, 100);
    }

    // ── transpose_if_transform_transposed ─────────────────────────

    #[test]
    fn transpose_normal_no_swap() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Normal, 1920, 1080),
            (1920, 1080)
        );
    }

    #[test]
    fn transpose_90_swaps() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Normal90, 1920, 1080),
            (1080, 1920)
        );
    }

    #[test]
    fn transpose_180_no_swap() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Normal180, 1920, 1080),
            (1920, 1080)
        );
    }

    #[test]
    fn transpose_270_swaps() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Normal270, 1920, 1080),
            (1080, 1920)
        );
    }

    #[test]
    fn transpose_flipped_no_swap() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Flipped, 1920, 1080),
            (1920, 1080)
        );
    }

    #[test]
    fn transpose_flipped90_swaps() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Flipped90, 1920, 1080),
            (1080, 1920)
        );
    }

    #[test]
    fn transpose_flipped180_no_swap() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Flipped180, 1920, 1080),
            (1920, 1080)
        );
    }

    #[test]
    fn transpose_flipped270_swaps() {
        assert_eq!(
            transpose_if_transform_transposed(Transform::Flipped270, 1920, 1080),
            (1080, 1920)
        );
    }

    // ── fit_inside_bounds ─────────────────────────────────────────

    #[test]
    fn fit_inside_already_fits() {
        let rect = Rect {
            x: 10,
            y: 20,
            w: 100,
            h: 50,
        };
        let result = fit_inside_bounds(rect, 1920, 1080);
        assert_eq!(result, rect);
    }

    #[test]
    fn fit_inside_clips_right_and_bottom() {
        let rect = Rect {
            x: 1800,
            y: 1000,
            w: 200,
            h: 200,
        };
        let result = fit_inside_bounds(rect, 1920, 1080);
        assert_eq!(
            result,
            Rect {
                x: 1800,
                y: 1000,
                w: 120,
                h: 80
            }
        );
    }

    #[test]
    fn fit_inside_clips_negative_origin() {
        let rect = Rect {
            x: -50,
            y: -30,
            w: 200,
            h: 200,
        };
        let result = fit_inside_bounds(rect, 1920, 1080);
        assert_eq!(
            result,
            Rect {
                x: 0,
                y: 0,
                w: 150,
                h: 170
            }
        );
    }

    #[test]
    fn fit_inside_completely_out_of_bounds() {
        let rect = Rect {
            x: 2000,
            y: 2000,
            w: 100,
            h: 100,
        };
        let result = fit_inside_bounds(rect, 1920, 1080);
        assert_eq!(
            result,
            Rect {
                x: 1920,
                y: 1080,
                w: 0,
                h: 0
            }
        );
    }

    #[test]
    fn fit_inside_zero_size_rect() {
        let rect = Rect {
            x: 100,
            y: 100,
            w: 0,
            h: 0,
        };
        let result = fit_inside_bounds(rect, 1920, 1080);
        assert_eq!(
            result,
            Rect {
                x: 100,
                y: 100,
                w: 0,
                h: 0
            }
        );
    }

    #[test]
    fn fit_inside_zero_bounds() {
        let rect = Rect {
            x: 0,
            y: 0,
            w: 100,
            h: 100,
        };
        let result = fit_inside_bounds(rect, 0, 0);
        assert_eq!(
            result,
            Rect {
                x: 0,
                y: 0,
                w: 0,
                h: 0
            }
        );
    }
}