Trait gfx_glyph::ab_glyph::Font

pub trait Font {
    // Required methods
    fn units_per_em(&self) -> Option<f32>;
    fn ascent_unscaled(&self) -> f32;
    fn descent_unscaled(&self) -> f32;
    fn line_gap_unscaled(&self) -> f32;
    fn glyph_id(&self, c: char) -> GlyphId;
    fn h_advance_unscaled(&self, id: GlyphId) -> f32;
    fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32;
    fn v_advance_unscaled(&self, id: GlyphId) -> f32;
    fn v_side_bearing_unscaled(&self, id: GlyphId) -> f32;
    fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32;
    fn outline(&self, id: GlyphId) -> Option<Outline>;
    fn glyph_count(&self) -> usize;
    fn codepoint_ids(&self) -> CodepointIdIter<'_> ;
    fn glyph_raster_image(
        &self,
        id: GlyphId,
        pixel_size: u16
    ) -> Option<GlyphImage<'_>>;

    // Provided methods
    fn pt_to_px_scale(&self, pt_size: f32) -> Option<PxScale> { ... }
    fn height_unscaled(&self) -> f32 { ... }
    fn glyph_bounds(&self, glyph: &Glyph) -> Rect
       where Self: Sized { ... }
    fn outline_glyph(&self, glyph: Glyph) -> Option<OutlinedGlyph>
       where Self: Sized { ... }
    fn as_scaled<S>(&self, scale: S) -> PxScaleFont<&Self>
       where S: Into<PxScale>,
             Self: Sized { ... }
    fn into_scaled<S>(self, scale: S) -> PxScaleFont<Self>
       where S: Into<PxScale>,
             Self: Sized { ... }
}

Functionality required from font data.

See also FontArc, FontRef and FontVec.

Units

Units of unscaled accessors are “font units”, which is an arbitrary unit defined by the font. See Font::units_per_em.

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.

Required Methods

fn units_per_em(&self) -> Option<f32>

Get the size of the font unit

This returns “font units per em”, where 1em is a base unit of font scale (typically the width of a capital ‘M’).

Returns None in case the font unit size exceeds the expected range. See Face::units_per_em.

May be used to calculate PxScale from pt size, see Font::pt_to_px_scale.

fn ascent_unscaled(&self) -> f32

Unscaled glyph ascent.

Scaling can be done with as_scaled.

fn descent_unscaled(&self) -> f32

Unscaled glyph descent.

Scaling can be done with as_scaled.

fn line_gap_unscaled(&self) -> f32

Unscaled line gap.

Scaling can be done with as_scaled.

fn glyph_id(&self, c: char) -> GlyphId

Lookup a GlyphId matching a given char.

Scaling can be done with as_scaled.

fn h_advance_unscaled(&self, id: GlyphId) -> f32

Unscaled horizontal advance for a given glyph id.

Scaling can be done with as_scaled.

fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32

Unscaled horizontal side bearing for a given glyph id.

Scaling can be done with as_scaled.

fn v_advance_unscaled(&self, id: GlyphId) -> f32

Unscaled vertical advance for a given glyph id.

Scaling can be done with as_scaled.

fn v_side_bearing_unscaled(&self, id: GlyphId) -> f32

Unscaled vertical side bearing for a given glyph id.

Scaling can be done with as_scaled.

fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32

Returns additional unscaled kerning to apply for a particular pair of glyph ids.

Scaling can be done with as_scaled.

fn outline(&self, id: GlyphId) -> Option<Outline>

Compute unscaled glyph outline curves & bounding box.

fn glyph_count(&self) -> usize

The number of glyphs present in this font. Glyph identifiers for this font will always be in the range 0..self.glyph_count()

fn codepoint_ids(&self) -> CodepointIdIter<'_>

Returns an iterator of all distinct (GlyphId, char) pairs. Not ordered.

Example

let font = FontRef::try_from_slice(include_bytes!("../../dev/fonts/Exo2-Light.otf"))?;

// Iterate over pairs, each id will appear at most once.
let mut codepoint_ids = font.codepoint_ids();
assert_eq!(codepoint_ids.next(), Some((GlyphId(408), '\r')));
assert_eq!(codepoint_ids.next(), Some((GlyphId(1), ' ')));
assert_eq!(codepoint_ids.next(), Some((GlyphId(75), '!')));

// Build a lookup map for all ids
let map: HashMap<_, _> = font.codepoint_ids().collect();
assert_eq!(map.get(&GlyphId(75)), Some(&'!'));

fn glyph_raster_image( &self, id: GlyphId, pixel_size: u16 ) -> Option<GlyphImage<'_>>

Returns a pre-rendered image of the glyph.

This is normally only present when an outline is not sufficient to describe the glyph, such as emojis (particularly color ones). The pixel_size parameter is in pixels per em, and will be used to select between multiple possible images (if present); the returned image will likely not match this value, requiring you to scale it to match the target resolution. To get the largest image use u16::MAX.

Provided Methods

fn pt_to_px_scale(&self, pt_size: f32) -> Option<PxScale>

Converts pt units into PxScale.

Note: To handle a screen scale factor multiply it to the pt_size argument.

Returns None in case the Font::units_per_em unit size exceeds the expected range.

Point size (pt)

Font sizes are typically specified in “points”. According to the modern standard, 1pt = 1/72in. The “point size” of a font is the number of points per em.

The DPI (dots-per-inch) of a screen depends on the screen in question; 96 DPI is often considered the “standard”. For high-DPI displays the DPI may be specified directly or one may multiply 96 by a scale-factor.

Thus, for example, a 10pt font on a 96 pixels-per-inch display has 10 / 72 * 96 = 13.333… pixels-per-em. If we divide this number by units_per_em we then get a scaling factor: pixels-per-font-unit.

Note however that since PxScale values are relative to the text height, one further step is needed: multiply by Font::height_unscaled.

fn height_unscaled(&self) -> f32

Unscaled height ascent - descent.

Scaling can be done with as_scaled.

fn glyph_bounds(&self, glyph: &Glyph) -> Rectwhere Self: Sized,

Returns the layout bounds of this glyph. These are different to the outline px_bounds().

Horizontally: Glyph position +/- h_advance/h_side_bearing. Vertically: Glyph position +/- ascent/descent.

fn outline_glyph(&self, glyph: Glyph) -> Option<OutlinedGlyph>where Self: Sized,

Compute glyph outline ready for drawing.

fn as_scaled<S>(&self, scale: S) -> PxScaleFont<&Self>where S: Into<PxScale>, Self: Sized,

Construct a PxScaleFontRef by associating with the given pixel scale.

Example

let font = FontRef::try_from_slice(include_bytes!("../../dev/fonts/Exo2-Light.otf"))?;

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);

fn into_scaled<S>(self, scale: S) -> PxScaleFont<Self>where S: Into<PxScale>, Self: Sized,

Move into a PxScaleFont associated with the given pixel scale.

Implementations on Foreign Types

impl<F> Font for &Fwhere F: Font,

fn units_per_em(&self) -> Option<f32>

fn ascent_unscaled(&self) -> f32

fn descent_unscaled(&self) -> f32

fn line_gap_unscaled(&self) -> f32

fn glyph_id(&self, c: char) -> GlyphId

fn h_advance_unscaled(&self, id: GlyphId) -> f32

fn h_side_bearing_unscaled(&self, id: GlyphId) -> f32

fn v_advance_unscaled(&self, id: GlyphId) -> f32

fn v_side_bearing_unscaled(&self, id: GlyphId) -> f32

fn kern_unscaled(&self, first: GlyphId, second: GlyphId) -> f32

fn outline(&self, glyph: GlyphId) -> Option<Outline>

fn glyph_count(&self) -> usize

fn codepoint_ids(&self) -> CodepointIdIter<'_>

fn glyph_raster_image(&self, id: GlyphId, size: u16) -> Option<GlyphImage<'_>>

Implementors

impl Font for FontArc

impl Font for FontRef<'_>

impl Font for FontVec