skrifa/

variation.rs

//! Axes of variation in a variable font.

use read_fonts::{
    tables::avar::Avar,
    tables::fvar::{self, Fvar},
    types::{Fixed, Tag},
    TableProvider,
};

use crate::{
    collections::SmallVec,
    instance::{Location, NormalizedCoord},
    setting::VariationSetting,
    string::StringId,
};

/// Axis of variation in a variable font.
///
/// In variable fonts, an axis usually refers to a single aspect of a
/// typeface's design that can be altered by the user.
///
/// See <https://fonts.google.com/knowledge/glossary/axis_in_variable_fonts>
#[derive(Clone)]
pub struct Axis {
    index: usize,
    record: fvar::VariationAxisRecord,
}

impl Axis {
    /// Returns the tag that identifies the axis.
    pub fn tag(&self) -> Tag {
        self.record.axis_tag()
    }

    /// Returns the index of the axis in its owning collection.
    pub fn index(&self) -> usize {
        self.index
    }

    /// Returns the localized string identifier for the name of the axis.
    pub fn name_id(&self) -> StringId {
        self.record.axis_name_id()
    }

    /// Returns true if the axis should be hidden in user interfaces.
    pub fn is_hidden(&self) -> bool {
        const AXIS_HIDDEN_FLAG: u16 = 0x1;
        self.record.flags() & AXIS_HIDDEN_FLAG != 0
    }

    /// Returns the minimum value of the axis.
    pub fn min_value(&self) -> f32 {
        self.record.min_value().to_f64() as _
    }

    /// Returns the default value of the axis.
    pub fn default_value(&self) -> f32 {
        self.record.default_value().to_f64() as _
    }

    /// Returns the maximum value of the axis.
    pub fn max_value(&self) -> f32 {
        self.record.max_value().to_f64() as _
    }

    /// Returns a normalized coordinate for the given user coordinate.
    ///
    /// The value will be clamped to the range specified by the minimum
    /// and maximum values.
    ///    
    /// This does not apply any axis variation remapping.
    pub fn normalize(&self, coord: f32) -> NormalizedCoord {
        self.record
            .normalize(Fixed::from_f64(coord as _))
            .to_f2dot14()
    }
}

/// Collection of axes in a variable font.
///
/// Converts user ([fvar](https://learn.microsoft.com/en-us/typography/opentype/spec/fvar))
/// locations to normalized locations. See [`Self::location`].
///
/// See the [`Axis`] type for more detail.
#[derive(Clone)]
pub struct AxisCollection<'a> {
    fvar: Option<Fvar<'a>>,
    avar: Option<Avar<'a>>,
}

impl<'a> AxisCollection<'a> {
    /// Creates a new axis collection from the given font.
    pub fn new(font: &impl TableProvider<'a>) -> Self {
        let fvar = font.fvar().ok();
        let avar = font.avar().ok();
        Self { fvar, avar }
    }

    /// Returns the number of variation axes in the font.
    pub fn len(&self) -> usize {
        self.fvar
            .as_ref()
            .map(|fvar| fvar.axis_count() as usize)
            .unwrap_or(0)
    }

    /// Returns true if the collection is empty.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Returns the axis at the given index.
    pub fn get(&self, index: usize) -> Option<Axis> {
        let record = *self.fvar.as_ref()?.axes().ok()?.get(index)?;
        Some(Axis { index, record })
    }

    /// Returns the axis with the given tag.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// let opsz = Tag::new(b"opsz");
    /// assert_eq!(font.axes().get_by_tag(opsz).unwrap().tag(), opsz);
    /// # }
    /// ```
    pub fn get_by_tag(&self, tag: Tag) -> Option<Axis> {
        self.iter().find(|axis| axis.tag() == tag)
    }

    /// Given an iterator of variation settings in user space, computes an
    /// ordered sequence of normalized coordinates.
    ///
    /// * Setting selectors that don't match an axis are ignored.
    /// * Setting values are clamped to the range of their associated axis
    ///     before normalization.
    /// * If more than one setting for an axis is provided, the last one is
    ///     used.
    /// * Omitted settings are set to 0.0, representing the default position
    ///     in variation space.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// let location = font.axes().location([("wght", 250.0), ("wdth", 75.0)]);
    /// # }
    /// ```
    pub fn location<I>(&self, settings: I) -> Location
    where
        I: IntoIterator,
        I::Item: Into<VariationSetting>,
    {
        let mut location = Location::new(self.len());
        self.location_to_slice(settings, location.coords_mut());
        location
    }

    /// Given an iterator of variation settings in user space, computes an
    /// ordered sequence of normalized coordinates and stores them in the
    /// target slice.
    ///
    /// * Setting selectors that don't match an axis are ignored.
    /// * Setting values are clamped to the range of their associated axis
    ///     before normalization.
    /// * If more than one setting for an axis is provided, the last one is
    ///     used.
    /// * If no setting for an axis is provided, the associated coordinate is
    ///     set to the normalized value 0.0, representing the default position
    ///     in variation space.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// let axes = font.axes();
    /// let mut location = vec![NormalizedCoord::default(); axes.len()];
    /// axes.location_to_slice([("wght", 250.0), ("wdth", 75.0)], &mut location);
    /// # }
    /// ```
    pub fn location_to_slice<I>(&self, settings: I, location: &mut [NormalizedCoord])
    where
        I: IntoIterator,
        I::Item: Into<VariationSetting>,
    {
        if let Some(fvar) = self.fvar.as_ref() {
            fvar.user_to_normalized(
                self.avar.as_ref(),
                settings
                    .into_iter()
                    .map(|setting| setting.into())
                    .map(|setting| (setting.selector, Fixed::from_f64(setting.value as f64))),
                location,
            );
        } else {
            location.fill(NormalizedCoord::default());
        }
    }

    /// Given an iterator of variation settings in user space, returns a
    /// new iterator yielding those settings that are valid for this axis
    /// collection.
    ///
    /// * Setting selectors that don't match an axis are dropped.
    /// * If more than one setting for an axis is provided, the last one is
    ///     retained.
    /// * Setting values are clamped to the range of their associated axis.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// // Assuming a font contains a single "wght" (weight) axis with range
    /// // 100-900:
    /// let axes = font.axes();
    /// let filtered: Vec<_> = axes
    ///     .filter([("wght", 400.0), ("opsz", 100.0), ("wght", 1200.0)])
    ///     .collect();
    /// // The first "wght" and "opsz" settings are dropped and the final
    /// // "wght" axis is clamped to the maximum value of 900.
    /// assert_eq!(&filtered, &[("wght", 900.0).into()]);
    /// # }
    /// ```
    pub fn filter<I>(&self, settings: I) -> impl Iterator<Item = VariationSetting> + Clone
    where
        I: IntoIterator,
        I::Item: Into<VariationSetting>,
    {
        #[derive(Copy, Clone, Default)]
        struct Entry {
            tag: Tag,
            min: f32,
            max: f32,
            value: f32,
            present: bool,
        }
        let mut results = SmallVec::<_, 8>::with_len(self.len(), Entry::default());
        for (axis, result) in self.iter().zip(results.as_mut_slice()) {
            result.tag = axis.tag();
            result.min = axis.min_value();
            result.max = axis.max_value();
            result.value = axis.default_value();
        }
        for setting in settings {
            let setting = setting.into();
            for entry in results.as_mut_slice() {
                if entry.tag == setting.selector {
                    entry.value = setting.value.max(entry.min).min(entry.max);
                    entry.present = true;
                }
            }
        }
        results
            .into_iter()
            .filter(|entry| entry.present)
            .map(|entry| VariationSetting::new(entry.tag, entry.value))
    }

    /// Returns an iterator over the axes in the collection.
    pub fn iter(&self) -> impl Iterator<Item = Axis> + 'a + Clone {
        let copy = self.clone();
        (0..self.len()).filter_map(move |i| copy.get(i))
    }
}

/// Named instance of a variation.
///
/// A set of fixed axis positions selected by the type designer and assigned a
/// name.
///
/// See <https://fonts.google.com/knowledge/glossary/instance>
#[derive(Clone)]
pub struct NamedInstance<'a> {
    axes: AxisCollection<'a>,
    record: fvar::InstanceRecord<'a>,
}

impl<'a> NamedInstance<'a> {
    /// Returns the string identifier for the subfamily name of the instance.
    pub fn subfamily_name_id(&self) -> StringId {
        self.record.subfamily_name_id
    }

    /// Returns the string identifier for the PostScript name of the instance.
    pub fn postscript_name_id(&self) -> Option<StringId> {
        self.record.post_script_name_id
    }

    /// Returns an iterator over the ordered sequence of user space coordinates
    /// that define the instance, one coordinate per axis.
    pub fn user_coords(&self) -> impl Iterator<Item = f32> + 'a + Clone {
        self.record
            .coordinates
            .iter()
            .map(|coord| coord.get().to_f64() as _)
    }

    /// Computes a location in normalized variation space for this instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// let location = font.named_instances().get(0).unwrap().location();
    /// # }
    /// ```
    pub fn location(&self) -> Location {
        let mut location = Location::new(self.axes.len());
        self.location_to_slice(location.coords_mut());
        location
    }

    /// Computes a location in normalized variation space for this instance and
    /// stores the result in the given slice.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use skrifa::prelude::*;
    /// # fn wrapper(font: &FontRef) {
    /// let instance = font.named_instances().get(0).unwrap();
    /// let mut location = vec![NormalizedCoord::default(); instance.user_coords().count()];
    /// instance.location_to_slice(&mut location);
    /// # }
    /// ```
    pub fn location_to_slice(&self, location: &mut [NormalizedCoord]) {
        let settings = self
            .axes
            .iter()
            .map(|axis| axis.tag())
            .zip(self.user_coords());
        self.axes.location_to_slice(settings, location);
    }
}

/// Collection of named instances in a variable font.
///
/// See the [`NamedInstance`] type for more detail.
#[derive(Clone)]
pub struct NamedInstanceCollection<'a> {
    axes: AxisCollection<'a>,
}

impl<'a> NamedInstanceCollection<'a> {
    /// Creates a new instance collection from the given font.
    pub fn new(font: &impl TableProvider<'a>) -> Self {
        Self {
            axes: AxisCollection::new(font),
        }
    }

    /// Returns the number of instances in the collection.
    pub fn len(&self) -> usize {
        self.axes
            .fvar
            .as_ref()
            .map(|fvar| fvar.instance_count() as usize)
            .unwrap_or(0)
    }

    /// Returns true if the collection is empty.
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Returns the instance at the given index.
    pub fn get(&self, index: usize) -> Option<NamedInstance<'a>> {
        let record = self.axes.fvar.as_ref()?.instances().ok()?.get(index).ok()?;
        Some(NamedInstance {
            axes: self.axes.clone(),
            record,
        })
    }

    /// Returns an iterator over the instances in the collection.
    pub fn iter(&self) -> impl Iterator<Item = NamedInstance<'a>> + 'a + Clone {
        let copy = self.clone();
        (0..self.len()).filter_map(move |i| copy.get(i))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::MetadataProvider as _;
    use font_test_data::VAZIRMATN_VAR;
    use read_fonts::FontRef;
    use std::str::FromStr;

    #[test]
    fn axis() {
        let font = FontRef::from_index(VAZIRMATN_VAR, 0).unwrap();
        let axis = font.axes().get(0).unwrap();
        assert_eq!(axis.index(), 0);
        assert_eq!(axis.tag(), Tag::new(b"wght"));
        assert_eq!(axis.min_value(), 100.0);
        assert_eq!(axis.default_value(), 400.0);
        assert_eq!(axis.max_value(), 900.0);
        assert_eq!(axis.name_id(), StringId::new(257));
        assert_eq!(
            font.localized_strings(axis.name_id())
                .english_or_first()
                .unwrap()
                .to_string(),
            "Weight"
        );
    }

    #[test]
    fn named_instances() {
        let font = FontRef::from_index(VAZIRMATN_VAR, 0).unwrap();
        let named_instances = font.named_instances();
        let thin = named_instances.get(0).unwrap();
        assert_eq!(thin.subfamily_name_id(), StringId::new(258));
        assert_eq!(
            font.localized_strings(thin.subfamily_name_id())
                .english_or_first()
                .unwrap()
                .to_string(),
            "Thin"
        );
        assert_eq!(thin.location().coords(), &[NormalizedCoord::from_f32(-1.0)]);
        let regular = named_instances.get(3).unwrap();
        assert_eq!(regular.subfamily_name_id(), StringId::new(261));
        assert_eq!(
            font.localized_strings(regular.subfamily_name_id())
                .english_or_first()
                .unwrap()
                .to_string(),
            "Regular"
        );
        assert_eq!(
            regular.location().coords(),
            &[NormalizedCoord::from_f32(0.0)]
        );
        let bold = named_instances.get(6).unwrap();
        assert_eq!(bold.subfamily_name_id(), StringId::new(264));
        assert_eq!(
            font.localized_strings(bold.subfamily_name_id())
                .english_or_first()
                .unwrap()
                .to_string(),
            "Bold"
        );
        assert_eq!(
            bold.location().coords(),
            &[NormalizedCoord::from_f32(0.6776123)]
        );
    }

    #[test]
    fn location() {
        let font = FontRef::from_index(VAZIRMATN_VAR, 0).unwrap();
        let axes = font.axes();
        let axis = axes.get_by_tag(Tag::from_str("wght").unwrap()).unwrap();
        assert_eq!(
            axes.location([("wght", -1000.0)]).coords(),
            &[NormalizedCoord::from_f32(-1.0)]
        );
        assert_eq!(
            axes.location([("wght", 100.0)]).coords(),
            &[NormalizedCoord::from_f32(-1.0)]
        );
        assert_eq!(
            axes.location([("wght", 200.0)]).coords(),
            &[NormalizedCoord::from_f32(-0.5)]
        );
        assert_eq!(
            axes.location([("wght", 400.0)]).coords(),
            &[NormalizedCoord::from_f32(0.0)]
        );
        // avar table maps 0.8 to 0.83875
        assert_eq!(
            axes.location(&[(
                "wght",
                axis.default_value() + (axis.max_value() - axis.default_value()) * 0.8,
            )])
            .coords(),
            &[NormalizedCoord::from_f32(0.83875)]
        );
        assert_eq!(
            axes.location([("wght", 900.0)]).coords(),
            &[NormalizedCoord::from_f32(1.0)]
        );
        assert_eq!(
            axes.location([("wght", 1251.5)]).coords(),
            &[NormalizedCoord::from_f32(1.0)]
        );
    }

    #[test]
    fn filter() {
        let font = FontRef::from_index(VAZIRMATN_VAR, 0).unwrap();
        // This font contains one wght axis with the range 100-900 and default
        // value of 400.
        let axes = font.axes();
        // Drop axes that are not present in the font
        let drop_missing: Vec<_> = axes.filter(&[("slnt", 25.0), ("wdth", 50.0)]).collect();
        assert_eq!(&drop_missing, &[]);
        // Clamp an out of range value
        let clamp: Vec<_> = axes.filter(&[("wght", 50.0)]).collect();
        assert_eq!(&clamp, &[("wght", 100.0).into()]);
        // Combination of the above two: drop the missing axis and clamp out of range value
        let drop_missing_and_clamp: Vec<_> =
            axes.filter(&[("slnt", 25.0), ("wght", 1000.0)]).collect();
        assert_eq!(&drop_missing_and_clamp, &[("wght", 900.0).into()]);
        // Ensure we take the later value in the case of duplicates
        let drop_duplicate_and_missing: Vec<_> = axes
            .filter(&[("wght", 400.0), ("opsz", 100.0), ("wght", 120.5)])
            .collect();
        assert_eq!(&drop_duplicate_and_missing, &[("wght", 120.5).into()]);
    }
}