image_renderer/

canvas.rs

//! Canvas 绘制上下文
//!
//! 提供类似 skia-safe 风格的绘制 API

use crate::clip::{ClipOp, ClipStack};
use crate::color::Color;
use crate::error::{DrawError, Result};
use crate::font::TextStyle;
use crate::matrix::{CanvasState, Matrix};
use crate::paint::{Paint, PaintStyle};
use crate::path::Path;
use crate::point::Point;
use crate::rect::Rect;
use crate::surface::Surface;
use image::Rgba;
use imageproc::drawing::{
    draw_filled_rect_mut, draw_hollow_rect_mut, draw_line_segment_mut, draw_text_mut,
};
use imageproc::rect::Rect as ImageprocRect;

/// Canvas 绘制上下文
///
/// 提供在图片表面上进行各种绘制操作的能力
pub struct Canvas {
    /// 底层图片表面
    surface: Surface,
    /// 状态栈，用于保存和恢复变换和裁剪状态
    state_stack: Vec<CanvasState>,
    /// 当前变换矩阵
    current_matrix: Matrix,
    /// 裁剪栈
    clip_stack: ClipStack,
}

impl Canvas {
    /// 创建新的 Canvas
    pub fn new(width: u32, height: u32) -> Result<Self> {
        let surface = Surface::new(width, height)?;
        Ok(Self {
            surface,
            state_stack: Vec::new(),
            current_matrix: Matrix::identity(),
            clip_stack: ClipStack::new(),
        })
    }

    /// 创建指定背景色的 Canvas
    pub fn new_with_color(width: u32, height: u32, color: Color) -> Result<Self> {
        let surface = Surface::new_with_color(width, height, color.to_rgba())?;
        Ok(Self {
            surface,
            state_stack: Vec::new(),
            current_matrix: Matrix::identity(),
            clip_stack: ClipStack::new(),
        })
    }

    /// 从已有的 Surface 创建 Canvas
    pub fn from_surface(surface: Surface) -> Self {
        Self {
            surface,
            state_stack: Vec::new(),
            current_matrix: Matrix::identity(),
            clip_stack: ClipStack::new(),
        }
    }

    /// 从文件加载图片并创建 Canvas
    pub fn from_file<P: AsRef<std::path::Path>>(path: P) -> Result<Self> {
        let surface = Surface::from_file(path)?;
        Ok(Self {
            surface,
            state_stack: Vec::new(),
            current_matrix: Matrix::identity(),
            clip_stack: ClipStack::new(),
        })
    }

    /// 获取 Canvas 宽度
    pub fn width(&self) -> u32 {
        self.surface.width()
    }

    /// 获取 Canvas 高度
    pub fn height(&self) -> u32 {
        self.surface.height()
    }

    /// 获取 Canvas 尺寸
    pub fn dimensions(&self) -> (u32, u32) {
        self.surface.dimensions()
    }

    /// 清空 Canvas 为指定颜色
    pub fn clear(&mut self, color: Color) {
        self.surface.clear(color.to_rgba());
    }

    /// 保存到文件
    pub fn save_to_file<P: AsRef<std::path::Path>>(&self, path: P) -> Result<()> {
        self.surface.save(path)?;
        Ok(())
    }

    /// 导出为 PNG 字节数据
    pub fn to_png_bytes(&self) -> Result<Vec<u8>> {
        Ok(self.surface.to_png_bytes()?)
    }

    /// 导出为 JPEG 字节数据
    pub fn to_jpeg_bytes(&self, quality: u8) -> Result<Vec<u8>> {
        Ok(self.surface.to_jpeg_bytes(quality)?)
    }

    /// 获取底层 Surface
    pub fn surface(&self) -> &Surface {
        &self.surface
    }

    /// 获取可变的底层 Surface
    pub fn surface_mut(&mut self) -> &mut Surface {
        &mut self.surface
    }

    /// 绘制点
    pub fn draw_point(&mut self, point: Point, paint: &Paint) {
        let x = point.x;
        let y = point.y;

        if x >= 0 && y >= 0 {
            let x = x as u32;
            let y = y as u32;
            if x < self.width() && y < self.height() {
                self.surface.put_pixel(x, y, paint.color().to_rgba());
            }
        }
    }

    /// 绘制线段
    pub fn draw_line(&mut self, start: Point, end: Point, paint: &Paint) {
        let start_f = (start.x as f32, start.y as f32);
        let end_f = (end.x as f32, end.y as f32);

        draw_line_segment_mut(
            self.surface.image_mut(),
            start_f,
            end_f,
            paint.color().to_rgba(),
        );
    }

    /// 绘制矩形
    pub fn draw_rect(&mut self, rect: Rect, paint: &Paint) {
        let imageproc_rect = ImageprocRect::at(rect.x, rect.y).of_size(rect.width, rect.height);

        match paint.style() {
            PaintStyle::Fill => {
                draw_filled_rect_mut(
                    self.surface.image_mut(),
                    imageproc_rect,
                    paint.color().to_rgba(),
                );
            }
            PaintStyle::Stroke => {
                // 绘制空心矩形
                draw_hollow_rect_mut(
                    self.surface.image_mut(),
                    imageproc_rect,
                    paint.color().to_rgba(),
                );

                // 如果线宽大于1，需要绘制多层
                let stroke_width = paint.stroke_width() as i32;
                for i in 1..stroke_width {
                    let inner_rect = ImageprocRect::at(rect.x + i, rect.y + i).of_size(
                        rect.width.saturating_sub((i * 2) as u32),
                        rect.height.saturating_sub((i * 2) as u32),
                    );
                    if inner_rect.width() > 0 && inner_rect.height() > 0 {
                        draw_hollow_rect_mut(
                            self.surface.image_mut(),
                            inner_rect,
                            paint.color().to_rgba(),
                        );
                    }
                }
            }
            PaintStyle::FillAndStroke => {
                // 先填充
                draw_filled_rect_mut(
                    self.surface.image_mut(),
                    imageproc_rect,
                    paint.color().to_rgba(),
                );
                // 再描边
                draw_hollow_rect_mut(
                    self.surface.image_mut(),
                    imageproc_rect,
                    paint.color().to_rgba(),
                );
            }
        }
    }

    /// 绘制圆角矩形
    pub fn draw_rounded_rect(&mut self, rect: Rect, radius: f32, paint: &Paint) {
        // 使用四个圆弧和四条直线来绘制圆角矩形
        let r = radius.min((rect.width as f32 / 2.0).min(rect.height as f32 / 2.0));

        if r <= 0.0 {
            self.draw_rect(rect, paint);
            return;
        }

        let color = paint.color().to_rgba();

        // 简化实现：绘制矩形主体和四个角
        match paint.style() {
            PaintStyle::Fill | PaintStyle::FillAndStroke => {
                // 填充中心矩形
                let center_rect = ImageprocRect::at(rect.x, rect.y + r as i32)
                    .of_size(rect.width, rect.height - (r * 2.0) as u32);
                draw_filled_rect_mut(self.surface.image_mut(), center_rect, color);

                // 填充上下矩形
                let top_rect = ImageprocRect::at(rect.x + r as i32, rect.y)
                    .of_size(rect.width - (r * 2.0) as u32, r as u32);
                draw_filled_rect_mut(self.surface.image_mut(), top_rect, color);

                let bottom_rect =
                    ImageprocRect::at(rect.x + r as i32, rect.y + rect.height as i32 - r as i32)
                        .of_size(rect.width - (r * 2.0) as u32, r as u32);
                draw_filled_rect_mut(self.surface.image_mut(), bottom_rect, color);

                // 绘制四个圆角
                self.draw_circle_corner(rect.x + r as i32, rect.y + r as i32, r, color, true);
                self.draw_circle_corner(
                    rect.x + rect.width as i32 - r as i32,
                    rect.y + r as i32,
                    r,
                    color,
                    true,
                );
                self.draw_circle_corner(
                    rect.x + r as i32,
                    rect.y + rect.height as i32 - r as i32,
                    r,
                    color,
                    true,
                );
                self.draw_circle_corner(
                    rect.x + rect.width as i32 - r as i32,
                    rect.y + rect.height as i32 - r as i32,
                    r,
                    color,
                    true,
                );
            }
            PaintStyle::Stroke => {
                // 描边实现
                self.draw_rect(rect, paint);
            }
        }
    }

    /// 辅助方法：绘制圆形区域
    fn draw_circle_corner(&mut self, cx: i32, cy: i32, radius: f32, color: Rgba<u8>, fill: bool) {
        let r = radius as i32;
        for dy in -r..=r {
            for dx in -r..=r {
                let dist_sq = dx * dx + dy * dy;
                let r_sq = (radius * radius) as i32;

                if fill && dist_sq <= r_sq {
                    let x = cx + dx;
                    let y = cy + dy;
                    if x >= 0 && y >= 0 {
                        self.surface.put_pixel(x as u32, y as u32, color);
                    }
                }
            }
        }
    }

    /// 绘制圆形
    pub fn draw_circle(&mut self, center: Point, radius: f32, paint: &Paint) {
        let color = paint.color().to_rgba();
        let r = radius as i32;

        match paint.style() {
            PaintStyle::Fill | PaintStyle::FillAndStroke => {
                // 填充圆形
                for dy in -r..=r {
                    for dx in -r..=r {
                        let dist_sq = dx * dx + dy * dy;
                        let r_sq = (radius * radius) as i32;

                        if dist_sq <= r_sq {
                            let x = center.x + dx;
                            let y = center.y + dy;
                            if x >= 0 && y >= 0 {
                                self.surface.put_pixel(x as u32, y as u32, color);
                            }
                        }
                    }
                }
            }
            PaintStyle::Stroke => {
                // 描边圆形
                let stroke_width = paint.stroke_width();
                let inner_r = (radius - stroke_width).max(0.0);
                let inner_r_sq = (inner_r * inner_r) as i32;
                let outer_r_sq = (radius * radius) as i32;

                for dy in -r..=r {
                    for dx in -r..=r {
                        let dist_sq = dx * dx + dy * dy;

                        if dist_sq <= outer_r_sq && dist_sq >= inner_r_sq {
                            let x = center.x + dx;
                            let y = center.y + dy;
                            if x >= 0 && y >= 0 {
                                self.surface.put_pixel(x as u32, y as u32, color);
                            }
                        }
                    }
                }
            }
        }
    }

    /// 绘制椭圆
    pub fn draw_oval(&mut self, rect: Rect, paint: &Paint) {
        let cx = rect.x + rect.width as i32 / 2;
        let cy = rect.y + rect.height as i32 / 2;
        let rx = rect.width as f32 / 2.0;
        let ry = rect.height as f32 / 2.0;

        let color = paint.color().to_rgba();

        match paint.style() {
            PaintStyle::Fill | PaintStyle::FillAndStroke => {
                // 填充椭圆
                for y in rect.y..(rect.y + rect.height as i32) {
                    for x in rect.x..(rect.x + rect.width as i32) {
                        let dx = (x - cx) as f32;
                        let dy = (y - cy) as f32;

                        if (dx * dx) / (rx * rx) + (dy * dy) / (ry * ry) <= 1.0 {
                            if x >= 0 && y >= 0 {
                                self.surface.put_pixel(x as u32, y as u32, color);
                            }
                        }
                    }
                }
            }
            PaintStyle::Stroke => {
                // 描边椭圆
                let stroke_width = paint.stroke_width();
                let inner_rx = (rx - stroke_width).max(0.0);
                let inner_ry = (ry - stroke_width).max(0.0);

                for y in rect.y..(rect.y + rect.height as i32) {
                    for x in rect.x..(rect.x + rect.width as i32) {
                        let dx = (x - cx) as f32;
                        let dy = (y - cy) as f32;

                        let outer = (dx * dx) / (rx * rx) + (dy * dy) / (ry * ry);
                        let inner =
                            (dx * dx) / (inner_rx * inner_rx) + (dy * dy) / (inner_ry * inner_ry);

                        if outer <= 1.0 && inner >= 1.0 {
                            if x >= 0 && y >= 0 {
                                self.surface.put_pixel(x as u32, y as u32, color);
                            }
                        }
                    }
                }
            }
        }
    }

    /// 绘制文本
    pub fn draw_text(
        &mut self,
        text: &str,
        position: Point,
        text_style: &TextStyle,
        paint: &Paint,
    ) {
        let scale = text_style.scale();
        let font = text_style.font.inner();
        let color = paint.color().to_rgba();

        draw_text_mut(
            self.surface.image_mut(),
            color,
            position.x,
            position.y,
            scale,
            font,
            text,
        );
    }

    /// 绘制图片
    pub fn draw_image(&mut self, image: &Surface, position: Point) -> Result<()> {
        self.draw_image_rect(
            image,
            None,
            Rect::new(position.x, position.y, image.width(), image.height()),
        )
    }

    /// 绘制图片的指定区域到指定位置
    pub fn draw_image_rect(
        &mut self,
        image: &Surface,
        src_rect: Option<Rect>,
        dst_rect: Rect,
    ) -> Result<()> {
        // 获取源矩形
        let src = src_rect.unwrap_or_else(|| Rect::new(0, 0, image.width(), image.height()));

        // 验证源矩形
        if src.x < 0
            || src.y < 0
            || src.x as u32 + src.width > image.width()
            || src.y as u32 + src.height > image.height()
        {
            return Err(DrawError::InvalidCoordinates { x: src.x, y: src.y });
        }

        // 如果需要缩放
        let src_image = if src.width != dst_rect.width || src.height != dst_rect.height {
            // 先裁剪
            let cropped = image.crop(src.x as u32, src.y as u32, src.width, src.height)?;
            // 再缩放
            cropped.resize(dst_rect.width, dst_rect.height)?
        } else {
            // 只裁剪
            image.crop(src.x as u32, src.y as u32, src.width, src.height)?
        };

        // 复制像素
        for y in 0..dst_rect.height {
            for x in 0..dst_rect.width {
                let src_pixel = src_image.get_pixel(x, y).unwrap();
                let dst_x = dst_rect.x + x as i32;
                let dst_y = dst_rect.y + y as i32;

                if dst_x >= 0
                    && dst_y >= 0
                    && (dst_x as u32) < self.width()
                    && (dst_y as u32) < self.height()
                {
                    // Alpha 混合
                    self.blend_pixel(dst_x as u32, dst_y as u32, src_pixel);
                }
            }
        }

        Ok(())
    }

    /// Alpha 混合像素
    fn blend_pixel(&mut self, x: u32, y: u32, src: Rgba<u8>) {
        if let Some(dst) = self.surface.get_pixel(x, y) {
            let src_alpha = src[3] as f32 / 255.0;
            let dst_alpha = dst[3] as f32 / 255.0;

            if src_alpha == 0.0 {
                return;
            }

            if src_alpha == 1.0 {
                self.surface.put_pixel(x, y, src);
                return;
            }

            // Alpha 混合
            let out_alpha = src_alpha + dst_alpha * (1.0 - src_alpha);

            if out_alpha == 0.0 {
                return;
            }

            let r = ((src[0] as f32 * src_alpha + dst[0] as f32 * dst_alpha * (1.0 - src_alpha))
                / out_alpha) as u8;
            let g = ((src[1] as f32 * src_alpha + dst[1] as f32 * dst_alpha * (1.0 - src_alpha))
                / out_alpha) as u8;
            let b = ((src[2] as f32 * src_alpha + dst[2] as f32 * dst_alpha * (1.0 - src_alpha))
                / out_alpha) as u8;
            let a = (out_alpha * 255.0) as u8;

            self.surface.put_pixel(x, y, Rgba([r, g, b, a]));
        }
    }

    /// 九宫格绘制图片（类似 skia-safe 的 draw_image_nine）
    ///
    /// 将图片分割成 3x3 的九宫格，智能拉伸以适应目标区域。
    /// 四个角落保持不变，边缘单向拉伸，中心区域双向拉伸。
    ///
    /// # 参数
    ///
    /// * `image` - 要绘制的图片
    /// * `center` - 中心矩形区域，定义九宫格的分割方式
    /// * `dst` - 目标绘制区域
    ///
    /// # 九宫格分割示例
    ///
    /// ```text
    /// ┌─────────┬──────────┬─────────┐
    /// │  角落1  │  上边缘  │  角落2  │
    /// │ (固定)  │ (水平拉) │ (固定)  │
    /// ├─────────┼──────────┼─────────┤
    /// │ 左边缘  │  中心    │ 右边缘  │
    /// │ (垂直拉)│ (双向拉) │ (垂直拉)│
    /// ├─────────┼──────────┼─────────┤
    /// │  角落3  │  下边缘  │  角落4  │
    /// │ (固定)  │ (水平拉) │ (固定)  │
    /// └─────────┴──────────┴─────────┘
    /// ```
    pub fn draw_image_nine(&mut self, image: &Surface, center: Rect, dst: Rect) -> Result<()> {
        // 验证 center 矩形的有效性
        if center.x < 0
            || center.y < 0
            || center.x as u32 >= image.width()
            || center.y as u32 >= image.height()
            || center.x as u32 + center.width > image.width()
            || center.y as u32 + center.height > image.height()
        {
            return Err(DrawError::InvalidCoordinates {
                x: center.x,
                y: center.y,
            });
        }

        // 计算源图片的九个区域
        let src_left = center.x as u32;
        let src_top = center.y as u32;
        let src_right = image.width() - (center.x as u32 + center.width);
        let src_bottom = image.height() - (center.y as u32 + center.height);
        let src_center_width = center.width;
        let src_center_height = center.height;

        // 计算目标区域的九个区域
        // 如果目标区域太小，角落区域可能需要缩小
        let dst_left = src_left.min(dst.width / 3);
        let dst_top = src_top.min(dst.height / 3);
        let dst_right = src_right.min(dst.width / 3);
        let dst_bottom = src_bottom.min(dst.height / 3);

        let dst_center_width = dst.width.saturating_sub(dst_left + dst_right);
        let dst_center_height = dst.height.saturating_sub(dst_top + dst_bottom);

        // 绘制九个区域

        // 1. 左上角（固定大小）
        if dst_left > 0 && dst_top > 0 {
            let src_rect = Rect::new(0, 0, src_left, src_top);
            let dst_rect = Rect::new(dst.x, dst.y, dst_left, dst_top);
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 2. 上边缘（水平拉伸）
        if dst_center_width > 0 && dst_top > 0 {
            let src_rect = Rect::new(src_left as i32, 0, src_center_width, src_top);
            let dst_rect = Rect::new(dst.x + dst_left as i32, dst.y, dst_center_width, dst_top);
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 3. 右上角（固定大小）
        if dst_right > 0 && dst_top > 0 {
            let src_rect = Rect::new((image.width() - src_right) as i32, 0, src_right, src_top);
            let dst_rect = Rect::new(
                dst.x + (dst.width - dst_right) as i32,
                dst.y,
                dst_right,
                dst_top,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 4. 左边缘（垂直拉伸）
        if dst_left > 0 && dst_center_height > 0 {
            let src_rect = Rect::new(0, src_top as i32, src_left, src_center_height);
            let dst_rect = Rect::new(dst.x, dst.y + dst_top as i32, dst_left, dst_center_height);
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 5. 中心区域（双向拉伸）
        if dst_center_width > 0 && dst_center_height > 0 {
            let src_rect = Rect::new(
                src_left as i32,
                src_top as i32,
                src_center_width,
                src_center_height,
            );
            let dst_rect = Rect::new(
                dst.x + dst_left as i32,
                dst.y + dst_top as i32,
                dst_center_width,
                dst_center_height,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 6. 右边缘（垂直拉伸）
        if dst_right > 0 && dst_center_height > 0 {
            let src_rect = Rect::new(
                (image.width() - src_right) as i32,
                src_top as i32,
                src_right,
                src_center_height,
            );
            let dst_rect = Rect::new(
                dst.x + (dst.width - dst_right) as i32,
                dst.y + dst_top as i32,
                dst_right,
                dst_center_height,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 7. 左下角（固定大小）
        if dst_left > 0 && dst_bottom > 0 {
            let src_rect = Rect::new(
                0,
                (image.height() - src_bottom) as i32,
                src_left,
                src_bottom,
            );
            let dst_rect = Rect::new(
                dst.x,
                dst.y + (dst.height - dst_bottom) as i32,
                dst_left,
                dst_bottom,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 8. 下边缘（水平拉伸）
        if dst_center_width > 0 && dst_bottom > 0 {
            let src_rect = Rect::new(
                src_left as i32,
                (image.height() - src_bottom) as i32,
                src_center_width,
                src_bottom,
            );
            let dst_rect = Rect::new(
                dst.x + dst_left as i32,
                dst.y + (dst.height - dst_bottom) as i32,
                dst_center_width,
                dst_bottom,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        // 9. 右下角（固定大小）
        if dst_right > 0 && dst_bottom > 0 {
            let src_rect = Rect::new(
                (image.width() - src_right) as i32,
                (image.height() - src_bottom) as i32,
                src_right,
                src_bottom,
            );
            let dst_rect = Rect::new(
                dst.x + (dst.width - dst_right) as i32,
                dst.y + (dst.height - dst_bottom) as i32,
                dst_right,
                dst_bottom,
            );
            self.draw_image_rect(image, Some(src_rect), dst_rect)?;
        }

        Ok(())
    }

    /// 测量文本尺寸
    pub fn measure_text(&self, text: &str, text_style: &TextStyle) -> (u32, u32) {
        let scale = text_style.scale();
        let font = text_style.font.inner();

        let v_metrics = font.v_metrics(scale);
        let height = (v_metrics.ascent - v_metrics.descent).ceil() as u32;

        let width = font
            .layout(text, scale, rusttype::point(0.0, 0.0))
            .map(|g| g.position().x + g.unpositioned().h_metrics().advance_width)
            .last()
            .unwrap_or(0.0)
            .ceil() as u32;

        (width, height)
    }

    /// 绘制虚线
    ///
    /// 根据 Paint 中的虚线样式绘制虚线。如果虚线样式为 Solid，则绘制实线。
    ///
    /// # 参数
    ///
    /// * `start` - 起点
    /// * `end` - 终点
    /// * `paint` - 绘制样式（包含虚线模式）
    ///
    /// # 示例
    ///
    /// ```no_run
    /// use image_renderer::{Canvas, Color, Paint, Point, paint::DashStyle};
    ///
    /// let mut canvas = Canvas::new(400, 300).unwrap();
    /// let mut paint = Paint::stroke(Color::BLUE, 2.0);
    /// paint.set_dash_style(DashStyle::ShortDash);
    ///
    /// canvas.draw_dashed_line(
    ///     Point::new(50, 100),
    ///     Point::new(350, 100),
    ///     &paint
    /// );
    /// ```
    pub fn draw_dashed_line(&mut self, start: Point, end: Point, paint: &Paint) {
        // 如果是实线，直接使用普通绘制
        if paint.dash_style().is_solid() {
            self.draw_line(start, end, paint);
            return;
        }

        // 获取虚线模式
        let pattern = match paint.dash_pattern() {
            Some(p) => p,
            None => {
                self.draw_line(start, end, paint);
                return;
            }
        };

        if pattern.is_empty() {
            self.draw_line(start, end, paint);
            return;
        }

        // 计算线段长度和方向
        let dx = end.x - start.x;
        let dy = end.y - start.y;
        let length = ((dx * dx + dy * dy) as f32).sqrt();

        if length == 0.0 {
            return;
        }

        // 计算单位方向向量
        let unit_dx = dx as f32 / length;
        let unit_dy = dy as f32 / length;

        // 遍历虚线模式绘制
        let mut current_pos = 0.0;
        let mut pattern_index = 0;
        let mut is_dash = true; // 开始是实线段

        while current_pos < length {
            let segment_length = pattern[pattern_index % pattern.len()];
            let next_pos = (current_pos + segment_length).min(length);

            if is_dash {
                // 绘制实线段
                let seg_start = Point::new(
                    start.x + (unit_dx * current_pos) as i32,
                    start.y + (unit_dy * current_pos) as i32,
                );
                let seg_end = Point::new(
                    start.x + (unit_dx * next_pos) as i32,
                    start.y + (unit_dy * next_pos) as i32,
                );
                self.draw_line(seg_start, seg_end, paint);
            }

            current_pos = next_pos;
            pattern_index += 1;
            is_dash = !is_dash; // 交替实线和间隙
        }
    }

    /// 绘制虚线矩形
    ///
    /// 根据 Paint 中的虚线样式绘制矩形边框。如果虚线样式为 Solid，则绘制实线矩形。
    ///
    /// # 参数
    ///
    /// * `rect` - 矩形区域
    /// * `paint` - 绘制样式（包含虚线模式）
    ///
    /// # 示例
    ///
    /// ```no_run
    /// use image_renderer::{Canvas, Color, Paint, Rect, paint::DashStyle};
    ///
    /// let mut canvas = Canvas::new(400, 300).unwrap();
    /// let mut paint = Paint::stroke(Color::RED, 2.0);
    /// paint.set_dash_style(DashStyle::DashDot);
    ///
    /// canvas.draw_dashed_rect(
    ///     Rect::new(50, 50, 300, 200),
    ///     &paint
    /// );
    /// ```
    pub fn draw_dashed_rect(&mut self, rect: Rect, paint: &Paint) {
        // 如果是实线，直接使用普通绘制
        if paint.dash_style().is_solid() {
            self.draw_rect(rect, paint);
            return;
        }

        // 绘制四条边
        // 上边
        self.draw_dashed_line(
            Point::new(rect.x, rect.y),
            Point::new(rect.x + rect.width as i32, rect.y),
            paint,
        );

        // 右边
        self.draw_dashed_line(
            Point::new(rect.x + rect.width as i32, rect.y),
            Point::new(rect.x + rect.width as i32, rect.y + rect.height as i32),
            paint,
        );

        // 下边
        self.draw_dashed_line(
            Point::new(rect.x + rect.width as i32, rect.y + rect.height as i32),
            Point::new(rect.x, rect.y + rect.height as i32),
            paint,
        );

        // 左边
        self.draw_dashed_line(
            Point::new(rect.x, rect.y + rect.height as i32),
            Point::new(rect.x, rect.y),
            paint,
        );
    }

    /// 绘制虚线圆角矩形
    ///
    /// 根据 Paint 中的虚线样式绘制圆角矩形边框。如果虚线样式为 Solid，则绘制实线圆角矩形。
    ///
    /// # 参数
    ///
    /// * `rect` - 矩形区域
    /// * `radius` - 圆角半径
    /// * `paint` - 绘制样式（包含虚线模式）
    ///
    /// # 示例
    ///
    /// ```no_run
    /// use image_renderer::{Canvas, Color, Paint, Rect, paint::DashStyle};
    ///
    /// let mut canvas = Canvas::new(400, 300).unwrap();
    /// let mut paint = Paint::stroke(Color::BLUE, 2.0);
    /// paint.set_dash_style(DashStyle::ShortDash);
    ///
    /// canvas.draw_dashed_rounded_rect(
    ///     Rect::new(50, 50, 300, 200),
    ///     20.0,
    ///     &paint
    /// );
    /// ```
    pub fn draw_dashed_rounded_rect(&mut self, rect: Rect, radius: f32, paint: &Paint) {
        // 限制圆角半径
        let r = radius.min((rect.width as f32 / 2.0).min(rect.height as f32 / 2.0));

        if r <= 0.0 {
            self.draw_dashed_rect(rect, paint);
            return;
        }

        // 如果是实线，使用普通圆角矩形绘制
        if paint.dash_style().is_solid() {
            self.draw_rounded_rect(rect, r, paint);
            return;
        }

        // 绘制四条直边（虚线）
        // 上边
        self.draw_dashed_line(
            Point::new(rect.x + r as i32, rect.y),
            Point::new(rect.x + rect.width as i32 - r as i32, rect.y),
            paint,
        );

        // 右边
        self.draw_dashed_line(
            Point::new(rect.x + rect.width as i32, rect.y + r as i32),
            Point::new(
                rect.x + rect.width as i32,
                rect.y + rect.height as i32 - r as i32,
            ),
            paint,
        );

        // 下边
        self.draw_dashed_line(
            Point::new(
                rect.x + rect.width as i32 - r as i32,
                rect.y + rect.height as i32,
            ),
            Point::new(rect.x + r as i32, rect.y + rect.height as i32),
            paint,
        );

        // 左边
        self.draw_dashed_line(
            Point::new(rect.x, rect.y + rect.height as i32 - r as i32),
            Point::new(rect.x, rect.y + r as i32),
            paint,
        );

        // 绘制四个圆角（虚线弧）
        // 左上角
        self.draw_dashed_arc(
            Point::new(rect.x + r as i32, rect.y + r as i32),
            r,
            180.0,
            270.0,
            paint,
        );

        // 右上角
        self.draw_dashed_arc(
            Point::new(rect.x + rect.width as i32 - r as i32, rect.y + r as i32),
            r,
            270.0,
            360.0,
            paint,
        );

        // 右下角
        self.draw_dashed_arc(
            Point::new(
                rect.x + rect.width as i32 - r as i32,
                rect.y + rect.height as i32 - r as i32,
            ),
            r,
            0.0,
            90.0,
            paint,
        );

        // 左下角
        self.draw_dashed_arc(
            Point::new(rect.x + r as i32, rect.y + rect.height as i32 - r as i32),
            r,
            90.0,
            180.0,
            paint,
        );
    }

    /// 绘制虚线圆弧
    ///
    /// 根据 Paint 中的虚线样式绘制圆弧。
    ///
    /// # 参数
    ///
    /// * `center` - 圆心
    /// * `radius` - 半径
    /// * `start_angle` - 起始角度（度数，0度为3点钟方向）
    /// * `end_angle` - 结束角度（度数）
    /// * `paint` - 绘制样式（包含虚线模式）
    fn draw_dashed_arc(
        &mut self,
        center: Point,
        radius: f32,
        start_angle: f32,
        end_angle: f32,
        paint: &Paint,
    ) {
        // 获取虚线模式
        let pattern = match paint.dash_pattern() {
            Some(p) if !p.is_empty() => p,
            _ => {
                // 如果没有虚线模式，绘制实线弧
                self.draw_arc_solid(center, radius, start_angle, end_angle, paint);
                return;
            }
        };

        // 计算弧长
        let angle_range = (end_angle - start_angle).abs();
        let arc_length = (angle_range.to_radians() * radius) as f32;

        if arc_length <= 0.0 {
            return;
        }

        // 沿着弧线绘制虚线
        let mut current_length = 0.0;
        let mut pattern_index = 0;
        let mut is_dash = true;

        while current_length < arc_length {
            let segment_length = pattern[pattern_index % pattern.len()];
            let next_length = (current_length + segment_length).min(arc_length);

            if is_dash {
                // 计算起始和结束角度
                let seg_start_angle = start_angle + (current_length / arc_length) * angle_range;
                let seg_end_angle = start_angle + (next_length / arc_length) * angle_range;

                // 绘制弧段
                self.draw_arc_segment(center, radius, seg_start_angle, seg_end_angle, paint);
            }

            current_length = next_length;
            pattern_index += 1;
            is_dash = !is_dash;
        }
    }

    /// 绘制实线圆弧段
    fn draw_arc_solid(
        &mut self,
        center: Point,
        radius: f32,
        start_angle: f32,
        end_angle: f32,
        paint: &Paint,
    ) {
        self.draw_arc_segment(center, radius, start_angle, end_angle, paint);
    }

    /// 绘制圆弧段（使用点连线）
    fn draw_arc_segment(
        &mut self,
        center: Point,
        radius: f32,
        start_angle: f32,
        end_angle: f32,
        paint: &Paint,
    ) {
        // 计算需要的点数（极高密度以获得抗锯齿效果）
        // 使用超精细计算：通过极高的点密度模拟抗锯齿
        let angle_range = (end_angle - start_angle).abs();
        let arc_length = angle_range.to_radians() * radius;

        // 使用极高的点密度来模拟抗锯齿效果
        // 每0.25像素一个点，确保圆弧足够平滑
        let points_per_pixel = 4.0; // 每像素4个点
        let num_points = (arc_length * points_per_pixel)
            .ceil()
            .max(angle_range * 2.0)
            .max(10.0) as i32;

        // 生成弧线上的点
        let mut points = Vec::new();
        for i in 0..=num_points {
            let t = i as f32 / num_points as f32;
            let angle = start_angle + t * (end_angle - start_angle);
            let rad = angle.to_radians();

            let x = center.x + (radius * rad.cos()) as i32;
            let y = center.y + (radius * rad.sin()) as i32;
            points.push(Point::new(x, y));
        }

        // 使用线段连接点，保持线宽一致
        for i in 0..points.len() - 1 {
            self.draw_line(points[i], points[i + 1], paint);
        }
    }

    /// 绘制自定义边框的矩形（支持每条边独立配置，每个角独立圆角）
    ///
    /// # 参数
    ///
    /// * `rect` - 矩形区域
    /// * `border` - 边框配置（每条边可独立设置颜色、线宽、虚线样式）
    /// * `radius` - 圆角配置（每个角可独立设置圆角半径）
    ///
    /// # 示例
    ///
    /// ```no_run
    /// use image_renderer::{Canvas, Color, Border, BorderSide, BorderRadius, DashStyle, Rect};
    ///
    /// let mut canvas = Canvas::new(400, 300).unwrap();
    ///
    /// // 创建不同样式的边框
    /// let border = Border::new(
    ///     BorderSide::solid(Color::RED, 2.0),           // 上边：红色实线
    ///     BorderSide::dashed(Color::BLUE, 3.0, DashStyle::ShortDash), // 右边：蓝色虚线
    ///     BorderSide::solid(Color::GREEN, 2.0),         // 下边：绿色实线
    ///     BorderSide::dashed(Color::YELLOW, 3.0, DashStyle::Dot),     // 左边：黄色点线
    /// );
    ///
    /// // 创建不同的圆角
    /// let radius = BorderRadius::new(20.0, 10.0, 5.0, 15.0);
    ///
    /// let rect = Rect::new(50, 50, 300, 200);
    /// canvas.draw_custom_border_rect(rect, &border, &radius);
    /// ```
    pub fn draw_custom_border_rect(
        &mut self,
        rect: Rect,
        border: &crate::border::Border,
        radius: &crate::border::BorderRadius,
    ) {
        // 限制圆角半径在合理范围内
        let radius = radius.clamp(rect.width as f32, rect.height as f32);

        // 如果所有圆角都是0，使用简化的直角矩形绘制
        if radius.is_zero() {
            self.draw_custom_border_rect_no_radius(rect, border);
            return;
        }

        // 绘制四条边（考虑圆角）
        // 上边：从左上圆角结束到右上圆角开始
        if border.top.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.top.color, border.top.width);
            paint.set_dash_style(border.top.dash_style.clone());

            let start = Point::new(rect.x + radius.top_left as i32, rect.y);
            let end = Point::new(rect.x + rect.width as i32 - radius.top_right as i32, rect.y);
            self.draw_dashed_line(start, end, &paint);
        }

        // 右边：从右上圆角结束到右下圆角开始
        if border.right.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.right.color, border.right.width);
            paint.set_dash_style(border.right.dash_style.clone());

            let start = Point::new(rect.x + rect.width as i32, rect.y + radius.top_right as i32);
            let end = Point::new(
                rect.x + rect.width as i32,
                rect.y + rect.height as i32 - radius.bottom_right as i32,
            );
            self.draw_dashed_line(start, end, &paint);
        }

        // 下边：从右下圆角结束到左下圆角开始
        if border.bottom.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.bottom.color, border.bottom.width);
            paint.set_dash_style(border.bottom.dash_style.clone());

            let start = Point::new(
                rect.x + rect.width as i32 - radius.bottom_right as i32,
                rect.y + rect.height as i32,
            );
            let end = Point::new(
                rect.x + radius.bottom_left as i32,
                rect.y + rect.height as i32,
            );
            self.draw_dashed_line(start, end, &paint);
        }

        // 左边：从左下圆角结束到左上圆角开始
        if border.left.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.left.color, border.left.width);
            paint.set_dash_style(border.left.dash_style.clone());

            let start = Point::new(
                rect.x,
                rect.y + rect.height as i32 - radius.bottom_left as i32,
            );
            let end = Point::new(rect.x, rect.y + radius.top_left as i32);
            self.draw_dashed_line(start, end, &paint);
        }

        // 绘制四个圆角
        // 左上角 (180° 到 270°)
        if radius.top_left > 0.0 {
            // 使用上边和左边的平均样式绘制圆角
            let corner_border = self.blend_corner_style(&border.top, &border.left);
            let mut paint = crate::Paint::stroke(corner_border.color, corner_border.width);
            paint.set_dash_style(corner_border.dash_style);

            self.draw_dashed_arc(
                Point::new(
                    rect.x + radius.top_left as i32,
                    rect.y + radius.top_left as i32,
                ),
                radius.top_left,
                180.0,
                270.0,
                &paint,
            );
        }

        // 右上角 (270° 到 360°)
        if radius.top_right > 0.0 {
            let corner_border = self.blend_corner_style(&border.top, &border.right);
            let mut paint = crate::Paint::stroke(corner_border.color, corner_border.width);
            paint.set_dash_style(corner_border.dash_style);

            self.draw_dashed_arc(
                Point::new(
                    rect.x + rect.width as i32 - radius.top_right as i32,
                    rect.y + radius.top_right as i32,
                ),
                radius.top_right,
                270.0,
                360.0,
                &paint,
            );
        }

        // 右下角 (0° 到 90°)
        if radius.bottom_right > 0.0 {
            let corner_border = self.blend_corner_style(&border.right, &border.bottom);
            let mut paint = crate::Paint::stroke(corner_border.color, corner_border.width);
            paint.set_dash_style(corner_border.dash_style);

            self.draw_dashed_arc(
                Point::new(
                    rect.x + rect.width as i32 - radius.bottom_right as i32,
                    rect.y + rect.height as i32 - radius.bottom_right as i32,
                ),
                radius.bottom_right,
                0.0,
                90.0,
                &paint,
            );
        }

        // 左下角 (90° 到 180°)
        if radius.bottom_left > 0.0 {
            let corner_border = self.blend_corner_style(&border.bottom, &border.left);
            let mut paint = crate::Paint::stroke(corner_border.color, corner_border.width);
            paint.set_dash_style(corner_border.dash_style);

            self.draw_dashed_arc(
                Point::new(
                    rect.x + radius.bottom_left as i32,
                    rect.y + rect.height as i32 - radius.bottom_left as i32,
                ),
                radius.bottom_left,
                90.0,
                180.0,
                &paint,
            );
        }
    }

    /// 绘制无圆角的自定义边框矩形
    fn draw_custom_border_rect_no_radius(&mut self, rect: Rect, border: &crate::border::Border) {
        // 上边
        if border.top.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.top.color, border.top.width);
            paint.set_dash_style(border.top.dash_style.clone());
            self.draw_dashed_line(
                Point::new(rect.x, rect.y),
                Point::new(rect.x + rect.width as i32, rect.y),
                &paint,
            );
        }

        // 右边
        if border.right.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.right.color, border.right.width);
            paint.set_dash_style(border.right.dash_style.clone());
            self.draw_dashed_line(
                Point::new(rect.x + rect.width as i32, rect.y),
                Point::new(rect.x + rect.width as i32, rect.y + rect.height as i32),
                &paint,
            );
        }

        // 下边
        if border.bottom.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.bottom.color, border.bottom.width);
            paint.set_dash_style(border.bottom.dash_style.clone());
            self.draw_dashed_line(
                Point::new(rect.x + rect.width as i32, rect.y + rect.height as i32),
                Point::new(rect.x, rect.y + rect.height as i32),
                &paint,
            );
        }

        // 左边
        if border.left.width > 0.0 {
            let mut paint = crate::Paint::stroke(border.left.color, border.left.width);
            paint.set_dash_style(border.left.dash_style.clone());
            self.draw_dashed_line(
                Point::new(rect.x, rect.y + rect.height as i32),
                Point::new(rect.x, rect.y),
                &paint,
            );
        }
    }

    /// 混合两条边的样式用于圆角（取平均值）
    fn blend_corner_style(
        &self,
        side1: &crate::border::BorderSide,
        side2: &crate::border::BorderSide,
    ) -> crate::border::BorderSide {
        // 如果其中一条边宽度为0，使用另一条
        if side1.width == 0.0 {
            return side2.clone();
        }
        if side2.width == 0.0 {
            return side1.clone();
        }

        // 混合颜色（简单平均）
        let color = crate::Color::rgba(
            ((side1.color.r as u16 + side2.color.r as u16) / 2) as u8,
            ((side1.color.g as u16 + side2.color.g as u16) / 2) as u8,
            ((side1.color.b as u16 + side2.color.b as u16) / 2) as u8,
            ((side1.color.a as u16 + side2.color.a as u16) / 2) as u8,
        );

        // 混合线宽（取平均）
        let width = (side1.width + side2.width) / 2.0;

        // 虚线样式：优先使用第一条边的样式
        let dash_style = side1.dash_style.clone();

        crate::border::BorderSide::new(color, width, dash_style)
    }

    // ==================== 路径绘制方法 ====================

    /// 绘制路径
    ///
    /// 根据 Paint 的样式绘制路径（填充或描边）
    ///
    /// # 参数
    ///
    /// * `path` - 要绘制的路径
    /// * `paint` - 绘制样式
    pub fn draw_path(&mut self, path: &Path, paint: &Paint) {
        // 应用当前变换矩阵
        let transformed_path = path.transform(&self.current_matrix);

        match paint.style() {
            PaintStyle::Fill | PaintStyle::FillAndStroke => {
                self.fill_path(&transformed_path, paint);
            }
            PaintStyle::Stroke => {
                self.stroke_path(&transformed_path, paint);
            }
        }
    }

    /// 填充路径
    fn fill_path(&mut self, path: &Path, paint: &Paint) {
        let color = paint.color().to_rgba();

        // 获取路径的边界框
        if let Some(bounds) = path.bounds() {
            // 遍历边界框内的每个像素，判断是否在路径内
            for y in bounds.y..(bounds.y + bounds.height as i32) {
                for x in bounds.x..(bounds.x + bounds.width as i32) {
                    if path.contains(x as f32, y as f32) {
                        if x >= 0 && y >= 0 && x < self.width() as i32 && y < self.height() as i32 {
                            // 检查裁剪
                            if self.clip_stack.contains_point(x, y) {
                                self.surface.put_pixel(x as u32, y as u32, color);
                            }
                        }
                    }
                }
            }
        }
    }

    /// 描边路径
    fn stroke_path(&mut self, path: &Path, paint: &Paint) {
        // 简化实现：将路径转换为线段序列并绘制
        let commands = path.commands();
        let mut current_point = None;

        for cmd in commands {
            match cmd {
                crate::path::PathCommand::MoveTo(p) => {
                    current_point = Some(*p);
                }
                crate::path::PathCommand::LineTo(p) => {
                    if let Some(start) = current_point {
                        self.draw_line(
                            Point::new(start.x as i32, start.y as i32),
                            Point::new(p.x as i32, p.y as i32),
                            paint,
                        );
                    }
                    current_point = Some(*p);
                }
                crate::path::PathCommand::QuadTo { control, end } => {
                    if let Some(start) = current_point {
                        // 使用多段线近似二次贝塞尔曲线
                        self.draw_quad_bezier(start, *control, *end, paint);
                    }
                    current_point = Some(*end);
                }
                crate::path::PathCommand::CubicTo {
                    control1,
                    control2,
                    end,
                } => {
                    if let Some(start) = current_point {
                        // 使用多段线近似三次贝塞尔曲线
                        self.draw_cubic_bezier(start, *control1, *control2, *end, paint);
                    }
                    current_point = Some(*end);
                }
                crate::path::PathCommand::ArcTo { .. } => {
                    // 圆弧绘制的简化实现
                    // 在实际应用中需要更复杂的实现
                }
                crate::path::PathCommand::Close => {
                    // 闭合路径
                }
            }
        }
    }

    /// 绘制二次贝塞尔曲线
    fn draw_quad_bezier(
        &mut self,
        start: crate::point::PointF,
        control: crate::point::PointF,
        end: crate::point::PointF,
        paint: &Paint,
    ) {
        let steps = 20;
        let mut prev = start;

        for i in 1..=steps {
            let t = i as f32 / steps as f32;
            let t2 = t * t;
            let mt = 1.0 - t;
            let mt2 = mt * mt;

            let x = mt2 * start.x + 2.0 * mt * t * control.x + t2 * end.x;
            let y = mt2 * start.y + 2.0 * mt * t * control.y + t2 * end.y;

            let curr = crate::point::PointF { x, y };
            self.draw_line(
                Point::new(prev.x as i32, prev.y as i32),
                Point::new(curr.x as i32, curr.y as i32),
                paint,
            );
            prev = curr;
        }
    }

    /// 绘制三次贝塞尔曲线
    fn draw_cubic_bezier(
        &mut self,
        start: crate::point::PointF,
        control1: crate::point::PointF,
        control2: crate::point::PointF,
        end: crate::point::PointF,
        paint: &Paint,
    ) {
        let steps = 30;
        let mut prev = start;

        for i in 1..=steps {
            let t = i as f32 / steps as f32;
            let t2 = t * t;
            let t3 = t2 * t;
            let mt = 1.0 - t;
            let mt2 = mt * mt;
            let mt3 = mt2 * mt;

            let x = mt3 * start.x
                + 3.0 * mt2 * t * control1.x
                + 3.0 * mt * t2 * control2.x
                + t3 * end.x;
            let y = mt3 * start.y
                + 3.0 * mt2 * t * control1.y
                + 3.0 * mt * t2 * control2.y
                + t3 * end.y;

            let curr = crate::point::PointF { x, y };
            self.draw_line(
                Point::new(prev.x as i32, prev.y as i32),
                Point::new(curr.x as i32, curr.y as i32),
                paint,
            );
            prev = curr;
        }
    }

    // ==================== 变换方法 ====================

    /// 平移变换
    ///
    /// 将后续的绘制操作沿 x 和 y 方向平移
    ///
    /// # 参数
    ///
    /// * `dx` - x 方向的平移量
    /// * `dy` - y 方向的平移量
    pub fn translate(&mut self, dx: f32, dy: f32) {
        self.current_matrix = self.current_matrix.pre_translate(dx, dy);
    }

    /// 缩放变换
    ///
    /// 将后续的绘制操作进行缩放
    ///
    /// # 参数
    ///
    /// * `sx` - x 方向的缩放因子
    /// * `sy` - y 方向的缩放因子
    pub fn scale(&mut self, sx: f32, sy: f32) {
        self.current_matrix = self.current_matrix.pre_scale(sx, sy);
    }

    /// 旋转变换
    ///
    /// 将后续的绘制操作绕原点旋转指定角度
    ///
    /// # 参数
    ///
    /// * `degrees` - 旋转角度（度数）
    pub fn rotate(&mut self, degrees: f32) {
        self.current_matrix = self.current_matrix.pre_rotate(degrees);
    }

    /// 绕指定点旋转
    ///
    /// # 参数
    ///
    /// * `degrees` - 旋转角度（度数）
    /// * `px` - 旋转中心的 x 坐标
    /// * `py` - 旋转中心的 y 坐标
    pub fn rotate_around(&mut self, degrees: f32, px: f32, py: f32) {
        self.translate(px, py);
        self.rotate(degrees);
        self.translate(-px, -py);
    }

    /// 设置变换矩阵
    ///
    /// 直接设置当前的变换矩阵
    ///
    /// # 参数
    ///
    /// * `matrix` - 新的变换矩阵
    pub fn set_matrix(&mut self, matrix: &Matrix) {
        self.current_matrix = *matrix;
    }

    /// 获取当前变换矩阵
    pub fn get_matrix(&self) -> &Matrix {
        &self.current_matrix
    }

    /// 连接变换矩阵
    ///
    /// 将指定矩阵与当前矩阵相乘
    ///
    /// # 参数
    ///
    /// * `matrix` - 要连接的矩阵
    pub fn concat(&mut self, matrix: &Matrix) {
        self.current_matrix = self.current_matrix.post_concat(matrix);
    }

    /// 重置变换矩阵为单位矩阵
    pub fn reset_matrix(&mut self) {
        self.current_matrix = Matrix::identity();
    }

    // ==================== 状态保存和恢复 ====================

    /// 保存当前的绘制状态
    ///
    /// 将当前的变换矩阵和裁剪区域压入状态栈
    pub fn save(&mut self) {
        let state = CanvasState {
            matrix: self.current_matrix,
            clip_rect: self.clip_stack.get_bounds(),
        };
        self.state_stack.push(state);
        self.clip_stack.save();
    }

    /// 恢复之前保存的绘制状态
    ///
    /// 从状态栈中弹出并恢复变换矩阵和裁剪区域
    pub fn restore(&mut self) {
        if let Some(state) = self.state_stack.pop() {
            self.current_matrix = state.matrix;
            self.clip_stack.restore();
        }
    }

    /// 获取当前保存的状态层数
    pub fn get_save_count(&self) -> usize {
        self.state_stack.len()
    }

    /// 恢复到指定的保存层级
    ///
    /// # 参数
    ///
    /// * `count` - 目标层级数
    pub fn restore_to_count(&mut self, count: usize) {
        while self.state_stack.len() > count {
            self.restore();
        }
    }

    // ==================== 裁剪方法 ====================

    /// 矩形裁剪
    ///
    /// 将绘制区域限制在指定的矩形内
    ///
    /// # 参数
    ///
    /// * `rect` - 裁剪矩形
    /// * `op` - 裁剪操作（相交或差集）
    pub fn clip_rect(&mut self, rect: Rect, op: ClipOp) {
        // 应用当前变换到裁剪矩形
        let transformed_rect = self.transform_rect(rect);
        self.clip_stack.clip_rect(transformed_rect, op);
    }

    /// 路径裁剪
    ///
    /// 将绘制区域限制在指定的路径内
    ///
    /// # 参数
    ///
    /// * `path` - 裁剪路径
    /// * `op` - 裁剪操作（相交或差集）
    pub fn clip_path(&mut self, path: &Path, op: ClipOp) {
        // 应用当前变换到裁剪路径
        let transformed_path = path.transform(&self.current_matrix);
        self.clip_stack.clip_path(transformed_path, op);
    }

    /// 获取当前裁剪区域的边界
    pub fn get_clip_bounds(&self) -> Option<Rect> {
        self.clip_stack.get_bounds()
    }

    /// 检查点是否在裁剪区域内
    pub fn is_clipped(&self, x: i32, y: i32) -> bool {
        !self.clip_stack.contains_point(x, y)
    }

    // ==================== 辅助方法 ====================

    /// 应用变换到矩形
    fn transform_rect(&self, rect: Rect) -> Rect {
        let (x1, y1) = self.current_matrix.map_point(rect.x as f32, rect.y as f32);
        let (x2, y2) = self.current_matrix.map_point(
            (rect.x + rect.width as i32) as f32,
            (rect.y + rect.height as i32) as f32,
        );

        Rect::new(
            x1 as i32,
            y1 as i32,
            (x2 - x1).abs() as u32,
            (y2 - y1).abs() as u32,
        )
    }
}