Replace magic boolean with new Hinting enum

src/buffer.rs

@@ -11,8 +11,8 @@ use unicode_segmentation::UnicodeSegmentation;
 
 use crate::{
     Affinity, Align, Attrs, AttrsList, BidiParagraphs, BorrowedWithFontSystem, BufferLine, Color,
-    Cursor, FontSystem, LayoutCursor, LayoutGlyph, LayoutLine, LineEnding, LineIter, Motion,
-    Renderer, Scroll, ShapeLine, Shaping, Wrap,
+    Cursor, FontSystem, Hinting, LayoutCursor, LayoutGlyph, LayoutLine, LineEnding, LineIter,
+    Motion, Renderer, Scroll, ShapeLine, Shaping, Wrap,
 };
 
 /// A line of visible text for rendering
@@ -216,7 +216,7 @@ pub struct Buffer {
     wrap: Wrap,
     monospace_width: Option<f32>,
     tab_width: u16,
-    hint: bool,
+    hint: Hinting,
 }
 
 impl Clone for Buffer {
@@ -248,7 +248,7 @@ impl Buffer {
     /// # Panics
     ///
     /// Will panic if `metrics.line_height` is zero.
-    pub fn new_empty(metrics: Metrics, hint: bool) -> Self {
+    pub fn new_empty(metrics: Metrics, hint: Hinting) -> Self {
         assert_ne!(metrics.line_height, 0.0, "line height cannot be 0");
         Self {
             lines: Vec::new(),
@@ -269,7 +269,7 @@ impl Buffer {
     /// # Panics
     ///
     /// Will panic if `metrics.line_height` is zero.
-    pub fn new(font_system: &mut FontSystem, metrics: Metrics, hint: bool) -> Self {
+    pub fn new(font_system: &mut FontSystem, metrics: Metrics, hint: Hinting) -> Self {
         let mut buffer = Self::new_empty(metrics, hint);
         buffer.set_text(font_system, "", &Attrs::new(), Shaping::Advanced, None);
         buffer
@@ -722,9 +722,9 @@ impl Buffer {
     /// Set text of buffer, using an iterator of styled spans (pairs of text and attributes)
     ///
     /// ```
-    /// # use cosmic_text::{Attrs, Buffer, Family, FontSystem, Metrics, Shaping};
+    /// # use cosmic_text::{Attrs, Buffer, Family, FontSystem, Metrics, Hinting, Shaping};
     /// # let mut font_system = FontSystem::new();
-    /// let mut buffer = Buffer::new_empty(Metrics::new(32.0, 44.0), false);
+    /// let mut buffer = Buffer::new_empty(Metrics::new(32.0, 44.0), Hinting::Disabled);
     /// let attrs = Attrs::new().family(Family::Serif);
     /// buffer.set_rich_text(
     ///     &mut font_system,
@@ -1451,9 +1451,9 @@ impl BorrowedWithFontSystem<'_, Buffer> {
     /// Set text of buffer, using an iterator of styled spans (pairs of text and attributes)
     ///
     /// ```
-    /// # use cosmic_text::{Attrs, Buffer, Family, FontSystem, Metrics, Shaping};
+    /// # use cosmic_text::{Attrs, Buffer, Family, FontSystem, Metrics, Hinting, Shaping};
     /// # let mut font_system = FontSystem::new();
-    /// let mut buffer = Buffer::new_empty(Metrics::new(32.0, 44.0), false);
+    /// let mut buffer = Buffer::new_empty(Metrics::new(32.0, 44.0), Hinting::Disabled);
     /// let attrs = Attrs::new().family(Family::Serif);
     /// buffer.set_rich_text(
     ///     &mut font_system,

src/buffer_line.rs

@@ -3,7 +3,8 @@ use alloc::{string::String, vec::Vec};
 use core::mem;
 
 use crate::{
-    Align, Attrs, AttrsList, Cached, FontSystem, LayoutLine, LineEnding, ShapeLine, Shaping, Wrap,
+    Align, Attrs, AttrsList, Cached, FontSystem, Hinting, LayoutLine, LineEnding, ShapeLine,
+    Shaping, Wrap,
 };
 
 /// A line (or paragraph) of text that is shaped and laid out
@@ -243,7 +244,7 @@ impl BufferLine {
         wrap: Wrap,
         match_mono_width: Option<f32>,
         tab_width: u16,
-        hint: bool,
+        hint: Hinting,
     ) -> &[LayoutLine] {
         if self.layout_opt.is_unused() {
             let align = self.align;

src/layout.rs

@@ -151,3 +151,28 @@ impl Display for Align {
         }
     }
 }
+
+/// Metrics hinting strategy
+#[derive(Debug, Eq, PartialEq, Clone, Copy, Default)]
+pub enum Hinting {
+    /// No metrics hinting.
+    ///
+    /// Glyphs will have subpixel coordinates.
+    ///
+    /// This is the default.
+    #[default]
+    Disabled,
+
+    /// Metrics hinting.
+    ///
+    /// Glyphs will be snapped to integral coordinates in the X-axis during layout.
+    /// This can improve readability for smaller text and/or low-DPI screens.
+    ///
+    /// However, in order to get the right effect, you must use physical coordinates
+    /// during layout and avoid further scaling when rendering. Otherwise, the rounding
+    /// errors can accumulate and glyph distances may look erratic.
+    ///
+    /// In other words, metrics hinting makes layouting dependent of the target
+    /// resolution.
+    Enabled,
+}

src/lib.rs

@@ -12,7 +12,7 @@
 //! point, you can use the `SwashCache` to rasterize glyphs into either images or pixels.
 //!
 //! ```
-//! use cosmic_text::{Attrs, Color, FontSystem, SwashCache, Buffer, Metrics, Shaping};
+//! use cosmic_text::{Attrs, Color, FontSystem, SwashCache, Buffer, Metrics, Hinting, Shaping};
 //!
 //! // A FontSystem provides access to detected system fonts, create one per application
 //! let mut font_system = FontSystem::new();
@@ -24,7 +24,7 @@
 //! let metrics = Metrics::new(14.0, 20.0);
 //!
 //! // A Buffer provides shaping and layout for a UTF-8 string, create one per text widget
-//! let mut buffer = Buffer::new(&mut font_system, metrics, false);
+//! let mut buffer = Buffer::new(&mut font_system, metrics, Hinting::Disabled);
 //!
 //! // Borrow buffer together with the font system for more convenient method calls
 //! let mut buffer = buffer.borrow_with(&mut font_system);

src/shape.rs

@@ -4,8 +4,8 @@
 
 use crate::fallback::FontFallbackIter;
 use crate::{
-    math, Align, AttrsList, CacheKeyFlags, Color, Font, FontSystem, LayoutGlyph, LayoutLine,
-    Metrics, Wrap,
+    math, Align, AttrsList, CacheKeyFlags, Color, Font, FontSystem, Hinting, LayoutGlyph,
+    LayoutLine, Metrics, Wrap,
 };
 #[cfg(not(feature = "std"))]
 use alloc::vec::Vec;
@@ -1152,7 +1152,7 @@ impl ShapeLine {
         wrap: Wrap,
         align: Option<Align>,
         match_mono_width: Option<f32>,
-        hint: bool,
+        hinting: Hinting,
     ) -> Vec<LayoutLine> {
         let mut lines = Vec::with_capacity(1);
         self.layout_to_buffer(
@@ -1163,7 +1163,7 @@ impl ShapeLine {
             align,
             &mut lines,
             match_mono_width,
-            hint,
+            hinting,
         );
         lines
     }
@@ -1177,7 +1177,7 @@ impl ShapeLine {
         align: Option<Align>,
         layout_lines: &mut Vec<LayoutLine>,
         match_mono_width: Option<f32>,
-        hint: bool,
+        hinting: Hinting,
     ) {
         fn add_to_visual_line(
             vl: &mut VisualLine,
@@ -1553,7 +1553,7 @@ impl ShapeLine {
                 x += alignment_correction;
             }
 
-            if hint {
+            if hinting == Hinting::Enabled {
                 x = x.round();
             }
 
@@ -1635,7 +1635,7 @@ impl ShapeLine {
                                 // Round to nearest monospace width
                                 x_advance = ((x_advance / match_em_width).round()) * match_em_width;
                             }
-                            if hint {
+                            if hinting == Hinting::Enabled {
                                 x_advance = x_advance.round();
                             }
                             if self.rtl {