thorvg 0.5.0

//! Paints, transforms, and the shared [`Paint`] trait.
//!
//! Wraps the [`ThorVG` C API](https://www.thorvg.org/c-native).

use crate::error::{Error, Result};
use crate::shape::Shape;
use thorvg_sys as sys;

/// A 3×3 affine transformation matrix.
///
/// The layout is row-major and matches thorvg's `Tvg_Matrix`:
///
/// ```text
/// | e11 e12 e13 |
/// | e21 e22 e23 |
/// | e31 e32 e33 |
/// ```
///
/// It transforms a column vector `[x y 1]ᵀ`, so:
/// - `e11`, `e12`, `e21`, `e22` form the rotation/scale block.
/// - `e13`, `e23` hold the x and y **translation** (third column,
///   not the bottom row).
/// - `e31`, `e32` are `0` and `e33` is `1` for a well-formed affine
///   transform; see [`IDENTITY`](Self::IDENTITY).
///
/// Note: `PartialEq` uses exact floating-point comparison.
/// Use approximate comparison for transformed values.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Matrix {
    pub e11: f32,
    pub e12: f32,
    pub e13: f32,
    pub e21: f32,
    pub e22: f32,
    pub e23: f32,
    pub e31: f32,
    pub e32: f32,
    pub e33: f32,
}

impl Matrix {
    /// The identity matrix.
    pub const IDENTITY: Self = Self {
        e11: 1.0,
        e12: 0.0,
        e13: 0.0,
        e21: 0.0,
        e22: 1.0,
        e23: 0.0,
        e31: 0.0,
        e32: 0.0,
        e33: 1.0,
    };

    /// Row-major 3×3 multiply: `self × rhs`, matching thorvg's
    /// `operator*` (tvgMath.cpp). The combinators build the new
    /// operation as the left operand so it applies *after* `self`.
    #[must_use]
    fn multiply(self, rhs: Matrix) -> Matrix {
        Matrix {
            e11: self.e11 * rhs.e11 + self.e12 * rhs.e21 + self.e13 * rhs.e31,
            e12: self.e11 * rhs.e12 + self.e12 * rhs.e22 + self.e13 * rhs.e32,
            e13: self.e11 * rhs.e13 + self.e12 * rhs.e23 + self.e13 * rhs.e33,
            e21: self.e21 * rhs.e11 + self.e22 * rhs.e21 + self.e23 * rhs.e31,
            e22: self.e21 * rhs.e12 + self.e22 * rhs.e22 + self.e23 * rhs.e32,
            e23: self.e21 * rhs.e13 + self.e22 * rhs.e23 + self.e23 * rhs.e33,
            e31: self.e31 * rhs.e11 + self.e32 * rhs.e21 + self.e33 * rhs.e31,
            e32: self.e31 * rhs.e12 + self.e32 * rhs.e22 + self.e33 * rhs.e32,
            e33: self.e31 * rhs.e13 + self.e32 * rhs.e23 + self.e33 * rhs.e33,
        }
    }

    /// Returns `self` with a translation applied after it.
    ///
    /// Combinators chain in reading order: `m.translate(..).rotate(..)`
    /// translates first, then rotates. Note this is *true* matrix
    /// composition — unlike thorvg's incremental [`Paint::translate`],
    /// which always keeps the translation outermost. Build the matrix
    /// here and hand it to `set_transform` for full control.
    #[must_use]
    pub fn translate(self, x: f32, y: f32) -> Matrix {
        Matrix {
            e13: x,
            e23: y,
            ..Matrix::IDENTITY
        }
        .multiply(self)
    }

    /// Returns `self` with a (possibly non-uniform) scale applied after
    /// it. `Paint::scale` only does uniform scaling; this allows `sx != sy`.
    #[must_use]
    pub fn scale(self, sx: f32, sy: f32) -> Matrix {
        Matrix {
            e11: sx,
            e22: sy,
            ..Matrix::IDENTITY
        }
        .multiply(self)
    }

    /// Returns `self` with a rotation applied after it. `degrees`
    /// matches the unit of [`Paint::rotate`].
    #[must_use]
    pub fn rotate(self, degrees: f32) -> Matrix {
        let r = degrees.to_radians();
        let (s, c) = (libm::sinf(r), libm::cosf(r));
        Matrix {
            e11: c,
            e12: -s,
            e21: s,
            e22: c,
            ..Matrix::IDENTITY
        }
        .multiply(self)
    }

    fn to_raw(self) -> sys::Tvg_Matrix {
        sys::Tvg_Matrix {
            e11: self.e11,
            e12: self.e12,
            e13: self.e13,
            e21: self.e21,
            e22: self.e22,
            e23: self.e23,
            e31: self.e31,
            e32: self.e32,
            e33: self.e33,
        }
    }

    fn from_raw(m: sys::Tvg_Matrix) -> Self {
        Self {
            e11: m.e11,
            e12: m.e12,
            e13: m.e13,
            e21: m.e21,
            e22: m.e22,
            e23: m.e23,
            e31: m.e31,
            e32: m.e32,
            e33: m.e33,
        }
    }
}

impl Default for Matrix {
    /// The identity matrix; see [`Matrix::IDENTITY`].
    fn default() -> Self {
        Self::IDENTITY
    }
}

/// A point in 2D space.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Point {
    /// X coordinate.
    pub x: f32,
    /// Y coordinate.
    pub y: f32,
}

impl Point {
    /// Builds a [`Point`] from its coordinates.
    #[must_use]
    pub const fn new(x: f32, y: f32) -> Self {
        Self { x, y }
    }
}

/// Blending method for compositing paint objects.
///
/// Covers thorvg's user-facing blend modes (`Tvg_Blend_Method`
/// `NORMAL`..=`ADD`). The C enum's `TVG_BLEND_METHOD_COMPOSITION`
/// (= 255) is deliberately omitted: it is an internal value the engine
/// uses for intermediate composition, not a mode callers select. Blend
/// is write-only in the C API (there is no `tvg_paint_get_blend_method`),
/// so the engine never hands a value back that would need mapping here —
/// hence this enum has only `to_raw` and no `from_raw`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
#[non_exhaustive]
pub enum BlendMethod {
    /// Source is drawn over the destination (the default, no blending).
    Normal = 0,
    /// Multiplies source and destination — always darkens.
    Multiply,
    /// Inverse-multiplies — always lightens.
    Screen,
    /// `Multiply` in dark areas, `Screen` in light areas.
    Overlay,
    /// Keeps the darker of source and destination per channel.
    Darken,
    /// Keeps the lighter of source and destination per channel.
    Lighten,
    /// Brightens the destination to reflect the source.
    ColorDodge,
    /// Darkens the destination to reflect the source.
    ColorBurn,
    /// `Overlay` with source and destination swapped.
    HardLight,
    /// A softer variant of `HardLight`.
    SoftLight,
    /// Absolute difference of source and destination per channel.
    Difference,
    /// Like `Difference` but with lower contrast.
    Exclusion,
    /// Hue of the source with destination saturation and luminosity.
    Hue,
    /// Saturation of the source with destination hue and luminosity.
    Saturation,
    /// Hue and saturation of the source with destination luminosity.
    Color,
    /// Luminosity of the source with destination hue and saturation.
    Luminosity,
    /// Additive blending — sums source and destination per channel.
    Add,
}

impl BlendMethod {
    fn to_raw(self) -> sys::Tvg_Blend_Method {
        match self {
            Self::Normal => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_NORMAL,
            Self::Multiply => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_MULTIPLY,
            Self::Screen => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_SCREEN,
            Self::Overlay => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_OVERLAY,
            Self::Darken => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_DARKEN,
            Self::Lighten => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_LIGHTEN,
            Self::ColorDodge => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_COLORDODGE,
            Self::ColorBurn => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_COLORBURN,
            Self::HardLight => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_HARDLIGHT,
            Self::SoftLight => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_SOFTLIGHT,
            Self::Difference => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_DIFFERENCE,
            Self::Exclusion => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_EXCLUSION,
            Self::Hue => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_HUE,
            Self::Saturation => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_SATURATION,
            Self::Color => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_COLOR,
            Self::Luminosity => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_LUMINOSITY,
            Self::Add => sys::Tvg_Blend_Method::TVG_BLEND_METHOD_ADD,
        }
    }
}

/// Masking method for combining two paint objects.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(u8)]
#[non_exhaustive]
pub enum MaskMethod {
    /// No masking applied.
    None = 0,
    /// Masks by the target's alpha channel.
    Alpha,
    /// Masks by the inverse of the target's alpha channel.
    InvAlpha,
    /// Masks by the target's luminance.
    Luma,
    /// Masks by the inverse of the target's luminance.
    InvLuma,
    /// Adds the target's coverage to the source.
    Add,
    /// Subtracts the target's coverage from the source.
    Subtract,
    /// Keeps only where source and target overlap.
    Intersect,
    /// Keeps the non-overlapping coverage of source and target.
    Difference,
    /// Keeps the lighter coverage of source and target.
    Lighten,
    /// Keeps the darker coverage of source and target.
    Darken,
}

impl MaskMethod {
    fn to_raw(self) -> sys::Tvg_Mask_Method {
        match self {
            Self::None => sys::Tvg_Mask_Method::TVG_MASK_METHOD_NONE,
            Self::Alpha => sys::Tvg_Mask_Method::TVG_MASK_METHOD_ALPHA,
            Self::InvAlpha => sys::Tvg_Mask_Method::TVG_MASK_METHOD_INVERSE_ALPHA,
            Self::Luma => sys::Tvg_Mask_Method::TVG_MASK_METHOD_LUMA,
            Self::InvLuma => sys::Tvg_Mask_Method::TVG_MASK_METHOD_INVERSE_LUMA,
            Self::Add => sys::Tvg_Mask_Method::TVG_MASK_METHOD_ADD,
            Self::Subtract => sys::Tvg_Mask_Method::TVG_MASK_METHOD_SUBTRACT,
            Self::Intersect => sys::Tvg_Mask_Method::TVG_MASK_METHOD_INTERSECT,
            Self::Difference => sys::Tvg_Mask_Method::TVG_MASK_METHOD_DIFFERENCE,
            Self::Lighten => sys::Tvg_Mask_Method::TVG_MASK_METHOD_LIGHTEN,
            Self::Darken => sys::Tvg_Mask_Method::TVG_MASK_METHOD_DARKEN,
        }
    }

    pub(crate) fn from_raw(m: sys::Tvg_Mask_Method) -> Self {
        match m {
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_ALPHA => Self::Alpha,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_INVERSE_ALPHA => Self::InvAlpha,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_LUMA => Self::Luma,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_INVERSE_LUMA => Self::InvLuma,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_ADD => Self::Add,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_SUBTRACT => Self::Subtract,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_INTERSECT => Self::Intersect,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_DIFFERENCE => Self::Difference,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_LIGHTEN => Self::Lighten,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_DARKEN => Self::Darken,
            sys::Tvg_Mask_Method::TVG_MASK_METHOD_NONE => Self::None,
        }
    }
}

/// A read-only borrow of a paint owned by another object.
///
/// Returned by getters that expose an internal paint handle whose
/// lifetime is governed by the containing object (e.g. the mask
/// target stored inside a `Paint::mask` relationship).  The `'a`
/// lifetime ties the borrow to the source: dropping the source
/// invalidates the borrow.
///
/// Read-only surface only — mutating the borrowed paint via raw
/// access would race with the owner.
pub struct BorrowedPaint<'a> {
    raw: sys::Tvg_Paint,
    _life: core::marker::PhantomData<&'a ()>,
}

impl BorrowedPaint<'_> {
    /// Wraps a raw handle as a read-only borrow.
    ///
    /// # Safety
    ///
    /// `raw` must be a valid paint handle whose owner outlives `'a`.
    pub(crate) unsafe fn from_raw(raw: sys::Tvg_Paint) -> Self {
        Self {
            raw,
            _life: core::marker::PhantomData,
        }
    }

    /// Returns the underlying raw handle.
    ///
    /// Intended for use with `thorvg-sys` C APIs not yet wrapped here; the
    /// `'a` lifetime keeps the borrow honest. Do not use it to mutate the
    /// paint — that would race with the owner.
    pub fn raw(&self) -> sys::Tvg_Paint {
        self.raw
    }

    /// Returns the runtime [`PaintType`] of the borrowed handle.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    pub fn paint_type(&self) -> Result<PaintType> {
        let mut t = sys::Tvg_Type::TVG_TYPE_UNDEF;
        Error::from_raw(unsafe { sys::tvg_paint_get_type(self.raw, &raw mut t) })?;
        Ok(PaintType::from_raw(t))
    }

    /// Returns the user-assigned id, or `0` if none was set.
    pub fn id(&self) -> u32 {
        unsafe { sys::tvg_paint_get_id(self.raw) }
    }

    /// Returns the opacity, in the range `0..=255`.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    pub fn opacity(&self) -> Result<u8> {
        let mut o: u8 = 0;
        Error::from_raw(unsafe { sys::tvg_paint_get_opacity(self.raw, &raw mut o) })?;
        Ok(o)
    }

    /// Returns the axis-aligned bounding box `(x, y, w, h)` in canvas space.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if the bounds cannot be
    /// computed (usually invalid path data), or [`Error::InvalidArguments`]
    /// if the underlying handle is invalid.
    pub fn bounds(&self) -> Result<(f32, f32, f32, f32)> {
        let (mut x, mut y, mut w, mut h) = (0f32, 0f32, 0f32, 0f32);
        Error::from_raw(unsafe {
            sys::tvg_paint_get_aabb(self.raw, &raw mut x, &raw mut y, &raw mut w, &raw mut h)
        })?;
        Ok((x, y, w, h))
    }
}

impl core::fmt::Debug for BorrowedPaint<'_> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("BorrowedPaint").finish_non_exhaustive()
    }
}

/// The concrete type of a paint object.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum PaintType {
    /// Unknown or unset type.
    Undefined,
    /// A [`Shape`](crate::Shape).
    Shape,
    /// A [`Scene`](crate::Scene).
    Scene,
    /// A [`Picture`](crate::Picture).
    Picture,
    /// A [`Text`](crate::Text).
    Text,
    /// A [`LinearGradient`](crate::LinearGradient).
    LinearGradient,
    /// A [`RadialGradient`](crate::RadialGradient).
    RadialGradient,
}

impl PaintType {
    pub(crate) fn from_raw(t: sys::Tvg_Type) -> Self {
        match t {
            sys::Tvg_Type::TVG_TYPE_SHAPE => Self::Shape,
            sys::Tvg_Type::TVG_TYPE_SCENE => Self::Scene,
            sys::Tvg_Type::TVG_TYPE_PICTURE => Self::Picture,
            sys::Tvg_Type::TVG_TYPE_TEXT => Self::Text,
            sys::Tvg_Type::TVG_TYPE_LINEAR_GRAD => Self::LinearGradient,
            sys::Tvg_Type::TVG_TYPE_RADIAL_GRAD => Self::RadialGradient,
            sys::Tvg_Type::TVG_TYPE_UNDEF => Self::Undefined,
        }
    }
}

/// Sealed-trait marker.
///
/// `Paint::raw`/`into_raw`/`from_raw_paint` move opaque `ThorVG`
/// pointers across the FFI boundary without any further validation;
/// allowing downstream crates to implement [`Paint`] would let safe
/// code hand bogus pointers to `tvg_canvas_add` etc.  The supertrait
/// bound on [`sealed::Sealed`] makes the trait closed.
pub(crate) mod sealed {
    pub trait Sealed {}
}

/// Common trait for all paint objects (Shape, Scene, Picture, Text).
///
/// Paint represents a graphical element that can be added to a canvas
/// with transformations, opacity, masking, and clipping.
///
/// This trait is **sealed**: only types defined in this crate may
/// implement it.
pub trait Paint: sealed::Sealed {
    /// Returns the underlying raw `Tvg_Paint` handle without transferring
    /// ownership.
    fn raw(&self) -> sys::Tvg_Paint;

    /// Consumes `self` and returns the raw handle, transferring ownership.
    ///
    /// The caller becomes responsible for the handle; the Rust `Drop` that
    /// would otherwise free it is suppressed.
    fn into_raw(self) -> sys::Tvg_Paint;

    /// Sets the opacity, where `0` is fully transparent and `255` is fully
    /// opaque.
    ///
    /// Changing the opacity can force the engine into a multi-pass
    /// composition, so prefer leaving it unchanged on hot paths.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn set_opacity(&mut self, opacity: u8) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_set_opacity(self.raw(), opacity) })
    }

    /// Returns the opacity, in the range `0..=255`.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn opacity(&self) -> Result<u8> {
        let mut opacity: u8 = 0;
        Error::from_raw(unsafe { sys::tvg_paint_get_opacity(self.raw(), &raw mut opacity) })?;
        Ok(opacity)
    }

    /// Sets whether the paint is rendered.
    ///
    /// A hidden paint is excluded from the rendered output but is not
    /// deactivated: it may still be processed during updates. To remove it
    /// entirely, take it off the canvas instead.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn set_visible(&mut self, visible: bool) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_set_visible(self.raw(), visible) })
    }

    /// Returns `true` if the paint is rendered.
    fn visible(&self) -> bool {
        unsafe { sys::tvg_paint_get_visible(self.raw()) }
    }

    /// Scales the paint uniformly by `factor`.
    ///
    /// This is an incremental helper layered on the paint's transform; for
    /// non-uniform scaling build a [`Matrix`] and pass it to
    /// [`set_transform`](Paint::set_transform).
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if a custom transform has
    /// already been set via [`set_transform`](Paint::set_transform), or
    /// [`Error::InvalidArguments`] if the underlying handle is invalid.
    fn scale(&mut self, factor: f32) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_scale(self.raw(), factor) })
    }

    /// Rotates the paint by `degree` degrees, clockwise about the origin.
    ///
    /// The rotation axis passes through the object's local origin `(0, 0)`.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if a custom transform has
    /// already been set via [`set_transform`](Paint::set_transform), or
    /// [`Error::InvalidArguments`] if the underlying handle is invalid.
    fn rotate(&mut self, degree: f32) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_rotate(self.raw(), degree) })
    }

    /// Translates the paint by `(x, y)`.
    ///
    /// The coordinate origin is the upper-left corner of the canvas, with
    /// `x` increasing right and `y` increasing down.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if a custom transform has
    /// already been set via [`set_transform`](Paint::set_transform), or
    /// [`Error::InvalidArguments`] if the underlying handle is invalid.
    fn translate(&mut self, x: f32, y: f32) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_translate(self.raw(), x, y) })
    }

    /// Sets the affine transformation matrix, replacing any prior transform.
    ///
    /// Unlike [`scale`](Paint::scale), [`rotate`](Paint::rotate), and
    /// [`translate`](Paint::translate) — which the engine rejects once a
    /// custom transform exists — this overwrites the transform outright.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn set_transform(&mut self, m: &Matrix) -> Result<()> {
        let raw_m = m.to_raw();
        Error::from_raw(unsafe { sys::tvg_paint_set_transform(self.raw(), &raw const raw_m) })
    }

    /// Returns the affine transformation matrix.
    ///
    /// If no transform was set, this is [`Matrix::IDENTITY`].
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn transform(&self) -> Result<Matrix> {
        let mut m = sys::Tvg_Matrix {
            e11: 0.0,
            e12: 0.0,
            e13: 0.0,
            e21: 0.0,
            e22: 0.0,
            e23: 0.0,
            e31: 0.0,
            e32: 0.0,
            e33: 0.0,
        };
        Error::from_raw(unsafe { sys::tvg_paint_get_transform(self.raw(), &raw mut m) })?;
        Ok(Matrix::from_raw(m))
    }

    /// Returns the axis-aligned bounding box `(x, y, width, height)` in
    /// canvas space, with all transforms applied.
    ///
    /// The paint must have been updated on a canvas first (typically after
    /// a draw/sync), otherwise the bounds reflect stale geometry.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if the bounds cannot be
    /// computed (usually invalid path data), or [`Error::InvalidArguments`]
    /// if the underlying handle is invalid.
    fn bounds(&self) -> Result<(f32, f32, f32, f32)> {
        let mut x: f32 = 0.0;
        let mut y: f32 = 0.0;
        let mut w: f32 = 0.0;
        let mut h: f32 = 0.0;
        Error::from_raw(unsafe {
            sys::tvg_paint_get_aabb(self.raw(), &raw mut x, &raw mut y, &raw mut w, &raw mut h)
        })?;
        Ok((x, y, w, h))
    }

    /// Returns the oriented bounding box (OBB) as its four corner points in
    /// canvas space.
    ///
    /// Unlike [`bounds`](Paint::bounds), the OBB preserves the object's
    /// rotation: it is the local AABB with the object's transform applied.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if the bounds cannot be
    /// computed (usually invalid path data), or [`Error::InvalidArguments`]
    /// if the underlying handle is invalid.
    fn bounds_obb(&self) -> Result<[Point; 4]> {
        let mut pts = [sys::Tvg_Point { x: 0.0, y: 0.0 }; 4];
        Error::from_raw(unsafe { sys::tvg_paint_get_obb(self.raw(), pts.as_mut_ptr()) })?;
        Ok([
            Point {
                x: pts[0].x,
                y: pts[0].y,
            },
            Point {
                x: pts[1].x,
                y: pts[1].y,
            },
            Point {
                x: pts[2].x,
                y: pts[2].y,
            },
            Point {
                x: pts[3].x,
                y: pts[3].y,
            },
        ])
    }

    /// Clips this paint's drawing region to the `clipper` shape's paths.
    ///
    /// On success the `clipper` is consumed: the engine takes a reference
    /// and ties its lifetime to this paint (released when the owning canvas
    /// is destroyed), and the Rust `Drop` is suppressed to avoid a
    /// double-free. On error the engine never touches the `clipper`, so it
    /// is dropped normally and its allocation is released rather than
    /// leaked.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if `clipper` already belongs
    /// to another paint. (The C API also reports `NOT_SUPPORTED` for a
    /// non-shape clipper, but the [`Shape`] argument type makes that
    /// unreachable here.)
    fn set_clip(&mut self, clipper: Shape<'_>) -> Result<()> {
        let raw = clipper.raw();
        let r = Error::from_raw(unsafe { sys::tvg_paint_set_clip(self.raw(), raw) });
        if r.is_ok() {
            let _ = clipper.into_raw();
        }
        r
    }

    /// Returns the clip shape set via [`set_clip`](Paint::set_clip), or
    /// `None` if none is set.
    ///
    /// The returned [`Shape`] is a non-owning view: it does not free the
    /// underlying clipper on drop.
    fn clip(&self) -> Option<Shape<'_>> {
        let raw = unsafe { sys::tvg_paint_get_clip(self.raw()) };
        if raw.is_null() {
            None
        } else {
            Some(unsafe { Shape::from_raw(raw, false) })
        }
    }

    /// Masks this paint with `mask` using the given [`MaskMethod`].
    ///
    /// On success the `mask` is consumed: the engine takes a reference and
    /// ties its lifetime to this paint (released when the owning canvas is
    /// destroyed), and the Rust `Drop` is suppressed to avoid a
    /// double-free. On error the engine does not take ownership, so `mask`
    /// is dropped normally and its allocation is released rather than
    /// leaked.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InsufficientCondition`] if `mask` already belongs to
    /// another paint, or [`Error::InvalidArguments`] if `method` is
    /// [`MaskMethod::None`] (passing a target with no masking method is
    /// rejected — use a real method, or clear the mask through the engine).
    fn set_mask<P: Paint>(&mut self, mask: P, method: MaskMethod) -> Result<()> {
        let raw = mask.raw();
        let r = Error::from_raw(unsafe {
            sys::tvg_paint_set_mask_method(self.raw(), raw, method.to_raw())
        });
        if r.is_ok() {
            let _ = mask.into_raw();
        }
        r
    }

    /// Returns the mask target and [`MaskMethod`] set via
    /// [`set_mask`](Paint::set_mask), or `None` if no mask is attached.
    ///
    /// The returned [`BorrowedPaint`] is read-only and tied to this paint's
    /// lifetime — dropping the source invalidates the borrow.
    ///
    /// # Why a borrow rather than `Shape<'_>`
    ///
    /// `set_mask` accepts any `Paint` (Shape, Scene, Picture, Text),
    /// so the returned mask cannot be type-pinned to `Shape` without
    /// risking a silent type-pun.  `BorrowedPaint::paint_type` lets
    /// callers dispatch on the runtime type.
    fn mask(&self) -> Option<(BorrowedPaint<'_>, MaskMethod)> {
        let mut target: sys::Tvg_Paint = core::ptr::null_mut();
        let mut method = sys::Tvg_Mask_Method::TVG_MASK_METHOD_NONE;

        // The C signature `tvg_paint_get_mask_method(paint, target,
        // method)` types `target` as `Tvg_Paint` (= *mut c_void) but
        // treats it internally as a `Paint**` out-param — passing a
        // real paint handle here would corrupt that paint's vtable.
        // We pass the address of a local `Tvg_Paint` slot cast to
        // `Tvg_Paint`, which is what the C side actually wants.
        let r = unsafe {
            sys::tvg_paint_get_mask_method(
                self.raw(),
                (&raw mut target).cast::<sys::_Tvg_Paint>(),
                &raw mut method,
            )
        };

        if Error::from_raw(r).is_err() || target.is_null() {
            return None;
        }
        // SAFETY: target is non-null and refers to a paint owned by
        // `self` (the masking source); the BorrowedPaint's lifetime
        // is bounded by `&self`.
        Some((
            unsafe { BorrowedPaint::from_raw(target) },
            MaskMethod::from_raw(method),
        ))
    }

    /// Sets the [`BlendMethod`] used to composite this paint over the layer
    /// beneath it.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn set_blend(&mut self, method: BlendMethod) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_set_blend_method(self.raw(), method.to_raw()) })
    }

    /// Sets the paint's id, used to identify a paint instance within a scene.
    ///
    /// *Experimental in `ThorVG`; the API may change.*
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn set_id(&mut self, id: u32) -> Result<()> {
        Error::from_raw(unsafe { sys::tvg_paint_set_id(self.raw(), id) })
    }

    /// Returns the user-assigned id, or `0` if none was set.
    ///
    /// *Experimental in `ThorVG`; the API may change.*
    fn id(&self) -> u32 {
        unsafe { sys::tvg_paint_get_id(self.raw()) }
    }

    /// Returns the concrete [`PaintType`] of this paint.
    ///
    /// # Errors
    ///
    /// Returns [`Error::InvalidArguments`] if the underlying handle is
    /// invalid.
    fn paint_type(&self) -> Result<PaintType> {
        let mut t = sys::Tvg_Type::TVG_TYPE_UNDEF;
        Error::from_raw(unsafe { sys::tvg_paint_get_type(self.raw(), &raw mut t) })?;
        Ok(PaintType::from_raw(t))
    }

    /// Returns `true` if the rectangle `(x, y, w, h)` intersects this paint's
    /// filled area (hit-testing).
    ///
    /// To test a single point, use `w = 1, h = 1`; non-positive `w` or `h`
    /// always returns `false`. The paint must have been updated on a canvas
    /// first. Blending and masking are ignored, but hidden paints still
    /// count.
    fn intersects(&self, x: i32, y: i32, w: i32, h: i32) -> bool {
        unsafe { sys::tvg_paint_intersects(self.raw(), x, y, w, h) }
    }

    /// Returns a deep copy of this paint with all properties preserved, or
    /// `None` if duplication fails.
    fn duplicate(&self) -> Option<Self>
    where
        Self: Sized,
    {
        let raw = unsafe { sys::tvg_paint_duplicate(self.raw()) };
        if raw.is_null() {
            None
        } else {
            // Safety: duplicate returns a new owned paint
            Some(unsafe { Self::from_raw_paint(raw) })
        }
    }

    // Note: paint_ref/paint_unref/ref_cnt/parent_raw are intentionally
    // not exposed. They manipulate ThorVG's internal reference counting
    // which conflicts with Rust's ownership model. Misuse (e.g.
    // paint_unref(true)) causes double-free when Drop runs. Use
    // thorvg-sys directly if you need low-level refcount control.

    /// Constructs a new owned instance from a raw `Tvg_Paint` handle.
    ///
    /// # Safety
    ///
    /// `raw` must be a valid `Tvg_Paint` owned by the caller, and its
    /// runtime [`PaintType`] must match `Self`. The returned value takes
    /// ownership and frees the handle on drop.
    unsafe fn from_raw_paint(raw: sys::Tvg_Paint) -> Self
    where
        Self: Sized;
}