Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-fonts

Source of release 0.7.1

0.7.1 / src / opentype / scaler.lucb

#==============================================================================================
#
#   scaler - a face's metrics and advances at a size, with Skia's FreeType backend's numbers
#
#   DESCRIPTION:
#       What Skia's FreeType scaler context (SkFontHost_FreeType.cpp) answers for a face at a
#       pixel size, reproduced float for float (browsers measure text with these numbers):
#
#       - SkScalerContext_FreeType::generateFontMetrics: the typographic metrics when OS/2's
#         USE_TYPO_METRICS bit is set, FreeType's ascender/descender/height otherwise, each
#         divided by units per em and multiplied by the text size in single precision; the
#         x-height from OS/2 or from the 'x' glyph's box;
#       - SkStrikeSpec::MakeCanonicalized: text larger than 256 px is measured at 64 px
#         unhinted and scaled back (SkFont::setupForAsPaths);
#       - SkScalerContextRec::computeMatrices: text of at most 1/4096 px (a zero font-size) is
#         measured at 1 px;
#       - glyph advances with Skia's default hinting (FT_LOAD_TARGET_NORMAL): the phantom
#         points rounded to whole pixels, or the linear advance when unhinted;
#       - the face's bounding box at a size (SkFontPriv::GetFontBounds).
#
#       Glyph outlines at a size are sfnt_face_glyph_path's (glyf.lucb).
#
#==============================================================================================

## A face's metrics at a size, in pixels with y growing downward (SkFontMetrics): ascent is
## negative, descent positive.
pub struct SfntMetrics:
    pub var top: f32
    pub var ascent: f32
    pub var descent: f32
    pub var bottom: f32
    pub var leading: f32
    pub var avg_char_width: f32
    pub var x_min: f32
    pub var x_max: f32
    pub var x_height: f32
    pub var cap_height: f32
    pub var underline_thickness: f32
    pub var underline_position: f32
    pub var strikeout_thickness: f32
    pub var strikeout_position: f32

## The largest text size Skia measures directly (SkStrikeSpec::ShouldDrawAsPath's memory limit).
let sk_max_size_for_glyph_cache: f32 = 256.0

## The size of SkFontPriv::kCanonicalTextSizeForPaths.
let sk_canonical_text_size_for_paths: f32 = 64.0

## SK_ScalarNearlyZero (SkScalar.h): 1 / 4096.
let sk_scalar_nearly_zero: f32 = 1.0 / 4096.0

## The vertical scale of SkScalerContextRec::computeMatrices (kFull, no device matrix) for text
## of `size` pixels: the size, or 1 when the total matrix is singular or not finite. "All
## underlying ports have issues with zero text size, so use the matrices to zero": the
## remaining matrix becomes zero, so glyphs and advances vanish, but the scaler context, and so
## generateFontMetrics, measures the face at size 1.
func sk_scaler_context_scale(size: f32) -> f32:
    if math32.abs(size) <= sk_scalar_nearly_zero or not math32.is_finite(size):
        return 1.0
    return math32.abs(size)

## The face's metrics at `size` pixels per em (SkFont::getMetrics).
pub func sfnt_face_metrics(face: const SfntFace*, size: f32) -> SfntMetrics:
    var metrics: SfntMetrics
    if size > sk_max_size_for_glyph_cache:
        # MakeCanonicalized: measured as a path font at the canonical size, then scaled.
        metrics = sk_scaler_font_metrics(face, sk_canonical_text_size_for_paths, false)
        let scale = size / sk_canonical_text_size_for_paths
        metrics.top *= scale
        metrics.ascent *= scale
        metrics.descent *= scale
        metrics.bottom *= scale
        metrics.leading *= scale
        metrics.avg_char_width *= scale
        metrics.x_min *= scale
        metrics.x_max *= scale
        metrics.x_height *= scale
        metrics.cap_height *= scale
        metrics.underline_thickness *= scale
        metrics.underline_position *= scale
        metrics.strikeout_thickness *= scale
        metrics.strikeout_position *= scale
        return metrics
    return sk_scaler_font_metrics(face, sk_scaler_context_scale(size), true)

## The top of a glyph's box in pixels (getCBoxForLetter: the control box of the outline loaded
## at the size, yMax in 26.6 over 64), or none when the face has no such glyph.
func sk_letter_box_top(face: const SfntFace*, letter: u32, size: f32) -> f32?:
    let glyph = sfnt_face_ft_glyph_for_code_point(face, letter)
    if glyph == 0:
        return none
    var outline = sfnt_face_load_outline(face, glyph, sfnt_face_ft_scale(face, size)) else return none
    defer outline.release()
    if outline.ys.length() == 0:
        return 0.0
    var y_max: i64 = *outline.ys.at(0)
    for y in outline.ys.view():
        if y > y_max:
            y_max = y
    return (f32)y_max / 64.0

## SkScalerContext_FreeType::generateFontMetrics at text size `size` (fScale.y()).
## FIXME: FreeType hints the letter boxes it measures when the OS/2 table has no x-height
## (`hinted`); the port measures the unhinted outline.
func sk_scaler_font_metrics(face: const SfntFace*, size: f32, hinted: bool) -> SfntMetrics:
    var metrics: SfntMetrics
    let upem = (f32)face.units_per_em

    # use the os/2 table as a source of reasonable defaults.
    var x_height: f32 = 0.0
    var avg_char_width: f32 = 0.0
    var cap_height: f32 = 0.0
    var strikeout_thickness: f32 = 0.0
    var strikeout_position: f32 = 0.0
    if let os2 = face.os2:
        x_height = (f32)os2.sx_height / upem * size
        avg_char_width = (f32)os2.x_avg_char_width / upem
        strikeout_thickness = (f32)os2.y_strikeout_size / upem
        strikeout_position = -(f32)os2.y_strikeout_position / upem
        if os2.version != 0xFFFF and os2.version >= 2:
            cap_height = (f32)os2.s_cap_height / upem * size

    # pull from format-specific metrics as needed
    var ascent: f32
    var descent: f32
    var leading: f32
    # FreeType will always use HHEA metrics if they're not zero. It completely ignores the
    # OS/2 fsSelection::UseTypoMetrics bit.
    var use_typo_metrics = false
    if let os2 = face.os2:
        use_typo_metrics = os2.version != 0xFFFF and (os2.fs_selection & (1 << 7)) != 0
    if use_typo_metrics:
        let os2 = face.os2 else trap("VERIFY_NOT_REACHED")
        ascent = -(f32)os2.s_typo_ascender / upem
        descent = -(f32)os2.s_typo_descender / upem
        leading = (f32)os2.s_typo_line_gap / upem
    else:
        ascent = -(f32)face.ascender / upem
        descent = -(f32)face.descender / upem
        leading = (f32)((i32)face.height + ((i32)face.descender - (i32)face.ascender)) / upem
    let x_min = (f32)face.x_min / upem
    let x_max = (f32)face.x_max / upem
    let y_min = -(f32)face.y_min / upem
    let y_max = -(f32)face.y_max / upem
    let underline_thickness = (f32)face.underline_thickness / upem
    let underline_position = -(f32)((i32)face.underline_position + (i32)face.underline_thickness // 2) / upem

    # we may be able to synthesize x_height and cap_height from outline
    if x_height == 0.0:
        if let top = sk_letter_box_top(face, (u32)'x', size):
            x_height = top
    if cap_height == 0.0:
        if let top = sk_letter_box_top(face, (u32)'H', size):
            cap_height = top

    # synthesize elements that were not provided by the os/2 table or format-specific metrics
    if x_height == 0.0:
        x_height = -ascent * size
    if avg_char_width == 0.0:
        avg_char_width = x_max - x_min
    if cap_height == 0.0:
        cap_height = -ascent * size

    # disallow negative linespacing
    if leading < 0.0:
        leading = 0.0

    metrics.top = y_max * size
    metrics.ascent = ascent * size
    metrics.descent = descent * size
    metrics.bottom = y_min * size
    metrics.leading = leading * size
    metrics.avg_char_width = avg_char_width * size
    metrics.x_min = x_min * size
    metrics.x_max = x_max * size
    metrics.x_height = x_height
    metrics.cap_height = cap_height
    metrics.underline_thickness = underline_thickness * size
    metrics.underline_position = underline_position * size
    metrics.strikeout_thickness = strikeout_thickness * size
    metrics.strikeout_position = strikeout_position * size
    return metrics

## The advance of `glyph` in pixels at `size` as Skia's glyph cache has it:
## SkScalerContext_FreeType::generateMetrics with hinting (the phantom points rounded to
## whole pixels, FT_LOAD_TARGET_NORMAL) at sizes up to 256 px (below 1 px, the advance at
## 1 px scaled down; none at a zero size), the linear advance of the unhinted canonical font
## scaled back above that.
pub func sfnt_face_hinted_advance(face: const SfntFace*, glyph: u32, size: f32) -> f32:
    let advance_units = (i64)sfnt_face_advance(face, glyph)
    if size > sk_max_size_for_glyph_cache:
        # linearHoriAdvance: FT_MulDiv(advance, x_scale, 64) in 16.16 at the size used.
        let linear = ft_mul_div(advance_units, sfnt_face_ft_scale(face, sk_canonical_text_size_for_paths), 64)
        let advance = (f32)linear / 65536.0
        return advance * (size / sk_canonical_text_size_for_paths)
    # SkScalerContext_FreeType's constructor: computeMatrices zeroes the matrices of text of
    # at most 1/4096 px, and with them every advance.
    if math32.abs(size) <= sk_scalar_nearly_zero or not math32.is_finite(size):
        return 0.0
    let context_size = sk_scaler_context_scale(size)
    let scale = sfnt_face_ft_scale(face, context_size)
    var pp1_units: i64 = 0
    if face.outline_format == SfntOutlineFormat.true_type:
        if let range = sfnt_glyf_range(face, glyph):
            let x_min: i64 = (i64)sfnt_i16(face.glyf, range.0 + 2) if range.1 > range.0 else 0
            pp1_units = x_min - (i64)sfnt_face_left_side_bearing(face, glyph)
    let pp1 = ft_pix_round(ft_mul_fix(pp1_units, scale))
    let pp2 = ft_pix_round(ft_mul_fix(pp1_units + advance_units, scale))
    var advance = pp2 - pp1
    # "FreeType currently does not allow requesting sizes less than 1, this allow for
    # scaling": below 1 px the face is at 1 px and fMatrix22 scales by size / ppem, a transform
    # FT_Load_Glyph applies to the advance (FT_Vector_Transform).
    if context_size < 1.0:
        let x_ppem = (f32)face.units_per_em * ((f32)scale * 1.52587890625e-5) / 64.0
        let xx = (i64)(context_size / x_ppem * 65536.0)  # SkScalarToFixed
        advance = ft_mul_fix(advance, xx)
    return (f32)advance * 0.015625

## The width of ASCII `text` at `size` (SkFont::measureText): the sum of the hinted glyph
## advances.
pub func sfnt_face_measure_ascii(face: const SfntFace*, size: f32, text: const u8[]) -> f32:
    var width: f32 = 0.0
    for byte in text:
        width += sfnt_face_hinted_advance(face, sfnt_face_ft_glyph_for_code_point(face, (u32)byte), size)
    return width

## The face's bounding box (head) at `size`, in y-down pixels: (left, top, right, bottom)
## (SkFontPriv::GetFontBounds).
pub func sfnt_face_bounds(face: const SfntFace*, size: f32) -> (f32, f32, f32, f32):
    let upem = (f32)face.units_per_em
    # SkTypeface::getBounds: the head box over units per em, y flipped.
    let left = (f32)face.x_min / upem
    let top = -(f32)face.y_max / upem
    let right = (f32)face.x_max / upem
    let bottom = -(f32)face.y_min / upem
    return (left * size, top * size, right * size, bottom * size)