Trait ab_glyph::Font

source · 
pub trait Font {

Show 23 methods    // 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_image2(
        &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_raster_image(
        &self,
        id: GlyphId,
        pixel_size: u16,
    ) -> Option<GlyphImage<'_>> { ... }
    fn glyph_svg_image(&self, id: GlyphId) -> Option<GlyphSvg<'_>> { ... }
    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: Into<PxScale>>(&self, scale: S) -> PxScaleFont<&Self>
       where Self: Sized { ... }
    fn into_scaled<S: Into<PxScale>>(self, scale: S) -> PxScaleFont<Self>
       where Self: Sized { ... }
    fn font_data(&self) -> &[u8] ⓘ { ... }

}
Expand description

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.

§Glyph layout concepts

Fonts provide several properties to inform layout of glyphs.

         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
                  |  .:x++++==              |
                  | .#+                     |
                  | :@            =++=++x=: |
           ascent | +#       x:  +x     x+  |
                  | =#       #:  :#:---:#:  | height
                  | -@-      #:  .#--:--    |
                  |  =#:-.-==#:   #x+===:.  |
baseline ____________ .-::-. ..  #:    .:@. |
                  |              #+--..-=#. |
          descent |               -::=::-   |
         ____________________________________
                | |             |           | line_gap
                | |  h_advance  |           ‾
                 ^                      
           h_side_bearing

Required Methods§

source

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.

source

fn ascent_unscaled(&self) -> f32

Unscaled glyph ascent. See glyph layout concepts.

Scaling can be done with as_scaled.

source

fn descent_unscaled(&self) -> f32

Unscaled glyph descent. See glyph layout concepts.

Scaling can be done with as_scaled.

source

fn line_gap_unscaled(&self) -> f32

Unscaled line gap. See glyph layout concepts.

Scaling can be done with as_scaled.

source

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

Lookup a GlyphId matching a given char.

Scaling can be done with as_scaled.

source

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

Unscaled horizontal advance for a given glyph id. See glyph layout concepts.

Returns 0.0 if the font does not define this value.

Scaling can be done with as_scaled.

source

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

Unscaled horizontal side bearing for a given glyph id. See glyph layout concepts.

Returns 0.0 if the font does not define this value.

Scaling can be done with as_scaled.

source

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

Unscaled vertical advance for a given glyph id.

Returns 0.0 if the font does not define this value.

Scaling can be done with as_scaled.

source

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

Unscaled vertical side bearing for a given glyph id.

Returns 0.0 if the font does not define this value.

Scaling can be done with as_scaled.

source

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.

source

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

Compute unscaled glyph outline curves & bounding box.

source

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

source

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(&'!'));
source

fn glyph_raster_image2( &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§

source

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.

source

fn height_unscaled(&self) -> f32

Unscaled height ascent - descent. See glyph layout concepts.

Scaling can be done with as_scaled.

source

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

👎Deprecated since 0.2.22: Deprecated in favor of glyph_raster_image2

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.

source

fn glyph_svg_image(&self, id: GlyphId) -> Option<GlyphSvg<'_>>

Returns raw SVG data of a range of glyphs which includes this one.

Some fonts define their images as SVG rather than a raster format. SVG data here is raw and should be rendered and/or decompressed by the caller, and scaled appropriately. The SVG file might include a series of glyphs as nodes.

source

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

Returns the layout bounds of this glyph.

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

These are not the same as OutlinedGlyph::px_bounds. If you are drawing pixels you should use px_bounds and not this method as outlines are not bound by layout values.

source

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

Compute glyph outline ready for drawing.

source

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

Construct a PxScaleFont 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);
source

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

Move into a PxScaleFont associated with the given pixel scale.

source

fn font_data(&self) -> &[u8] ⓘ

Extracts a slice containing the data passed into e.g. FontArc::try_from_slice.

§Example
let font = FontArc::try_from_slice(owned_font_data)?;
assert_eq!(font.font_data(), owned_font_data);

Implementations on Foreign Types§

source§

impl<F: Font> Font for &F

source§

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

source§

fn ascent_unscaled(&self) -> f32

source§

fn descent_unscaled(&self) -> f32

source§

fn line_gap_unscaled(&self) -> f32

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

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

source§

fn glyph_count(&self) -> usize

source§

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

source§

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

source§

fn glyph_svg_image(&self, id: GlyphId) -> Option<GlyphSvg<'_>>

source§

fn font_data(&self) -> &[u8] ⓘ

Implementors§