DOCSEARCHbyAlgolia
Submit Docs

allsorts

repository·master·Indexed 21 days ago

https://github.com/yeslogic/allsorts

A high-performance font parser, shaping engine, and subsetter written in Rust. It supports OpenType, WOFF, and WOFF2 formats, providing capabilities for parsing (glyf, CFF, CFF2), shaping for a wide array of international scripts, and font subsetting and instancing for PDF embedding and variable fonts. Version 0.17.0.

Tokens
14.6K
Snippets
52
Records
69
Agent score
73%

What's inside allsorts

  1. Overview of Allsorts capabilities

    master

    Allsorts is a Rust-based library designed for font processing. It provides three primary capabilities:

    1. Parsing: Supports TrueType/OpenType (glyf, CFF, CFF2), WOFF, and WOFF2 file formats.
    2. Shaping: Converts Unicode codepoints into laid-out glyphs by applying font-specific kerning, ligatures, and substitutions. It supports a wide range of scripts including Arabic, Cyrillic, Greek, Hebrew, Indic scripts (Bengali, Devanagari, Gujarati, Gurmukhi, Kannada, Malayalam, Oriya, Sinhala, Tamil, Telugu), Khmer, Lao, Latin, Myanmar, Syriac, and Thai.
    3. Subsetting & Instancing: Can subset fonts into formats suitable for PDF embedding and can instance variable fonts into non-variable fonts.

  3. Overview of Allsorts

    master

    Allsorts is a font parser, shaping engine, and subsetter written in Rust. It supports OpenType, WOFF, and WOFF2 formats.

    Key Capabilities:

    • Parsing: Handles TrueType (ttf), OpenType (otf), WOFF, and WOFF2.
    • Shaping: Supports a wide range of scripts including Arabic, Cyrillic, Greek, Hebrew, Indic scripts (Bengali, Devanagari, etc.), Khmer, Lao, Latin, Mongolian, Syriac, Thai, Tibetan, and more.
    • Subsetting: Can subset TrueType, OpenType, WOFF, and WOFF2 files into OpenType.

    Limitations:

    • Does not support Unicode normalization.
    • Does not perform font lookup/matching (use font-kit for this purpose).
    • Documentation is currently incomplete.

  4. Understand the STAT Style Attributes Table

    master

    The STAT table describes design attributes that distinguish font-style variants within a font family. It is primarily used for variable fonts to associate design axes and specific axis values with human-readable names (from the name table). This allows applications to present font options (like 'Thin', 'Bold', or 'Condensed') in user interfaces.

    Key components include:

    • Design Axes: The axes of variation (e.g., weight, width).
    • Axis Value Tables: Mappings between specific axis values (or ranges) and display names.

    For more details, refer to the Microsoft OpenType specification for STAT.

  5. Understand coordinate tuples in variable fonts

    master

    Variable fonts use two distinct types of coordinate tuples to describe positions in the variation space:

    1. ReadTuple: Uses F2Dot14 values to represent normalized coordinates. These are used for internal calculations and determining applicability of variation data.
    2. UserTuple: Uses Fixed values to represent user scale coordinates. These are the coordinates typically used by end-users or higher-level APIs to specify a font instance.

    The number of elements in a tuple must match the axis_count specified in the FvarTable.

    // Example of iterating over a UserTuple's axis values
for axis_value in user_tuple.iter() {
    // axis_value is of type Fixed
}

  6. Access bitmap metrics via the Metrics enum

    master

    The Metrics enum determines how the layout and positioning of a bitmap glyph are calculated. It supports two modes:

    1. Embedded(EmbeddedMetrics): Metrics are stored directly alongside the bitmap data. This includes ppem_x, ppem_y, and optional horizontal (hori()) or vertical (vert()) BitmapMetrics.
    2. HmtxVmtx(OriginOffset): Metrics are retrieved from the font's hmtx and vmtx tables. In this case, only the OriginOffset (the x/y offset from the glyph origin in font units) is provided via the BitmapGlyph.

    BitmapMetrics

    When using EmbeddedMetrics, you can access BitmapMetrics which provides:

    • origin_offset_x / origin_offset_y: Pixel distance from the origin to the edge of the bitmap.
    • advance: The horizontal advance width in pixels.
    • ascender / descender: Spacing relative to the baseline in pixels.
    pub enum Metrics {
    Embedded(EmbeddedMetrics),
    HmtxVmtx(OriginOffset),
}

// Accessing embedded metrics
if let Metrics::Embedded(ref embedded) = glyph.metrics {
    if let Some(h_metrics) = embedded.hori() {
        let advance = h_metrics.advance;
    }
}

  7. How `CmapTarget` affects the output font

    master

    The CmapTarget determines how character-to-glyph mappings are preserved in the subsetted font:

    • CmapTarget::Unicode: Ensures the subset font contains a Unicode BMP cmap subtable.
    • CmapTarget::Unrestricted: Allows the subsetting process to select the most appropriate cmap (e.g., Mac Roman if the selected glyphs fall within that set).
    • CmapTarget::Unicode (with SubsetProfile::Minimal): Often used when you want to ensure specific character mappings are maintained while keeping the font footprint small.

  8. Select a `CmapTarget` for subsetting

    master

    The CmapTarget enum determines the format of the cmap table in the subsetted font. This is particularly important for web compatibility.

    Options:

    • CmapTarget::Unrestricted (Default): Uses the smallest suitable cmap format.
    • CmapTarget::MacRoman: Uses a Mac Roman cmap. Characters outside the Mac Roman set will be omitted.
    • CmapTarget::Unicode: Uses a Unicode cmap format. Use this when targeting web browsers, as they may reject fonts that only contain a Mac Roman cmap.
    #[derive(Debug, Copy, Clone, Eq, PartialEq, Default)]
pub enum CmapTarget {
    #[default]
    Unrestricted,
    MacRoman,
    Unicode,
}

  9. Understand CBLC and CBDT table structures

    master

    The project implements parsing for OpenType bitmap tables:

    CBLC (Color Bitmap Location Table)

    Contains metadata about available 'strikes' (sets of bitmaps).

    • major_version: 2 for EBLC, 3 for CBLC.
    • bitmap_sizes: A list of BitmapSize objects, each describing a specific size/bit-depth combination.
    • BitmapSize includes BitmapInfo (line metrics, ppem, bit depth) and IndexSubTables that map glyph IDs to data locations.

    CBDT (Color Bitmap Data Table)

    Contains the actual raw bitmap data.

    • major_version: 2 for EBDT, 3 for CBDT.
    • data: The raw binary payload containing the image data (bitmaps, PNGs, or component data).

  10. Handle different bitmap data formats with the Bitmap enum

    master

    The Bitmap enum distinguishes between raw pixel data and data encapsulated in standard image containers.

    • Embedded(EmbeddedBitmap): Used for raw pixel data. Requires specifying width, height, and a BitDepth.
    • Encapsulated(EncapsulatedBitmap): Used when the bitmap is stored in a container format like PNG or JPEG. Requires an EncapsulatedFormat.

    BitDepth

    Defines the bit depth of raw EmbeddedBitmap data:

    • One: 1-bit (black and white)
    • Two: 2-bits (grey)
    • Four: 4-bits (grey)
    • Eight: 8-bits (grey)
    • ThirtyTwo: 32-bits (RGBA)

    EncapsulatedFormat

    Supported container formats for EncapsulatedBitmap:

    • Jpeg
    • Png
    • Tiff
    • Svg
    • Other(u32): A non-standard OpenType format identifier.
    pub enum Bitmap {
    Embedded(EmbeddedBitmap),
    Encapsulated(EncapsulatedBitmap),
}

pub enum BitDepth {
    One = 1,
    Two = 2,
    Four = 4,
    Eight = 8,
    ThirtyTwo = 32,
}

pub enum EncapsulatedFormat {
    Jpeg,
    Png,
    Tiff,
    Svg,
    Other(u32),
}

  11. Configure font subsetting with `SubsetProfile`

    master

    The SubsetProfile enum controls which tables are included in the resulting subset font. You can use predefined profiles or define a custom list of tables.

    Predefined Profiles:

    • SubsetProfile::Pdf: A minimal set of tables suitable for PDF embedding (includes cmap, head, cvt, fpgm, hhea, hmtx, maxp, name, post, prep).
    • SubsetProfile::Minimal: The minimum tables required for a valid OpenType font (includes cmap, head, hhea, hmtx, maxp, name, os/2, post).
    • SubsetProfile::Custom(Vec<u32>): A custom list of table tags.

    Parsing Custom Profiles: You can create a Custom profile from a string using SubsetProfile::parse_custom. The string can use comma or whitespace separation (e.g., "gsub,vmtx,prep"). Case is ignored. Note that Minimal profile tables are automatically included in a custom profile.

    Supported Table Tags for Custom Profiles:

    • cmap, head, hhea, hmtx, maxp, name, os/2 (or os2, os_2), post, gpos, gsub, vhea, vmtx, gdef, cvt, fpgm, prep.
    /// Parses a custom subset profile from a string
///
/// The table names may be separated by commas or whitespace, such as `gsub,vmtx,prep`.
/// Case is ignored. Tables from the Minimal profile are included automatically.
pub fn parse_custom(s: String) -> Result<Self, ParseError>

  12. How BitmapGlyph is constructed from CBDT data

    master

    A BitmapGlyph is created by combining BitmapInfo (from the CBDT table), the raw GlyphBitmapData, and a bitmap_id.

    During construction, the library performs several transformations:

    • Bit-alignment unpacking: For formats like 2, 5, and 7, bit-aligned data is unpacked into bytes using unpack_bit_aligned_data.
    • Color space conversion: For 32-bit data, the library converts BGRA to RGBA using bgra_to_rgba.
    • Metrics calculation: Metrics (origin offsets, advance, etc.) are calculated based on whether the table uses horizontal or vertical metrics and whether the metrics are 'small' or 'big'.
    • Encapsulation: Formats 17, 18, and 19 are treated as EncapsulatedBitmap (specifically PNG).