From f6eb81a33ea31dbf8d597f54ca9167ddd85e6c48 Mon Sep 17 00:00:00 2001 From: Alex Butler Date: Fri, 21 Jun 2024 23:40:13 +0100 Subject: [PATCH] Add font glyph layout concepts docs --- glyph/CHANGELOG.md | 4 ++++ glyph/src/font.rs | 31 +++++++++++++++++++++++++++---- glyph/src/glyph.rs | 4 ++++ glyph/src/scale.rs | 10 ++++++---- 4 files changed, 41 insertions(+), 8 deletions(-) diff --git a/glyph/CHANGELOG.md b/glyph/CHANGELOG.md index 1b71724..6edced3 100644 --- a/glyph/CHANGELOG.md +++ b/glyph/CHANGELOG.md @@ -1,3 +1,7 @@ +# Unreleased +* Add `Font` glyph layout concept documentation demonstrating "ascent", "descent", "h_side_bearing", + "h_advance", "height", "line_gap", "baseline". + # 0.2.26 * Update _ttf-parser_ to `0.21`. diff --git a/glyph/src/font.rs b/glyph/src/font.rs index 3025c65..6ee49d1 100644 --- a/glyph/src/font.rs +++ b/glyph/src/font.rs @@ -15,6 +15,27 @@ use crate::{ /// /// ab_glyph uses a non-standard scale [`PxScale`] which is the pixel height /// of the text. See [`Font::pt_to_px_scale`] to convert standard point sizes. +/// +/// ## Glyph layout concepts +/// Fonts provide several properties to inform layout of glyphs. +/// ```text +/// ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾ +/// | .:x++++== | +/// | .#+ | +/// | :@ =++=++x=: | +/// ascent | +# x: +x x+ | +/// | =# #: :#:---:#: | height +/// | -@- #: .#--:-- | +/// | =#:-.-==#: #x+===:. | +/// baseline ____________ .-::-. .. #: .:@. | +/// | #+--..-=#. | +/// descent | -::=::- | +/// ____________________________________ +/// | | | | line_gap +/// | | h_advance | ‾ +/// ^ +/// h_side_bearing +/// ``` pub trait Font { /// Get the size of the font unit /// @@ -56,17 +77,17 @@ pub trait Font { Some(PxScale::from(px_per_em * height / units_per_em)) } - /// Unscaled glyph ascent. + /// Unscaled glyph ascent. See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Scaling can be done with [`as_scaled`](Self::as_scaled). fn ascent_unscaled(&self) -> f32; - /// Unscaled glyph descent. + /// Unscaled glyph descent. See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Scaling can be done with [`as_scaled`](Self::as_scaled). fn descent_unscaled(&self) -> f32; - /// Unscaled height `ascent - descent`. + /// Unscaled height `ascent - descent`. See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Scaling can be done with [`as_scaled`](Self::as_scaled). #[inline] @@ -74,7 +95,7 @@ pub trait Font { self.ascent_unscaled() - self.descent_unscaled() } - /// Unscaled line gap. + /// Unscaled line gap. See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Scaling can be done with [`as_scaled`](Self::as_scaled). fn line_gap_unscaled(&self) -> f32; @@ -85,6 +106,7 @@ pub trait Font { fn glyph_id(&self, c: char) -> GlyphId; /// Unscaled horizontal advance for a given glyph id. + /// See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Returns `0.0` if the font does not define this value. /// @@ -92,6 +114,7 @@ pub trait Font { fn h_advance_unscaled(&self, id: GlyphId) -> f32; /// Unscaled horizontal side bearing for a given glyph id. + /// See [glyph layout concepts](Font#glyph-layout-concepts). /// /// Returns `0.0` if the font does not define this value. /// diff --git a/glyph/src/glyph.rs b/glyph/src/glyph.rs index 5cf7247..c40d5a0 100644 --- a/glyph/src/glyph.rs +++ b/glyph/src/glyph.rs @@ -58,6 +58,10 @@ pub struct Glyph { /// Pixel scale of this glyph. pub scale: PxScale, /// Position of this glyph. + /// + /// Horizontally this is to the left of the glyph before applying + /// `h_advance` or `h_side_bearing`. Vertically this is at the "baseline". + /// See [glyph layout concepts](trait.Font.html#glyph-layout-concepts). pub position: Point, } diff --git a/glyph/src/scale.rs b/glyph/src/scale.rs index 31875e5..01c5870 100644 --- a/glyph/src/scale.rs +++ b/glyph/src/scale.rs @@ -103,19 +103,19 @@ pub trait ScaleFont { } } - /// Pixel scaled glyph ascent. + /// Pixel scaled glyph ascent. See [glyph layout concepts](Font#glyph-layout-concepts). #[inline] fn ascent(&self) -> f32 { self.v_scale_factor() * self.font().ascent_unscaled() } - /// Pixel scaled glyph descent. + /// Pixel scaled glyph descent. See [glyph layout concepts](Font#glyph-layout-concepts). #[inline] fn descent(&self) -> f32 { self.v_scale_factor() * self.font().descent_unscaled() } - /// Pixel scaled height `ascent - descent`. + /// Pixel scaled height `ascent - descent`. See [glyph layout concepts](Font#glyph-layout-concepts). /// /// By definition of [`PxScale`], this is `self.scale().y`. #[inline] @@ -123,7 +123,7 @@ pub trait ScaleFont { self.scale().y } - /// Pixel scaled line gap. + /// Pixel scaled line gap. See [glyph layout concepts](Font#glyph-layout-concepts). #[inline] fn line_gap(&self) -> f32 { self.v_scale_factor() * self.font().line_gap_unscaled() @@ -157,12 +157,14 @@ pub trait ScaleFont { } /// Pixel scaled horizontal advance for a given glyph. + /// See [glyph layout concepts](Font#glyph-layout-concepts). #[inline] fn h_advance(&self, id: GlyphId) -> f32 { self.h_scale_factor() * self.font().h_advance_unscaled(id) } /// Pixel scaled horizontal side bearing for a given glyph. + /// See [glyph layout concepts](Font#glyph-layout-concepts). #[inline] fn h_side_bearing(&self, id: GlyphId) -> f32 { self.h_scale_factor() * self.font().h_side_bearing_unscaled(id)