cranpose_ui/widgets/

image.rs

//! Image composable and painter primitives.

#![expect(non_snake_case, reason = "names follow Compose's casing")]

#[cfg(feature = "svg")]
use std::sync::{Mutex, MutexGuard};
use std::{
    hash::{Hash, Hasher},
    sync::Arc,
};

use cranpose_core::NodeId;
use cranpose_ui_graphics::{ColorFilter, DrawScope, ImageBitmap, ImageSampling};
use cranpose_ui_layout::{Constraints, MeasurePolicy, MeasureResult, MeasureScope, Placement};
use thiserror::Error;

use crate::{
    composable,
    layout::core::{Alignment, Measurable},
    modifier::{Modifier, Rect, Size},
    nine_patch::{NinePatchInsets, PatchFill, PatchQuad, nine_patch_quads, tile_quads},
    widgets::Layout,
};

#[cfg(feature = "svg")]
#[path = "image_svg.rs"]
mod image_svg;

/// Alpha value of a fully opaque image, the default for [`Image`].
pub const DEFAULT_ALPHA: f32 = 1.0;
#[cfg(feature = "svg")]
const SVG_RASTER_CACHE_LIMIT: usize = 8;

/// How an image is scaled to fit the bounds it is drawn into. Compose's `ContentScale`.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum ContentScale {
    /// Scales both axes by one factor so the whole image fits inside the bounds, leaving space on
    /// one axis.
    Fit,
    /// Scales both axes by one factor so the image covers the bounds, cropping what overflows.
    Crop,
    /// Scales each axis separately so the image fills the bounds, which distorts its aspect ratio.
    FillBounds,
    /// Scales both axes by one factor so the image width matches the bounds width.
    FillWidth,
    /// Scales both axes by one factor so the image height matches the bounds height.
    FillHeight,
    /// Like `Fit`, but never enlarges an image that already fits inside the bounds.
    Inside,
    /// Draws the image at its own size without scaling.
    None,
}

impl ContentScale {
    /// Returns the size of an image of `src_size` after this scale fits it to `dst_size`. For
    /// `Crop` the result can exceed `dst_size`. Returns zero size if a side of either size is zero
    /// or negative.
    pub fn scaled_size(self, src_size: Size, dst_size: Size) -> Size {
        if src_size.width <= 0.0
            || src_size.height <= 0.0
            || dst_size.width <= 0.0
            || dst_size.height <= 0.0
        {
            return Size::ZERO;
        }

        let scale_x = dst_size.width / src_size.width;
        let scale_y = dst_size.height / src_size.height;

        let (factor_x, factor_y) = match self {
            Self::Fit => {
                let factor = scale_x.min(scale_y);
                (factor, factor)
            }
            Self::Crop => {
                let factor = scale_x.max(scale_y);
                (factor, factor)
            }
            Self::FillBounds => (scale_x, scale_y),
            Self::FillWidth => (scale_x, scale_x),
            Self::FillHeight => (scale_y, scale_y),
            Self::Inside => {
                if src_size.width <= dst_size.width && src_size.height <= dst_size.height {
                    (1.0, 1.0)
                } else {
                    let factor = scale_x.min(scale_y);
                    (factor, factor)
                }
            }
            Self::None => (1.0, 1.0),
        };

        Size {
            width: src_size.width * factor_x,
            height: src_size.height * factor_y,
        }
    }
}

/// The pixels that an [`Image`] draws: a bitmap, a region of a bitmap, a tiled or nine-patch
/// region, or an SVG. Compose's `Painter`.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Painter {
    kind: PainterKind,
}

#[derive(Clone, Debug, PartialEq, Eq, Hash)]
enum PainterKind {
    Bitmap(ImageBitmap),
    BitmapRegion {
        bitmap: ImageBitmap,
        source: Quad,
        sampling: ImageSampling,
    },
    /// A source repeated at its own size across whatever space it is given,
    /// rather than scaled to fit it.
    BitmapTiled {
        bitmap: ImageBitmap,
        source: Quad,
        sampling: ImageSampling,
    },
    /// A source whose corners keep their size while its edges and middle grow.
    NinePatch {
        bitmap: ImageBitmap,
        source: Quad,
        insets: Quad,
        center: PatchFill,
        edges: PatchFill,
        sampling: ImageSampling,
    },
    Svg(SvgPainter),
}

/// Four `f32`s carried as bits.
///
/// A painter is compared and hashed so a composable can skip when it has not
/// changed, and floats are neither `Eq` nor `Hash`. Keeping the bits makes the
/// comparison exact — two painters built from the same numbers are the same
/// painter — without asking the caller to think about it.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
struct Quad {
    a: u32,
    b: u32,
    c: u32,
    d: u32,
}

impl Quad {
    fn of(a: f32, b: f32, c: f32, d: f32) -> Self {
        Self {
            a: a.to_bits(),
            b: b.to_bits(),
            c: c.to_bits(),
            d: d.to_bits(),
        }
    }

    fn values(self) -> (f32, f32, f32, f32) {
        (
            f32::from_bits(self.a),
            f32::from_bits(self.b),
            f32::from_bits(self.c),
            f32::from_bits(self.d),
        )
    }

    fn from_rect(source: Rect) -> Self {
        Self::of(source.x, source.y, source.width, source.height)
    }

    fn rect(self) -> Rect {
        let (x, y, width, height) = self.values();
        Rect {
            x,
            y,
            width,
            height,
        }
    }

    fn from_insets(insets: NinePatchInsets) -> Self {
        Self::of(insets.left, insets.top, insets.right, insets.bottom)
    }

    fn insets(self) -> NinePatchInsets {
        let (left, top, right, bottom) = self.values();
        NinePatchInsets::new(left, top, right, bottom)
    }
}

impl Painter {
    /// Creates a painter that draws the whole bitmap.
    pub fn from_bitmap(bitmap: ImageBitmap) -> Self {
        Self {
            kind: PainterKind::Bitmap(bitmap),
        }
    }

    /// Creates a painter for one source region of a bitmap atlas.
    pub fn from_bitmap_region(bitmap: ImageBitmap, source: Rect, sampling: ImageSampling) -> Self {
        Self {
            kind: PainterKind::BitmapRegion {
                bitmap,
                source: Quad::from_rect(source),
                sampling,
            },
        }
    }

    /// Creates a painter that repeats `source` at its own size across whatever
    /// space it is given, instead of scaling it to fit.
    ///
    /// A texture, a hatch or a skin background covers an area of any size
    /// without going soft. `source` is a region of `bitmap`, so an application
    /// tiles one sprite out of an atlas and never the whole sheet.
    pub fn from_bitmap_tiled(bitmap: ImageBitmap, source: Rect, sampling: ImageSampling) -> Self {
        Self {
            kind: PainterKind::BitmapTiled {
                bitmap,
                source: Quad::from_rect(source),
                sampling,
            },
        }
    }

    /// Creates a painter whose corners keep their own size while its edges and
    /// middle grow — one drawing of a button, panel or trough used at every
    /// size.
    ///
    /// `center` and `edges` decide whether the growing parts are stretched or
    /// tiled. Insets that leave no middle, or a destination with no room for
    /// the corners, fall back to a plain scale rather than drawing corners over
    /// each other.
    pub fn from_nine_patch(
        bitmap: ImageBitmap,
        source: Rect,
        insets: NinePatchInsets,
        center: PatchFill,
        edges: PatchFill,
        sampling: ImageSampling,
    ) -> Self {
        Self {
            kind: PainterKind::NinePatch {
                bitmap,
                source: Quad::from_rect(source),
                insets: Quad::from_insets(insets),
                center,
                edges,
                sampling,
            },
        }
    }

    /// Creates a painter that draws a parsed SVG.
    pub fn from_svg(svg: SvgPainter) -> Self {
        Self {
            kind: PainterKind::Svg(svg),
        }
    }

    /// Returns the size in pixels that the painter has without constraints: the bitmap size, the
    /// source region size, or the size the SVG declares.
    pub fn intrinsic_size(&self) -> Size {
        match &self.kind {
            PainterKind::Bitmap(bitmap) => bitmap.intrinsic_size(),
            PainterKind::BitmapRegion { source, .. }
            | PainterKind::BitmapTiled { source, .. }
            | PainterKind::NinePatch { source, .. } => {
                let source = source.rect();
                Size::new(source.width.max(0.0), source.height.max(0.0))
            }
            PainterKind::Svg(svg) => svg.intrinsic_size(),
        }
    }

    /// Returns the bitmap that the painter draws from, or `None` for an SVG painter. Region, tiled
    /// and nine-patch painters return their whole source bitmap.
    pub fn as_bitmap(&self) -> Option<&ImageBitmap> {
        match &self.kind {
            PainterKind::Bitmap(bitmap) => Some(bitmap),
            PainterKind::BitmapRegion { bitmap, .. }
            | PainterKind::BitmapTiled { bitmap, .. }
            | PainterKind::NinePatch { bitmap, .. } => Some(bitmap),
            PainterKind::Svg(_) => None,
        }
    }

    /// Returns the underlying bitmap when this painter is bitmap-backed.
    pub fn bitmap(&self) -> Option<&ImageBitmap> {
        self.as_bitmap()
    }
}

impl From<ImageBitmap> for Painter {
    fn from(value: ImageBitmap) -> Self {
        Self::from_bitmap(value)
    }
}

impl From<SvgPainter> for Painter {
    fn from(value: SvgPainter) -> Self {
        Self::from_svg(value)
    }
}

/// Creates a painter that draws the whole bitmap.
pub fn BitmapPainter(bitmap: ImageBitmap) -> Painter {
    Painter::from_bitmap(bitmap)
}

/// Creates a painter that draws one region from a bitmap atlas.
pub fn BitmapRegionPainter(bitmap: ImageBitmap, source: Rect, sampling: ImageSampling) -> Painter {
    Painter::from_bitmap_region(bitmap, source, sampling)
}

/// Creates a painter that repeats one region of a bitmap across its bounds.
pub fn TiledPainter(bitmap: ImageBitmap, source: Rect, sampling: ImageSampling) -> Painter {
    Painter::from_bitmap_tiled(bitmap, source, sampling)
}

/// Creates a painter whose corners stay put while its edges and middle grow.
pub fn NinePatchPainter(
    bitmap: ImageBitmap,
    source: Rect,
    insets: NinePatchInsets,
    center: PatchFill,
    edges: PatchFill,
    sampling: ImageSampling,
) -> Painter {
    Painter::from_nine_patch(bitmap, source, insets, center, edges, sampling)
}

/// Errors returned while parsing or rasterizing an SVG painter.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum SvgPainterError {
    /// The crate was built without the `svg` feature.
    #[error("SVG support is disabled; enable the cranpose-ui `svg` feature")]
    SvgFeatureDisabled,
    /// The SVG data could not be parsed. Holds the parser message.
    #[error("failed to parse SVG: {0}")]
    Parse(String),
    /// A requested raster side was zero, negative or not a finite number.
    #[error("SVG raster dimensions must be greater than zero")]
    InvalidRasterDimensions,
    /// The requested raster is too large to address.
    #[error("SVG raster dimensions are too large")]
    RasterDimensionsTooLarge,
    /// Allocating the memory for the raster failed.
    #[error("failed to allocate SVG raster {width}x{height}")]
    RasterAllocationFailed {
        /// Requested raster width in pixels.
        width: u32,
        /// Requested raster height in pixels.
        height: u32,
    },
    /// The raster cache could not be locked.
    #[error("SVG raster cache is unavailable")]
    RasterCacheUnavailable,
    /// Creating the bitmap from the rasterized pixels failed.
    #[error(transparent)]
    ImageBitmap(#[from] cranpose_ui_graphics::ImageBitmapError),
}

/// Parsed SVG image data that rasterizes on demand for the requested draw size.
#[derive(Clone)]
pub struct SvgPainter {
    inner: Arc<SvgPainterInner>,
}

struct SvgPainterInner {
    #[cfg(feature = "svg")]
    document: image_svg::SvgDocument,
    intrinsic_size: Size,
    #[cfg(feature = "svg")]
    cache: Mutex<SvgRasterCache>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg(feature = "svg")]
struct SvgRasterKey {
    width: u32,
    height: u32,
}

#[derive(Clone, Debug)]
#[cfg(feature = "svg")]
struct SvgRasterEntry {
    key: SvgRasterKey,
    bitmap: ImageBitmap,
}

#[derive(Default, Debug)]
#[cfg(feature = "svg")]
struct SvgRasterCache {
    entries: Vec<SvgRasterEntry>,
}

impl SvgPainter {
    /// Parses SVG `bytes`. Fails with `SvgFeatureDisabled` when the `svg` feature is off and with
    /// `Parse` when the data is not valid SVG.
    pub fn from_bytes(bytes: &[u8]) -> Result<Self, SvgPainterError> {
        #[cfg(not(feature = "svg"))]
        {
            let _ = bytes;
            Err(SvgPainterError::SvgFeatureDisabled)
        }
        #[cfg(feature = "svg")]
        {
            let document = image_svg::parse_svg_document(bytes)?;
            let intrinsic_size = document.intrinsic_size();

            Ok(Self {
                inner: Arc::new(SvgPainterInner {
                    document,
                    intrinsic_size,
                    cache: Mutex::new(SvgRasterCache::default()),
                }),
            })
        }
    }

    /// Returns an id that clones of this painter share. Painters parsed separately have different
    /// ids while both are alive.
    pub fn id(&self) -> u64 {
        Arc::as_ptr(&self.inner) as usize as u64
    }

    /// Returns the size in pixels that the SVG document declares.
    pub fn intrinsic_size(&self) -> Size {
        self.inner.intrinsic_size
    }

    /// Rasterizes the SVG into a bitmap of `pixel_size` pixels, rounded up to whole pixels. A few
    /// recent sizes are cached.
    pub fn rasterize(&self, pixel_size: Size) -> Result<ImageBitmap, SvgPainterError> {
        #[cfg(not(feature = "svg"))]
        {
            let _ = pixel_size;
            Err(SvgPainterError::SvgFeatureDisabled)
        }
        #[cfg(feature = "svg")]
        {
            let key = svg_raster_key(pixel_size)?;
            if let Some(bitmap) = self.cached_bitmap(key)? {
                return Ok(bitmap);
            }

            let bitmap = self.rasterize_uncached(key)?;
            self.cache_bitmap(key, bitmap.clone())?;
            Ok(bitmap)
        }
    }

    #[cfg(feature = "svg")]
    fn cached_bitmap(&self, key: SvgRasterKey) -> Result<Option<ImageBitmap>, SvgPainterError> {
        let mut cache = self.lock_cache();
        Ok(cache.get(key))
    }

    #[cfg(feature = "svg")]
    fn cache_bitmap(&self, key: SvgRasterKey, bitmap: ImageBitmap) -> Result<(), SvgPainterError> {
        let mut cache = self.lock_cache();
        cache.insert(key, bitmap);
        Ok(())
    }

    #[cfg(feature = "svg")]
    fn lock_cache(&self) -> MutexGuard<'_, SvgRasterCache> {
        self.inner
            .cache
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
    }

    #[cfg(feature = "svg")]
    fn rasterize_uncached(&self, key: SvgRasterKey) -> Result<ImageBitmap, SvgPainterError> {
        (key.width as usize)
            .checked_mul(key.height as usize)
            .and_then(|value| value.checked_mul(4))
            .ok_or(SvgPainterError::RasterDimensionsTooLarge)?;

        let mut pixmap = tiny_skia::Pixmap::new(key.width, key.height).ok_or(
            SvgPainterError::RasterAllocationFailed {
                width: key.width,
                height: key.height,
            },
        )?;
        image_svg::rasterize_svg_document(&self.inner.document, &mut pixmap);
        let pixels = image_svg::demultiplied_rgba_pixels(&pixmap);
        Ok(ImageBitmap::from_rgba8(key.width, key.height, pixels)?)
    }
}

impl std::fmt::Debug for SvgPainter {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SvgPainter")
            .field("id", &self.id())
            .field("intrinsic_size", &self.intrinsic_size())
            .finish_non_exhaustive()
    }
}

impl PartialEq for SvgPainter {
    fn eq(&self, other: &Self) -> bool {
        self.id() == other.id()
    }
}

impl Eq for SvgPainter {}

impl Hash for SvgPainter {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.id().hash(state);
    }
}

#[cfg(feature = "svg")]
impl SvgRasterCache {
    fn get(&mut self, key: SvgRasterKey) -> Option<ImageBitmap> {
        let position = self.entries.iter().position(|entry| entry.key == key)?;
        let entry = self.entries.remove(position);
        let bitmap = entry.bitmap.clone();
        self.entries.push(entry);
        Some(bitmap)
    }

    fn insert(&mut self, key: SvgRasterKey, bitmap: ImageBitmap) {
        if let Some(position) = self.entries.iter().position(|entry| entry.key == key) {
            self.entries.remove(position);
        } else if self.entries.len() >= SVG_RASTER_CACHE_LIMIT {
            self.entries.remove(0);
        }
        self.entries.push(SvgRasterEntry { key, bitmap });
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
struct SvgBytesKey {
    ptr: usize,
    len: usize,
}

impl SvgBytesKey {
    fn new(bytes: &'static [u8]) -> Self {
        Self {
            ptr: bytes.as_ptr() as usize,
            len: bytes.len(),
        }
    }
}

/// Parses `bytes` once for the calling composition position and returns the same painter on later
/// recompositions. The cache key is the address and length of `bytes`.
pub fn rememberSvg(bytes: &'static [u8]) -> Result<SvgPainter, SvgPainterError> {
    let key = SvgBytesKey::new(bytes);
    cranpose_core::withCurrentComposer(|composer| {
        composer.with_key(&key, |composer| {
            composer
                .remember(|| SvgPainter::from_bytes(bytes))
                .with(Clone::clone)
        })
    })
}

/// Measure policy for Image that preserves aspect ratio when constraints
/// force the image smaller than its intrinsic size.
///
/// Unlike [`LeafMeasurePolicy`] which clamps width and height independently,
/// this scales both dimensions by the same factor so the image is never
/// distorted by layout constraints.
#[derive(Clone, Debug, PartialEq)]
struct ImageMeasurePolicy {
    intrinsic_size: Size,
}

impl MeasurePolicy for ImageMeasurePolicy {
    fn measure(
        &self,
        scope: &dyn MeasureScope,
        _measurables: &[Box<dyn Measurable>],
        constraints: Constraints,
    ) -> MeasureResult {
        let mut placements = Vec::new();
        let measurement = self.measure_into(scope, &[], constraints, &mut placements);
        MeasureResult::new(measurement, placements)
    }

    fn measure_into(
        &self,
        _scope: &dyn MeasureScope,
        _measurables: &[Box<dyn Measurable>],
        constraints: Constraints,
        placements: &mut Vec<Placement>,
    ) -> cranpose_ui_layout::Measurement {
        placements.clear();
        let iw = self.intrinsic_size.width;
        let ih = self.intrinsic_size.height;

        if iw <= 0.0 || ih <= 0.0 {
            let (w, h) = constraints.constrain(0.0, 0.0);
            return Size {
                width: w,
                height: h,
            }
            .into();
        }

        let cw = iw.clamp(constraints.min_width, constraints.max_width);
        let ch = ih.clamp(constraints.min_height, constraints.max_height);

        let scale_x = cw / iw;
        let scale_y = ch / ih;

        let (width, height) = if scale_x < 1.0 || scale_y < 1.0 {
            let factor = scale_x.min(scale_y);
            let w = (iw * factor).clamp(constraints.min_width, constraints.max_width);
            let h = (ih * factor).clamp(constraints.min_height, constraints.max_height);
            (w, h)
        } else {
            (cw, ch)
        };

        Size { width, height }.into()
    }

    fn min_intrinsic_width(&self, _measurables: &[Box<dyn Measurable>], _height: f32) -> f32 {
        self.intrinsic_size.width
    }

    fn max_intrinsic_width(&self, _measurables: &[Box<dyn Measurable>], _height: f32) -> f32 {
        self.intrinsic_size.width
    }

    fn min_intrinsic_height(&self, _measurables: &[Box<dyn Measurable>], _width: f32) -> f32 {
        self.intrinsic_size.height
    }

    fn max_intrinsic_height(&self, _measurables: &[Box<dyn Measurable>], _width: f32) -> f32 {
        self.intrinsic_size.height
    }
}

/// Where the painter draws in the container, as Compose's painter modifier
/// places it: scaled, then aligned on sizes rounded to whole device pixels
/// of `density`, overflowing the container where the scale makes it larger.
fn destination_rect(
    src_size: Size,
    dst_size: Size,
    alignment: Alignment,
    content_scale: ContentScale,
    density: f32,
) -> Rect {
    use cranpose_ui_layout::round_to_px;

    let draw_size = content_scale.scaled_size(src_size, dst_size);
    Rect {
        x: alignment.horizontal.align(
            round_to_px(dst_size.width, density),
            round_to_px(draw_size.width, density),
            density,
        ),
        y: alignment.vertical.align(
            round_to_px(dst_size.height, density),
            round_to_px(draw_size.height, density),
            density,
        ),
        width: draw_size.width,
        height: draw_size.height,
    }
}

fn map_destination_clip_to_source(
    src_rect: Rect,
    dst_rect: Rect,
    clipped_dst_rect: Rect,
) -> Option<Rect> {
    if src_rect.width <= 0.0
        || src_rect.height <= 0.0
        || dst_rect.width <= 0.0
        || dst_rect.height <= 0.0
        || clipped_dst_rect.width <= 0.0
        || clipped_dst_rect.height <= 0.0
    {
        return None;
    }

    let scale_x = src_rect.width / dst_rect.width;
    let scale_y = src_rect.height / dst_rect.height;

    let src_min_x = src_rect.x;
    let src_min_y = src_rect.y;
    let src_max_x = src_rect.x + src_rect.width;
    let src_max_y = src_rect.y + src_rect.height;

    let raw_left = src_rect.x + (clipped_dst_rect.x - dst_rect.x) * scale_x;
    let raw_top = src_rect.y + (clipped_dst_rect.y - dst_rect.y) * scale_y;
    let raw_right =
        src_rect.x + ((clipped_dst_rect.x + clipped_dst_rect.width) - dst_rect.x) * scale_x;
    let raw_bottom =
        src_rect.y + ((clipped_dst_rect.y + clipped_dst_rect.height) - dst_rect.y) * scale_y;

    let left = raw_left.clamp(src_min_x, src_max_x);
    let top = raw_top.clamp(src_min_y, src_max_y);
    let right = raw_right.clamp(src_min_x, src_max_x);
    let bottom = raw_bottom.clamp(src_min_y, src_max_y);
    let width = right - left;
    let height = bottom - top;

    if width <= 0.0 || height <= 0.0 {
        None
    } else {
        Some(Rect {
            x: left,
            y: top,
            width,
            height,
        })
    }
}

fn image_destination_clip(
    src_size: Size,
    container_size: Size,
    alignment: Alignment,
    content_scale: ContentScale,
    density: f32,
) -> Option<(Rect, Rect)> {
    let dst_rect = destination_rect(src_size, container_size, alignment, content_scale, density);
    if dst_rect.width <= 0.0 || dst_rect.height <= 0.0 {
        return None;
    }

    let container_rect = Rect::from_size(container_size);
    let clipped_dst_rect = dst_rect.intersect(container_rect)?;
    Some((dst_rect, clipped_dst_rect))
}

// How an Image draws its painter: placed by its alignment and content
// scale on whole device pixels of `density`, with its alpha and color filter.
struct ImageDraw {
    alignment: Alignment,
    content_scale: ContentScale,
    alpha: f32,
    color_filter: Option<ColorFilter>,
    density: f32,
}

impl ImageDraw {
    fn clip(&self, src_size: Size, container_size: Size) -> Option<(Rect, Rect)> {
        image_destination_clip(
            src_size,
            container_size,
            self.alignment,
            self.content_scale,
            self.density,
        )
    }
}

fn draw_bitmap_painter(
    scope: &mut dyn DrawScope,
    bitmap: ImageBitmap,
    intrinsic_size: Size,
    draw: &ImageDraw,
) {
    let Some((dst_rect, clipped_dst_rect)) = draw.clip(intrinsic_size, scope.size()) else {
        return;
    };
    let full_src_rect = Rect::from_size(Size::new(bitmap.width() as f32, bitmap.height() as f32));
    let Some(clipped_src_rect) =
        map_destination_clip_to_source(full_src_rect, dst_rect, clipped_dst_rect)
    else {
        return;
    };
    scope.draw_image_src_sampled(
        bitmap,
        clipped_src_rect,
        clipped_dst_rect,
        draw.alpha,
        draw.color_filter.clone(),
        ImageSampling::Linear,
    );
}

fn draw_bitmap_region_painter(
    scope: &mut dyn DrawScope,
    bitmap: ImageBitmap,
    source: Rect,
    sampling: ImageSampling,
    draw: &ImageDraw,
) {
    let source_size = Size::new(source.width.max(0.0), source.height.max(0.0));
    let Some((dst_rect, clipped_dst_rect)) = draw.clip(source_size, scope.size()) else {
        return;
    };
    let Some(clipped_source) = map_destination_clip_to_source(source, dst_rect, clipped_dst_rect)
    else {
        return;
    };
    scope.draw_image_src_sampled(
        bitmap,
        clipped_source,
        clipped_dst_rect,
        draw.alpha,
        draw.color_filter.clone(),
        sampling,
    );
}

/// Draws a list of source-to-destination quads, clipped to the container.
///
/// Every fill that is not a plain scale — tiling, nine-patch — reduces to this,
/// so the clipping rule and the sampling choice are stated once.
fn draw_patch_quads(
    scope: &mut dyn DrawScope,
    bitmap: &ImageBitmap,
    quads: &[PatchQuad],
    container: Rect,
    alpha: f32,
    color_filter: Option<ColorFilter>,
    sampling: ImageSampling,
) {
    for quad in quads {
        let Some(clipped_destination) = intersect(quad.destination, container) else {
            continue;
        };
        let Some(clipped_source) =
            map_destination_clip_to_source(quad.source, quad.destination, clipped_destination)
        else {
            continue;
        };
        scope.draw_image_src_sampled(
            bitmap.clone(),
            clipped_source,
            clipped_destination,
            alpha,
            color_filter.clone(),
            sampling,
        );
    }
}

fn intersect(rect: Rect, bounds: Rect) -> Option<Rect> {
    let left = rect.x.max(bounds.x);
    let top = rect.y.max(bounds.y);
    let right = (rect.x + rect.width).min(bounds.x + bounds.width);
    let bottom = (rect.y + rect.height).min(bounds.y + bounds.height);
    if right <= left || bottom <= top {
        return None;
    }
    Some(Rect {
        x: left,
        y: top,
        width: right - left,
        height: bottom - top,
    })
}

// Draws a tiled or nine-patch painter across the whole container, in the
// patches `quads_of` cuts for it. Content scale and alignment do not apply:
// such a fill covers its bounds by construction.
fn draw_filled_painter(
    scope: &mut dyn DrawScope,
    bitmap: &ImageBitmap,
    quads_of: impl FnOnce(Rect) -> Vec<PatchQuad>,
    alpha: f32,
    color_filter: Option<ColorFilter>,
    sampling: ImageSampling,
) {
    let container = Rect::from_size(scope.size());
    let quads = quads_of(container);
    draw_patch_quads(
        scope,
        bitmap,
        &quads,
        container,
        alpha,
        color_filter,
        sampling,
    );
}

fn draw_svg_painter(
    scope: &mut dyn DrawScope,
    svg: SvgPainter,
    intrinsic_size: Size,
    draw: &ImageDraw,
) {
    let Some((dst_rect, clipped_dst_rect)) = draw.clip(intrinsic_size, scope.size()) else {
        return;
    };
    let pixel_size = Size::new(
        dst_rect.width * draw.density,
        dst_rect.height * draw.density,
    );
    let bitmap = match svg.rasterize(pixel_size) {
        Ok(bitmap) => bitmap,
        Err(error) => {
            log::warn!("failed to rasterize SVG painter: {error}");
            return;
        }
    };
    let full_src_rect = Rect::from_size(Size::new(bitmap.width() as f32, bitmap.height() as f32));
    let Some(clipped_src_rect) =
        map_destination_clip_to_source(full_src_rect, dst_rect, clipped_dst_rect)
    else {
        return;
    };
    scope.draw_image_src_sampled(
        bitmap,
        clipped_src_rect,
        clipped_dst_rect,
        draw.alpha,
        draw.color_filter.clone(),
        ImageSampling::Linear,
    );
}

#[cfg(feature = "svg")]
fn svg_raster_key(pixel_size: Size) -> Result<SvgRasterKey, SvgPainterError> {
    let width = svg_raster_axis(pixel_size.width)?;
    let height = svg_raster_axis(pixel_size.height)?;
    width
        .checked_mul(height)
        .and_then(|value| value.checked_mul(4))
        .ok_or(SvgPainterError::RasterDimensionsTooLarge)?;
    Ok(SvgRasterKey { width, height })
}

#[cfg(feature = "svg")]
fn svg_raster_axis(value: f32) -> Result<u32, SvgPainterError> {
    if !value.is_finite() || value <= 0.0 {
        return Err(SvgPainterError::InvalidRasterDimensions);
    }

    let rounded = value.ceil();
    if rounded > u32::MAX as f32 {
        return Err(SvgPainterError::RasterDimensionsTooLarge);
    }
    Ok(rounded as u32)
}

/// Displays a painter with an optional accessible description.
///
/// Images use the image accessibility role unless `modifier` supplies another role.
/// Without a description or modifier semantics, the image is decorative.
#[composable]
pub fn Image<P>(
    painter: P,
    content_description: Option<String>,
    modifier: Modifier,
    alignment: Alignment,
    content_scale: ContentScale,
    alpha: f32,
    color_filter: Option<ColorFilter>,
) -> NodeId
where
    P: Into<Painter> + Clone + PartialEq + 'static,
{
    let painter = painter.into();
    let intrinsic_dp = painter.intrinsic_size();
    let draw_alpha = alpha.clamp(0.0, 1.0);

    let semantics_modifier = Modifier::empty().stable_semantics(move |config| {
        config.content_description.clone_from(&content_description);
    });

    // The grid the image is aligned on: the composition's, as Text keeps it.
    let draw = ImageDraw {
        alignment,
        content_scale,
        alpha: draw_alpha,
        color_filter,
        density: crate::density::density().density(),
    };
    let image_modifier = semantics_modifier
        .then(modifier)
        .stable_semantics(|config| {
            if config.role.is_none()
                && config
                    .content_description
                    .as_ref()
                    .is_some_and(|label| !label.trim().is_empty())
            {
                config.role = Some(crate::SemanticsWidgetRole::Image);
            }
        })
        .draw_behind(move |scope: &mut dyn DrawScope| {
            if draw.alpha <= 0.0 {
                return;
            }
            let container_size = scope.size();
            if container_size.width <= 0.0 || container_size.height <= 0.0 {
                return;
            }
            match &painter.kind {
                PainterKind::Bitmap(bitmap) => {
                    draw_bitmap_painter(scope, bitmap.clone(), intrinsic_dp, &draw);
                }
                PainterKind::BitmapRegion {
                    bitmap,
                    source,
                    sampling,
                } => draw_bitmap_region_painter(
                    scope,
                    bitmap.clone(),
                    source.rect(),
                    *sampling,
                    &draw,
                ),
                PainterKind::BitmapTiled {
                    bitmap,
                    source,
                    sampling,
                } => draw_filled_painter(
                    scope,
                    bitmap,
                    |container| tile_quads(source.rect(), container),
                    draw.alpha,
                    draw.color_filter.clone(),
                    *sampling,
                ),
                PainterKind::NinePatch {
                    bitmap,
                    source,
                    insets,
                    center,
                    edges,
                    sampling,
                } => draw_filled_painter(
                    scope,
                    bitmap,
                    |container| {
                        nine_patch_quads(source.rect(), container, insets.insets(), *center, *edges)
                    },
                    draw.alpha,
                    draw.color_filter.clone(),
                    *sampling,
                ),
                PainterKind::Svg(svg) => {
                    draw_svg_painter(scope, svg.clone(), intrinsic_dp, &draw);
                }
            }
        });

    Layout(
        image_modifier,
        ImageMeasurePolicy {
            intrinsic_size: intrinsic_dp,
        },
        || {},
    )
}

#[cfg(test)]
#[path = "tests/image_tests.rs"]
mod tests;