Add _unscaled to methods returning f32 unscaled metrics (#3)

* Add `_unscaled` to methods returning f32 unscaled metrics
* Add some missing docs

glyph/src/font.rs

@@ -6,31 +6,47 @@ use crate::{Glyph, GlyphId, Outline, OutlinedGlyph, PxScale, PxScaleFont};
 /// [`FontVec`](struct.FontVec.html).
 pub trait Font {
     /// Unscaled glyph ascent.
-    fn ascent(&self) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn ascent_unscaled(&self) -> f32;
 
     /// Unscaled glyph descent.
-    fn descent(&self) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn descent_unscaled(&self) -> f32;
 
     /// Unscaled height `ascent - descent`.
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
     #[inline]
-    fn height(&self) -> f32 {
-        self.ascent() - self.descent()
+    fn height_unscaled(&self) -> f32 {
+        self.ascent_unscaled() - self.descent_unscaled()
     }
 
     /// Unscaled line gap.
-    fn line_gap(&self) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn line_gap_unscaled(&self) -> f32;
 
     /// Lookup a `GlyphId` matching a given `char`.
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
     fn glyph_id(&self, c: char) -> GlyphId;
 
     /// Unscaled horizontal advance for a given glyph id.
-    fn h_advance(&self, id: GlyphId) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn h_advance_unscaled(&self, id: GlyphId) -> f32;
 
     /// Unscaled horizontal side bearing for a given glyph id.
-    fn h_side_bearing(&self, id: GlyphId) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32;
 
     /// Returns additional unscaled kerning to apply for a particular pair of glyph ids.
-    fn kern(&self, first: GlyphId, second: GlyphId) -> f32;
+    ///
+    /// Scaling can be done with [as_scaled](trait.Font.html#method.as_scaled).
+    fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32;
 
     /// Compute unscaled glyph outline curves & bounding box.
     fn outline(&self, id: GlyphId) -> Option<Outline>;
@@ -60,8 +76,7 @@ pub trait Font {
     /// # fn main() -> Result<(), ab_glyph::InvalidFont> {
     /// let font = FontRef::try_from_slice(include_bytes!("../../dev/fonts/Exo2-Light.otf"))?;
     ///
-    /// // unscaled descent
-    /// assert_eq!(font.descent(), -201.0);
+    /// assert_eq!(font.descent_unscaled(), -201.0);
     ///
     /// assert_eq!(font.as_scaled(24.0).descent(), -4.02);
     /// assert_eq!(font.as_scaled(50.0).descent(), -8.375);
@@ -94,18 +109,18 @@ pub trait Font {
 
 impl<F: Font> Font for &F {
     #[inline]
-    fn ascent(&self) -> f32 {
-        (*self).ascent()
+    fn ascent_unscaled(&self) -> f32 {
+        (*self).ascent_unscaled()
     }
 
     #[inline]
-    fn descent(&self) -> f32 {
-        (*self).descent()
+    fn descent_unscaled(&self) -> f32 {
+        (*self).descent_unscaled()
     }
 
     #[inline]
-    fn line_gap(&self) -> f32 {
-        (*self).line_gap()
+    fn line_gap_unscaled(&self) -> f32 {
+        (*self).line_gap_unscaled()
     }
 
     #[inline]
@@ -114,18 +129,18 @@ impl<F: Font> Font for &F {
     }
 
     #[inline]
-    fn h_advance(&self, id: GlyphId) -> f32 {
-        (*self).h_advance(id)
+    fn h_advance_unscaled(&self, id: GlyphId) -> f32 {
+        (*self).h_advance_unscaled(id)
     }
 
     #[inline]
-    fn h_side_bearing(&self, id: GlyphId) -> f32 {
-        (*self).h_side_bearing(id)
+    fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32 {
+        (*self).h_side_bearing_unscaled(id)
     }
 
     #[inline]
-    fn kern(&self, first: GlyphId, second: GlyphId) -> f32 {
-        (*self).kern(first, second)
+    fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32 {
+        (*self).kern_unscaled(first, second)
     }
 
     #[inline]

glyph/src/font_arc.rs

@@ -72,18 +72,18 @@ impl fmt::Debug for FontArc {
 
 impl Font for FontArc {
     #[inline]
-    fn ascent(&self) -> f32 {
-        self.0.ascent()
+    fn ascent_unscaled(&self) -> f32 {
+        self.0.ascent_unscaled()
     }
 
     #[inline]
-    fn descent(&self) -> f32 {
-        self.0.descent()
+    fn descent_unscaled(&self) -> f32 {
+        self.0.descent_unscaled()
     }
 
     #[inline]
-    fn line_gap(&self) -> f32 {
-        self.0.line_gap()
+    fn line_gap_unscaled(&self) -> f32 {
+        self.0.line_gap_unscaled()
     }
 
     #[inline]
@@ -92,18 +92,18 @@ impl Font for FontArc {
     }
 
     #[inline]
-    fn h_advance(&self, id: GlyphId) -> f32 {
-        self.0.h_advance(id)
+    fn h_advance_unscaled(&self, id: GlyphId) -> f32 {
+        self.0.h_advance_unscaled(id)
     }
 
     #[inline]
-    fn h_side_bearing(&self, id: GlyphId) -> f32 {
-        self.0.h_side_bearing(id)
+    fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32 {
+        self.0.h_side_bearing_unscaled(id)
     }
 
     #[inline]
-    fn kern(&self, first: GlyphId, second: GlyphId) -> f32 {
-        self.0.kern(first, second)
+    fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32 {
+        self.0.kern_unscaled(first, second)
     }
 
     #[inline]

glyph/src/outlined.rs

@@ -4,7 +4,7 @@ use crate::{point, Glyph, Point, PxScaleFactor};
 #[cfg(not(feature = "std"))]
 use alloc::vec::Vec;
 
-// A "raw" collection of outline curves for a glyph, unscaled & unpositioned.
+/// A "raw" collection of outline curves for a glyph, unscaled & unpositioned.
 #[derive(Clone, Debug)]
 pub struct Outline {
     /// Unscaled bounding box.

glyph/src/scale.rs

@@ -24,6 +24,7 @@ impl From<f32> for PxScale {
     }
 }
 
+/// 2D scale factors for use with unscaled metrics.
 #[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
 pub struct PxScaleFactor {
     pub horizontal: f32,
@@ -63,13 +64,13 @@ pub trait ScaleFont<F: Font> {
     /// Scale factor for unscaled font horizontal values.
     #[inline]
     fn h_scale_factor(&self) -> f32 {
-        self.scale().x / self.font().height()
+        self.scale().x / self.font().height_unscaled()
     }
 
     /// Scale factor for unscaled font vertical values.
     #[inline]
     fn v_scale_factor(&self) -> f32 {
-        self.scale().y / self.font().height()
+        self.scale().y / self.font().height_unscaled()
     }
 
     #[inline]
@@ -83,13 +84,13 @@ pub trait ScaleFont<F: Font> {
     /// Pixel scaled glyph ascent.
     #[inline]
     fn ascent(&self) -> f32 {
-        self.v_scale_factor() * self.font().ascent()
+        self.v_scale_factor() * self.font().ascent_unscaled()
     }
 
     /// Pixel scaled glyph descent.
     #[inline]
     fn descent(&self) -> f32 {
-        self.v_scale_factor() * self.font().descent()
+        self.v_scale_factor() * self.font().descent_unscaled()
     }
 
     /// Pixel scaled height `ascent - descent`.
@@ -101,7 +102,7 @@ pub trait ScaleFont<F: Font> {
     /// Pixel scaled line gap.
     #[inline]
     fn line_gap(&self) -> f32 {
-        self.v_scale_factor() * self.font().line_gap()
+        self.v_scale_factor() * self.font().line_gap_unscaled()
     }
 
     /// Lookup a `GlyphId` matching a given `char`.
@@ -134,19 +135,19 @@ pub trait ScaleFont<F: Font> {
     /// Pixel scaled horizontal advance for a given glyph.
     #[inline]
     fn h_advance(&self, id: GlyphId) -> f32 {
-        self.h_scale_factor() * self.font().h_advance(id)
+        self.h_scale_factor() * self.font().h_advance_unscaled(id)
     }
 
     /// Pixel scaled horizontal side bearing for a given glyph.
     #[inline]
     fn h_side_bearing(&self, id: GlyphId) -> f32 {
-        self.h_scale_factor() * self.font().h_side_bearing(id)
+        self.h_scale_factor() * self.font().h_side_bearing_unscaled(id)
     }
 
     /// Returns additional pixel scaled kerning to apply for a particular pair of glyphs.
     #[inline]
     fn kern(&self, first: GlyphId, second: GlyphId) -> f32 {
-        self.h_scale_factor() * self.font().kern(first, second)
+        self.h_scale_factor() * self.font().kern_unscaled(first, second)
     }
 
     /// The number of glyphs present in this font. Glyph identifiers for this

glyph/src/ttfp.rs

@@ -146,17 +146,17 @@ macro_rules! impl_font {
     ($font:ty) => {
         impl Font for $font {
             #[inline]
-            fn ascent(&self) -> f32 {
+            fn ascent_unscaled(&self) -> f32 {
                 f32::from(self.0.as_font().ascender())
             }
 
             #[inline]
-            fn descent(&self) -> f32 {
+            fn descent_unscaled(&self) -> f32 {
                 f32::from(self.0.as_font().descender())
             }
 
             #[inline]
-            fn line_gap(&self) -> f32 {
+            fn line_gap_unscaled(&self) -> f32 {
                 f32::from(self.0.as_font().line_gap())
             }
 
@@ -167,7 +167,7 @@ macro_rules! impl_font {
             }
 
             #[inline]
-            fn h_advance(&self, id: GlyphId) -> f32 {
+            fn h_advance_unscaled(&self, id: GlyphId) -> f32 {
                 let advance = self
                     .0
                     .as_font()
@@ -177,7 +177,7 @@ macro_rules! impl_font {
             }
 
             #[inline]
-            fn h_side_bearing(&self, id: GlyphId) -> f32 {
+            fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32 {
                 let advance = self
                     .0
                     .as_font()
@@ -187,7 +187,7 @@ macro_rules! impl_font {
             }
 
             #[inline]
-            fn kern(&self, first: GlyphId, second: GlyphId) -> f32 {
+            fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32 {
                 self.0
                     .as_font()
                     .glyphs_kerning(first.into(), second.into())