skrifa/color/

mod.rs

//! Drawing color glyphs.
//!
//! # Examples
//! ## Retrieve the clip box of a COLRv1 glyph if it has one:
//!
//! ```
//! # use core::result::Result;
//! # use skrifa::{instance::{Size, Location}, color::{ColorGlyphFormat, ColorPainter, PaintError}, GlyphId, MetadataProvider};
//! # fn get_colr_bb(font: read_fonts::FontRef, color_painter_impl : &mut impl ColorPainter, glyph_id : GlyphId, size: Size) -> Result<(), PaintError> {
//! match font.color_glyphs()
//!       .get_with_format(glyph_id, ColorGlyphFormat::ColrV1)
//!       .expect("Glyph not found.")
//!       .bounding_box(&Location::default(), size)
//! {
//!   Some(bounding_box) => {
//!       println!("Bounding box is {:?}", bounding_box);
//!   }
//!   None => {
//!       println!("Glyph has no clip box.");
//!   }
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Paint a COLRv1 glyph given a font, and a glyph id and a [`ColorPainter`] implementation:
//! ```
//! # use core::result::Result;
//! # use skrifa::{instance::{Size, Location}, color::{ColorGlyphFormat, ColorPainter, PaintError}, GlyphId, MetadataProvider};
//! # fn paint_colr(font: read_fonts::FontRef, color_painter_impl : &mut impl ColorPainter, glyph_id : GlyphId) -> Result<(), PaintError> {
//! let color_glyph = font.color_glyphs()
//!                     .get_with_format(glyph_id, ColorGlyphFormat::ColrV1)
//!                     .expect("Glyph not found");
//! color_glyph.paint(&Location::default(), color_painter_impl)
//! # }
//! ```
//!
mod instance;
mod transform;
mod traversal;

#[cfg(test)]
mod traversal_tests;

use raw::tables::colr;
#[cfg(test)]
use serde::{Deserialize, Serialize};

pub use read_fonts::tables::colr::{CompositeMode, Extend};

use read_fonts::{
    types::{BoundingBox, GlyphId, Point},
    ReadError, TableProvider,
};

use std::{fmt::Debug, ops::Range};

use traversal::{get_clipbox_font_units, traverse_v0_range, traverse_with_callbacks, VisitedSet};

pub use transform::Transform;

use crate::prelude::{LocationRef, Size};

use self::instance::{resolve_paint, PaintId};

/// An error during drawing a COLR glyph.
///
/// This covers inconsistencies in the COLRv1 paint graph as well as downstream
/// parse errors from read-fonts.
#[derive(Debug, Clone)]
pub enum PaintError {
    ParseError(ReadError),
    GlyphNotFound(GlyphId),
    PaintCycleDetected,
    DepthLimitExceeded,
}

impl std::fmt::Display for PaintError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            PaintError::ParseError(read_error) => {
                write!(f, "Error parsing font data: {read_error}")
            }
            PaintError::GlyphNotFound(glyph_id) => {
                write!(f, "No COLRv1 glyph found for glyph id: {glyph_id}")
            }
            PaintError::PaintCycleDetected => write!(f, "Paint cycle detected in COLRv1 glyph."),
            PaintError::DepthLimitExceeded => write!(f, "Depth limit exceeded in COLRv1 glyph."),
        }
    }
}

impl From<ReadError> for PaintError {
    fn from(value: ReadError) -> Self {
        PaintError::ParseError(value)
    }
}

/// A color stop of a gradient.
///
/// All gradient callbacks of [`ColorPainter`] normalize color stops to be in the range of 0
/// to 1.
#[derive(Clone, PartialEq, Debug, Default)]
#[cfg_attr(test, derive(Serialize, Deserialize))]
// This repr(C) is required so that C-side FFI's
// are able to cast the ColorStop slice to a C-side array pointer.
#[repr(C)]
pub struct ColorStop {
    pub offset: f32,
    /// Specifies a color from the `CPAL` table.
    pub palette_index: u16,
    /// Additional alpha value, to be multiplied with the color above before use.
    pub alpha: f32,
}

// Design considerations for choosing a slice of ColorStops as `color_stop`
// type: In principle, a local `Vec<ColorStop>` allocation would not required if
// we're willing to walk the `ResolvedColorStop` iterator to find the minimum
// and maximum color stops.  Then we could scale the color stops based on the
// minimum and maximum. But performing the min/max search would require
// re-applying the deltas at least once, after which we would pass the scaled
// stops to client side and have the client sort the collected items once
// again. If we do want to pre-ort them, and still use use an
// `Iterator<Item=ColorStop>`` instead as the `color_stops` field, then we would
// need a Fontations-side allocations to sort, and an extra allocation on the
// client side to `.collect()` from the provided iterator before passing it to
// drawing API.
//
/// A fill type of a COLRv1 glyph (solid fill or various gradient types).
///
/// The client receives the information about the fill type in the
/// [`fill``](ColorPainter::fill) callback of the [`ColorPainter`] trait.
#[derive(Debug, PartialEq)]
pub enum Brush<'a> {
    /// A solid fill with the color specified by `palette_index`. The respective
    /// color from the CPAL table then needs to be multiplied with `alpha`.
    Solid { palette_index: u16, alpha: f32 },
    /// A linear gradient, normalized from the P0, P1 and P2 representation in
    /// the COLRv1 table to a linear gradient between two points `p0` and
    /// `p1`. If there is only one color stop, the client should draw a solid
    /// fill with that color. The `color_stops` are normalized to the range from
    /// 0 to 1.
    LinearGradient {
        p0: Point<f32>,
        p1: Point<f32>,
        color_stops: &'a [ColorStop],
        extend: Extend,
    },
    /// A radial gradient, with color stops normalized to the range of 0 to 1.
    /// Caution: This normalization can mean that negative radii occur. It is
    /// the client's responsibility to truncate the color line at the 0
    /// position, interpolating between `r0` and `r1` and compute an
    /// interpolated color at that position.
    RadialGradient {
        c0: Point<f32>,
        r0: f32,
        c1: Point<f32>,
        r1: f32,
        color_stops: &'a [ColorStop],
        extend: Extend,
    },
    /// A sweep gradient, also called conical gradient. The color stops are
    /// normalized to the range from 0 to 1 and the returned angles are to be
    /// interpreted in _clockwise_ direction (swapped from the meaning in the
    /// font file).  The stop normalization may mean that the angles may be
    /// larger or smaller than the range of 0 to 360. Note that only the range
    /// from 0 to 360 degrees is to be drawn, see
    /// <https://learn.microsoft.com/en-us/typography/opentype/spec/colr#sweep-gradients>.
    SweepGradient {
        c0: Point<f32>,
        start_angle: f32,
        end_angle: f32,
        color_stops: &'a [ColorStop],
        extend: Extend,
    },
}

/// Signals success of request to draw a COLRv1 sub glyph from cache.
///
/// Result of [`paint_cached_color_glyph`](ColorPainter::paint_cached_color_glyph)
/// through which the client signals whether a COLRv1 glyph referenced by
/// another COLRv1 glyph was drawn from cache or whether the glyph's subgraph
/// should be traversed by the skria side COLRv1 implementation.
pub enum PaintCachedColorGlyph {
    /// The specified COLRv1 glyph has been successfully painted client side.
    Ok,
    /// The client does not implement drawing COLRv1 glyphs from cache and the
    /// Fontations side COLRv1 implementation is asked to traverse the
    /// respective PaintColorGlyph sub graph.
    Unimplemented,
}

/// A group of required painting callbacks to be provided by the client.
///
/// Each callback is executing a particular drawing or canvas transformation
/// operation. The trait's callback functions are invoked when
/// [`paint`](ColorGlyph::paint) is called with a [`ColorPainter`] trait
/// object. The documentation for each function describes what actions are to be
/// executed using the client side 2D graphics API, usually by performing some
/// kind of canvas operation.
pub trait ColorPainter {
    /// Push the specified transform by concatenating it to the current
    /// transformation matrix.
    fn push_transform(&mut self, transform: Transform);

    /// Restore the transformation matrix to the state before the previous
    /// [`push_transform`](ColorPainter::push_transform) call.
    fn pop_transform(&mut self);

    /// Apply a clip path in the shape of glyph specified by `glyph_id`.
    fn push_clip_glyph(&mut self, glyph_id: GlyphId);

    /// Apply a clip rectangle specified by `clip_rect`.
    fn push_clip_box(&mut self, clip_box: BoundingBox<f32>);

    /// Restore the clip state to the state before a previous
    /// [`push_clip_glyph`](ColorPainter::push_clip_glyph) or
    /// [`push_clip_box`](ColorPainter::push_clip_box) call.
    fn pop_clip(&mut self);

    /// Fill the current clip area with the specified gradient fill.
    fn fill(&mut self, brush: Brush<'_>);

    /// Combined clip and fill operation.
    ///
    /// Apply the clip path determined by the specified `glyph_id`, then fill it
    /// with the specified [`brush`](Brush), applying the `_brush_transform`
    /// transformation matrix to the brush. The default implementation works
    /// based on existing methods in this trait. It is recommended for clients
    /// to override the default implementaition with a custom combined clip and
    /// fill operation. In this way overriding likely results in performance
    /// gains depending on performance characteristics of the 2D graphics stack
    /// that these calls are mapped to.
    fn fill_glyph(
        &mut self,
        glyph_id: GlyphId,
        brush_transform: Option<Transform>,
        brush: Brush<'_>,
    ) {
        self.push_clip_glyph(glyph_id);
        if let Some(wrap_in_transform) = brush_transform {
            self.push_transform(wrap_in_transform);
            self.fill(brush);
            self.pop_transform();
        } else {
            self.fill(brush);
        }
        self.pop_clip();
    }

    /// Optionally implement this method: Draw an unscaled COLRv1 glyph given
    /// the current transformation matrix (as accumulated by
    /// [`push_transform`](ColorPainter::push_transform) calls).
    fn paint_cached_color_glyph(
        &mut self,
        _glyph: GlyphId,
    ) -> Result<PaintCachedColorGlyph, PaintError> {
        Ok(PaintCachedColorGlyph::Unimplemented)
    }

    /// Open a new layer, and merge the layer down using `composite_mode` when
    /// [`pop_layer`](ColorPainter::pop_layer) is called, signalling that this layer is done drawing.
    fn push_layer(&mut self, composite_mode: CompositeMode);
    fn pop_layer(&mut self);
}

/// Distinguishes available color glyph formats.
#[derive(Clone, Copy)]
pub enum ColorGlyphFormat {
    ColrV0,
    ColrV1,
}

/// A representation of a color glyph that can be painted through a sequence of [`ColorPainter`] callbacks.
#[derive(Clone)]
pub struct ColorGlyph<'a> {
    colr: colr::Colr<'a>,
    root_paint_ref: ColorGlyphRoot<'a>,
}

#[derive(Clone)]
enum ColorGlyphRoot<'a> {
    V0Range(Range<usize>),
    V1Paint(colr::Paint<'a>, PaintId, GlyphId, Result<u16, ReadError>),
}

impl<'a> ColorGlyph<'a> {
    /// Returns the version of the color table from which this outline was
    /// selected.
    pub fn format(&self) -> ColorGlyphFormat {
        match &self.root_paint_ref {
            ColorGlyphRoot::V0Range(_) => ColorGlyphFormat::ColrV0,
            ColorGlyphRoot::V1Paint(..) => ColorGlyphFormat::ColrV1,
        }
    }

    /// Returns the bounding box. For COLRv1 glyphs, this is clipbox of the
    /// specified COLRv1 glyph, or `None` if there is
    /// none for the particular glyph.  The `size` argument can optionally be used
    /// to scale the bounding box to a particular font size. `location` allows
    /// specifycing a variation instance.
    pub fn bounding_box(
        &self,
        location: impl Into<LocationRef<'a>>,
        size: Size,
    ) -> Option<BoundingBox<f32>> {
        let instance = instance::ColrInstance::new(self.colr.clone(), location.into().coords());

        match &self.root_paint_ref {
            ColorGlyphRoot::V1Paint(_paint, _paint_id, glyph_id, upem) => {
                let resolved_bounding_box = get_clipbox_font_units(&instance, *glyph_id);
                resolved_bounding_box.map(|bounding_box| {
                    let scale_factor = size.linear_scale((*upem).clone().unwrap_or(0));
                    bounding_box.scale(scale_factor)
                })
            }
            _ => todo!(),
        }
    }

    /// Evaluates the paint graph at the specified location in variation space
    /// and emits the results to the given painter.
    ///
    ///
    /// For a COLRv1 glyph, traverses the COLRv1 paint graph and invokes drawing callbacks on a
    /// specified [`ColorPainter`] trait object.  The traversal operates in font
    /// units and will call `ColorPainter` methods with font unit values. This
    /// means, if you want to draw a COLRv1 glyph at a particular font size, the
    /// canvas needs to have a transformation matrix applied so that it scales down
    /// the drawing operations to `font_size / upem`.
    ///
    /// # Arguments
    ///
    /// * `glyph_id` the `GlyphId` to be drawn.
    /// * `location` coordinates for specifying a variation instance. This can be empty.
    /// * `painter` a client-provided [`ColorPainter`] implementation receiving drawing callbacks.
    ///
    pub fn paint(
        &self,
        location: impl Into<LocationRef<'a>>,
        painter: &mut impl ColorPainter,
    ) -> Result<(), PaintError> {
        let instance = instance::ColrInstance::new(self.colr.clone(), location.into().coords());
        match &self.root_paint_ref {
            ColorGlyphRoot::V1Paint(paint, paint_id, glyph_id, _) => {
                let clipbox = get_clipbox_font_units(&instance, *glyph_id);

                if let Some(rect) = clipbox {
                    painter.push_clip_box(rect);
                }

                let mut visited_set = VisitedSet::default();
                visited_set.insert(*paint_id);
                traverse_with_callbacks(
                    &resolve_paint(&instance, paint)?,
                    &instance,
                    painter,
                    &mut visited_set,
                    0,
                )?;

                if clipbox.is_some() {
                    painter.pop_clip();
                }
                Ok(())
            }
            ColorGlyphRoot::V0Range(range) => {
                traverse_v0_range(range, &instance, painter)?;
                Ok(())
            }
        }
    }
}

/// Collection of color glyphs.
#[derive(Clone)]
pub struct ColorGlyphCollection<'a> {
    colr: Option<colr::Colr<'a>>,
    upem: Result<u16, ReadError>,
}

impl<'a> ColorGlyphCollection<'a> {
    /// Creates a new collection of paintable color glyphs for the given font.
    pub fn new(font: &impl TableProvider<'a>) -> Self {
        let colr = font.colr().ok();
        let upem = font.head().map(|h| h.units_per_em());

        Self { colr, upem }
    }

    /// Returns the color glyph representation for the given glyph identifier,
    /// given a specific format.
    pub fn get_with_format(
        &self,
        glyph_id: GlyphId,
        glyph_format: ColorGlyphFormat,
    ) -> Option<ColorGlyph<'a>> {
        let colr = self.colr.clone()?;

        let root_paint_ref = match glyph_format {
            ColorGlyphFormat::ColrV0 => {
                let layer_range = colr.v0_base_glyph(glyph_id).ok()??;
                ColorGlyphRoot::V0Range(layer_range)
            }
            ColorGlyphFormat::ColrV1 => {
                let (paint, paint_id) = colr.v1_base_glyph(glyph_id).ok()??;
                ColorGlyphRoot::V1Paint(paint, paint_id, glyph_id, self.upem.clone())
            }
        };
        Some(ColorGlyph {
            colr,
            root_paint_ref,
        })
    }

    /// Returns a color glyph representation for the given glyph identifier if
    /// available, preferring a COLRv1 representation over a COLRv0
    /// representation.
    pub fn get(&self, glyph_id: GlyphId) -> Option<ColorGlyph<'a>> {
        self.get_with_format(glyph_id, ColorGlyphFormat::ColrV1)
            .or_else(|| self.get_with_format(glyph_id, ColorGlyphFormat::ColrV0))
    }
}

#[cfg(test)]
mod tests {

    use crate::{
        color::traversal_tests::test_glyph_defs::PAINTCOLRGLYPH_CYCLE, prelude::LocationRef,
        MetadataProvider,
    };

    use read_fonts::{types::BoundingBox, FontRef};

    use super::{Brush, ColorPainter, CompositeMode, GlyphId, Transform};
    use crate::color::traversal_tests::test_glyph_defs::{COLORED_CIRCLES_V0, COLORED_CIRCLES_V1};

    #[test]
    fn has_colrv1_glyph_test() {
        let colr_font = font_test_data::COLRV0V1_VARIABLE;
        let font = FontRef::new(colr_font).unwrap();
        let get_colrv1_glyph = |codepoint: &[char]| {
            font.charmap().map(codepoint[0]).and_then(|glyph_id| {
                font.color_glyphs()
                    .get_with_format(glyph_id, crate::color::ColorGlyphFormat::ColrV1)
            })
        };

        assert!(get_colrv1_glyph(COLORED_CIRCLES_V0).is_none());
        assert!(get_colrv1_glyph(COLORED_CIRCLES_V1).is_some());
    }
    struct DummyColorPainter {}

    impl DummyColorPainter {
        pub fn new() -> Self {
            Self {}
        }
    }

    impl Default for DummyColorPainter {
        fn default() -> Self {
            Self::new()
        }
    }

    impl ColorPainter for DummyColorPainter {
        fn push_transform(&mut self, _transform: Transform) {}
        fn pop_transform(&mut self) {}
        fn push_clip_glyph(&mut self, _glyph: GlyphId) {}
        fn push_clip_box(&mut self, _clip_box: BoundingBox<f32>) {}
        fn pop_clip(&mut self) {}
        fn fill(&mut self, _brush: Brush) {}
        fn push_layer(&mut self, _composite_mode: CompositeMode) {}
        fn pop_layer(&mut self) {}
    }

    #[test]
    fn paintcolrglyph_cycle_test() {
        let colr_font = font_test_data::COLRV0V1_VARIABLE;
        let font = FontRef::new(colr_font).unwrap();
        let cycle_glyph_id = font.charmap().map(PAINTCOLRGLYPH_CYCLE[0]).unwrap();
        let colrv1_glyph = font
            .color_glyphs()
            .get_with_format(cycle_glyph_id, crate::color::ColorGlyphFormat::ColrV1);

        assert!(colrv1_glyph.is_some());
        let mut color_painter = DummyColorPainter::new();

        let result = colrv1_glyph
            .unwrap()
            .paint(LocationRef::default(), &mut color_painter);
        // Expected to fail with an error as the glyph contains a paint cycle.
        assert!(result.is_err());
    }

    #[test]
    fn no_cliplist_test() {
        let colr_font = font_test_data::COLRV1_NO_CLIPLIST;
        let font = FontRef::new(colr_font).unwrap();
        let cycle_glyph_id = GlyphId::new(1);
        let colrv1_glyph = font
            .color_glyphs()
            .get_with_format(cycle_glyph_id, crate::color::ColorGlyphFormat::ColrV1);

        assert!(colrv1_glyph.is_some());
        let mut color_painter = DummyColorPainter::new();

        let result = colrv1_glyph
            .unwrap()
            .paint(LocationRef::default(), &mut color_painter);
        assert!(result.is_ok());
    }
}