//! 有界不可变 RGBA 图片资源，由原生 Arc 共享，准备阶段解码/排字，逐帧软件渲染只采样像素。
//! 调用路径：graphics 的图像加载入口调用 png，text_flow 调用 text 缓存设备分辨率字词。
//! SoftwareRenderer.draw_image 逆映射目标像素后调用 sample；graphics 使用 outline 取得排版避让轮廓。
//! id 只用于原生缓存身份比较，不是 VM 句柄，也不表示两个相同像素资源必有相同 ID。
//!
//! Immutable, bounded RGBA images shared by display lists. Decoding and text
//! preparation happen outside the frame loop; the CPU backend samples them.
use crate::{
    display_list::Color,
    geometry::Rect,
    text::{self, TextStyle},
};
use std::{io::Cursor, sync::Arc};

#[derive(Debug, serde::Serialize)]
// 像素、尺寸和轮廓在构造完成后由 Arc 只读共享；序列化省略原始像素与轮廓。
pub struct Image {
    // 资源实际像素宽，png/text 构造保证至少为一。
    pub width: u32,
    // 资源实际像素高，与绘制局部逻辑 rect 可按 scale 不同。
    pub height: u32,
    // 每次准备新资源取得的进程内数值身份，PartialEq 只比较它以便快速判断缓存复用。
    pub id: u64,
    #[serde(skip)]
    // 行优先 RGBA 字节数组，保存 straight alpha；采样时临时转预乘权重避免透明边黑晕。
    pixels: Vec<u8>,
    #[serde(skip)]
    // PNG 的 alpha 保守凸包，用于图形排版避让；预渲染文字目前返回空轮廓。
    pub outline: Vec<crate::geometry::Point>,
}

impl Image {
    // 将受预算约束的 PNG 解码为 RGBA，并一次性生成透明轮廓；格式/解码错误直接交给加载调用方。
    pub fn png(bytes: &[u8]) -> anyhow::Result<Arc<Self>> {
        // 借用输入字节建立内存解码器，不在帧循环执行文件 I/O。
        let mut decoder = png::Decoder::new(Cursor::new(bytes));
        // 展开调色板/低位深并去掉 16 位低字节，使后面每个颜色样本可按 8 位通道读取。
        decoder.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);
        // 先读取 PNG 头，像素预算在分配输出缓冲前检查。
        let mut reader = decoder.read_info()?;
        // 头部尺寸非零且总像素不超过 4194304，使用 u64 乘法避免 u32 乘积溢出。
        let info = reader.info();
        anyhow::ensure!(
            info.width > 0
                && info.height > 0
                && u64::from(info.width) * u64::from(info.height) <= 4_194_304,
            "image exceeds pixel budget"
        );
        // 按解码器计算的输出字节数分配，计算溢出时拒绝而非猜测缓冲长度。
        let mut buffer = vec![
            0;
            reader
                .output_buffer_size()
                .ok_or_else(|| anyhow::anyhow!("image size overflow"))?
        ];
        // 解码一帧并取得实际输出布局，只消费 buffer_size 范围，不读取未写尾部。
        let info = reader.next_frame(&mut buffer)?;
        // 预留统一四通道容量，原 PNG 可以是灰度、RGB 或 RGBA。
        let mut pixels = Vec::with_capacity(info.width as usize * info.height as usize * 4);
        // 按解码后的每像素样本数遍历，所有格式归并成同一 RGBA 存储。
        for chunk in buffer[..info.buffer_size()].chunks_exact(info.color_type.samples()) {
            // 灰度复制到 RGB，缺 alpha 填 255；若 Indexed 未展开则报错，不能把索引当颜色通道。
            let rgba = match info.color_type {
                // 原生四通道直接复制，保留源 alpha。
                // 三通道图片默认全不透明，不从相邻像素误读 alpha。
                png::ColorType::Rgba => [chunk[0], chunk[1], chunk[2], chunk[3]],
                png::ColorType::Rgb => [chunk[0], chunk[1], chunk[2], 255],
                // 单灰度通道复制到三色，完全不透明。
                png::ColorType::Grayscale => [chunk[0], chunk[0], chunk[0], 255],
                // 灰度/alpha 双通道保留透明度，前三色仍同值。
                png::ColorType::GrayscaleAlpha => [chunk[0], chunk[0], chunk[0], chunk[1]],
                // EXPAND 后正常不应残留索引图，若仍存在就拒绝不支持的输出布局。
                png::ColorType::Indexed => anyhow::bail!("unexpanded indexed PNG"),
            };
            pixels.extend_from_slice(&rgba);
        }
        // 资源准备阶段扫描 alpha 生成保守轮廓，后续排版不必每帧重新遍历图片像素。
        let outline = alpha_hull(&pixels, info.width, info.height);
        Ok(Arc::new(Self {
            width: info.width,
            height: info.height,
            pixels,
            id: next_id(),
            outline,
        }))
    }

    /// Cache a shaped word at the actual device resolution. Padding preserves
    /// italic/serif overhangs. Returns its logical image rectangle and advance.
    // 按实际设备 scale 预渲染一段已排字文本，返回共享资源、逻辑图片框和不含 padding 的文字 advance。
    pub fn text(
        value: &str,
        style: TextStyle,
        scale: f32,
        color: Color,
    ) -> Result<(Arc<Self>, Rect, f32), &'static str> {
        // 用逻辑 TextStyle 测量自然字形 advance/行高；返回 advance 不随设备 DPI 改变。
        let size = text::measure(value, style);
        // 按字号预留约 30% 整数逻辑边距，容纳斜体/衬线伸出而不裁掉字形。
        let pad = (style.font_size * 0.3).ceil();
        // 两侧 padding 后乘设备比例再向上取整，实际资源至少一像素宽。
        let width = ((size.width + pad * 2.) * scale).ceil().max(1.) as u32;
        // 高度也含两侧留白并按设备比例取整，与 width 分别计算。
        let height = ((size.height + pad * 2.) * scale).ceil().max(1.) as u32;
        // 准备文字资源另限 1048576 像素，避免单段文本缓冲无限增长。
        if u64::from(width) * u64::from(height) > 1_048_576 {
            return Err("prepared text image exceeds pixel budget");
        }
        // 零初始化 RGBA 即透明背景，字形回调只修改实际覆盖的像素。
        let mut pixels = vec![0; width as usize * height as usize * 4];
        // 以设备字号绘制，负 padding 框与下面回调偏移共同把逻辑文字原点放在资源留白之后。
        text::draw_clipped(
            value,
            style.scaled(scale),
            color,
            None,
            Rect::new(-pad * scale, -pad * scale, width as f32, height as f32),
            |x, y, c| {
                // 把绘制回调坐标移到含左 padding 的缓冲位置，按设备像素舍入。
                let x = x + (pad * scale).round() as i32;
                // 纵向也加 top padding，保持字形基线与返回的逻辑图片框一致。
                let y = y + (pad * scale).round() as i32;
                // 排除所有缓冲外像素，防止字形 overhang 或舍入造成越界写入。
                if x < 0 || y < 0 || x >= width as i32 || y >= height as i32 {
                    return;
                }
                // 行优先像素索引乘四得到 RGBA 字节起点，先通过上面坐标范围检查。
                let i = (y as usize * width as usize + x as usize) * 4;
                // All glyphs have the same ink color; alpha-over preserves overlaps.
                pixels[i..i + 3].copy_from_slice(&[c.red, c.green, c.blue]);
                pixels[i + 3] = (u16::from(c.alpha)
                    + u16::from(pixels[i + 3]) * (255 - u16::from(c.alpha)) / 255)
                    as u8;
            },
        );
        // 返回的新图有独立 id；逻辑 rect 左上为负 padding，绘图能保持原文字基线与 advance 对齐。
        Ok((
            Arc::new(Self {
                width,
                height,
                pixels,
                id: next_id(),
                outline: vec![],
            }),
            Rect::new(-pad, -pad, width as f32 / scale, height as f32 / scale),
            size.width,
        ))
    }

    // 软件渲染器传入逆映射的归一化纹理点和已夹取 opacity；预乘 alpha 双线性插值后返回 straight RGBA。
    pub fn sample(&self, u: f32, v: f32, opacity: f32) -> Color {
        // 归一化 u 映射到像素中心索引，减 0.5 使 texel 中心落在整数坐标。
        let x = u * self.width as f32 - 0.5;
        // v 使用同样中心约定，不把资源边缘当作像素中心。
        let y = v * self.height as f32 - 0.5;
        // 取左上采样格的整数基点，四个邻居随后夹在资源边界。
        let (ix, iy) = (x.floor() as i32, y.floor() as i32);
        // 小数部分作为双线性权重，四项权重之和为一。
        let (fx, fy) = (x - x.floor(), y - y.floor());
        // 前三项累计 RGB×alpha×权重，第四项累计 alpha×权重，避免透明像素 RGB 污染边缘。
        let mut sum = [0.; 4];
        // 四邻像素按二维线性乘积权重采样，边缘通过 clamping 复制最近 texel。
        for (dx, dy, w) in [
            (0, 0, (1. - fx) * (1. - fy)),
            (1, 0, fx * (1. - fy)),
            (0, 1, (1. - fx) * fy),
            (1, 1, fx * fy),
        ] {
            // 横轴邻居夹到有效像素列，不在透明边缘之外读越界数据。
            let px = (ix + dx).clamp(0, self.width as i32 - 1) as usize;
            // 纵轴独立夹取，图片宽高不同也不能复用同一边界。
            let py = (iy + dy).clamp(0, self.height as i32 - 1) as usize;
            // 转换资源像素位置为四通道字节偏移。
            let i = (py * self.width as usize + px) * 4;
            // alpha 保留 0..255 数值再乘权重，前三色同用该权重以实现预乘插值。
            let a = f32::from(self.pixels[i + 3]) * w;
            // 只累计 RGB 三通道，最终 alpha 单独累加，避免重复乘整体 opacity。
            for (j, s) in sum.iter_mut().enumerate().take(3) {
                *s += f32::from(self.pixels[i + j]) * a;
            }
            sum[3] += a;
        }
        // 完全透明时直接返回透明黑，避免除以零且不泄露透明像素的无意义 RGB。
        if sum[3] <= 0. {
            return Color::rgba(0, 0, 0, 0);
        }
        // RGB 除累计 alpha 恢复 straight 通道，整体 opacity 只作用最终 alpha。
        Color::rgba(
            (sum[0] / sum[3]).round() as u8,
            (sum[1] / sum[3]).round() as u8,
            (sum[2] / sum[3]).round() as u8,
            (sum[3] * opacity).round() as u8,
        )
    }
}

/// Conservative convex silhouette from opaque row endpoints. Unlike an image's
/// rectangle, this excludes empty transparent margins. Generated once per PNG.
fn alpha_hull(pixels: &[u8], width: u32, height: u32) -> Vec<crate::geometry::Point> {
    use crate::geometry::Point;
    // 先收集各有效行左右端像素的四角点，后面求整体凸包，而非逐像素精确边界。
    let mut points = Vec::new();
    // 按行扫描 alpha，阈值 16 去掉几乎透明的外围像素。
    for y in 0..height {
        // 只保留 alpha>=16 的列号，颜色通道不影响避让轮廓。
        let xs: Vec<_> = (0..width)
            .filter(|&x| pixels[((y * width + x) * 4 + 3) as usize] >= 16)
            .collect();
        // 该行有有效像素才生成候选角点，空透明行不参与外形。
        if let (Some(&left), Some(&right)) = (xs.first(), xs.last()) {
            // 右端取 right+1 表达像素外边界，不把末列中心当作轮廓右缘。
            for x in [left as f32, right as f32 + 1.] {
                // 上下各取像素行边界，保守覆盖整个端点像素单元。
                for yy in [y as f32, y as f32 + 1.] {
                    points.push(Point::new(x, yy));
                }
            }
        }
    }
    // 按 x/y 全序排序，后面单调链要求稳定几何次序；随后去掉重复角点。
    points.sort_by(|a, b| a.x.total_cmp(&b.x).then(a.y.total_cmp(&b.y)));
    points.dedup();
    // 不足三点直接返回，无法构成面积凸多边形，不补造图片矩形。
    if points.len() < 3 {
        return points;
    }
    // 二维叉积符号判断转向，单调链移除非凸与共线中间点。
    let cross =
        |a: Point, b: Point, c: Point| (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
    // 结果栈先构造下链，再逆序追加上链。
    let mut hull: Vec<Point> = Vec::new();
    // 按升序构造第一条凸包链，每个候选最多入栈/出栈一次。
    for &p in &points {
        // 新点使末两点不构成严格左转时弹出中间点，保留外侧端点。
        while hull.len() >= 2 && cross(hull[hull.len() - 2], hull[hull.len() - 1], p) <= 0. {
            hull.pop();
        }
        hull.push(p);
    }
    // 记录下链末端位置，构造上链时不能越过这条边界。
    let lower = hull.len();
    // 反向跳过已在下链末端的最右点，继续构造上链并闭合。
    for &p in points.iter().rev().skip(1) {
        // 与下链相同转向规则，但保留已完成下链；最后会去掉重复闭合首点。
        while hull.len() > lower && cross(hull[hull.len() - 2], hull[hull.len() - 1], p) <= 0. {
            hull.pop();
        }
        hull.push(p);
    }
    // 首点在上下链闭合时出现两次，移除末尾重复点，返回不含闭合副本的凸包。
    hull.pop();
    hull
}

// 为每个准备完成的原生资源分配进程内身份；只需要原子递增取号，不承担读写像素的跨线程发布屏障。
fn next_id() -> u64 {
    // 计数器从一开始，Relaxed 只用于取号；资源的安全共享由不可变 Arc 实现。
    static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
    NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
}
impl PartialEq for Image {
    // 原生缓存比较资源身份而非扫描像素；两次解码相同文件也会是不同资源 ID。
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id
    }
}