NativeElixirPdfUtilities.HtmlToPdf.Font (native_elixir_pdf_utilities v1.1.0)
View SourceFont loading, fallback resolution, text measurement, and PDF text encoding.
The renderer loads explicitly configured fonts, discovers installed fonts on demand, and keeps the bundled DejaVu Sans faces as the final fallback.
Summary
Types
A document-scoped mapping from Unicode or selected glyph pairs to PDF CIDs and glyphs.
Functions
Returns selected-font CSS glyph advances for validated text, sharing shaping, caches and work budgets.
Measures a validated selected font's CSS linear advances with fixed FreeType precision.
Encodes original text for an embedded Type0 font content stream.
Applies the encoding's available ligatures unless letter spacing is nonzero.
Older three-map encodings without :latin_ligatures retain their original
shaping based on available Unicode ligature mappings. Explicit metadata,
including an empty map, takes precedence.
Returns configured and bundled fallback faces in family declaration order, ordering each family's faces by the closest weight and style.
Reads glyph ink bounds from the selected TrueType font in design units.
Loads validated embedded byte faces without bundled font loading or system discovery.
Loads only explicit caller TrueType configurations, without bundled fonts or system discovery.
Loads explicit TTF font options into a registry.
Reads the selected font's OpenType MATH constants, glyph corrections,
height-dependent kerning, stretch variants, and assemblies in design units.
The :substitutions map contains the default math language's ssty, flac,
and dtls features. Each feature retains ordered lookup maps from glyph IDs
to alternate glyph lists. :substitution_kinds retains each lookup's single
or alternate kind, so a single substitution is not mistaken for a one-item
alternate set. Scaling and positioning are separate layout work.
Builds a document-scoped CID encoding for text shown with an embedded font.
Entries may be strings or {text, letter_spacing} pairs for spaced glyph runs.
Returns the PDF resource key for a selected font face.
Resolves a CSS font-family value or fallback list to a supported font face.
Shapes common Latin ligatures authorized by the selected font's Latin GSUB liga feature when letter spacing is zero.
Returns whether a font face can safely encode every codepoint in text.
Measures glyph advances in PDF points for the selected font and size. Nonzero letter spacing disables optional ligatures; callers add spacing separately. Standalone work-limit failures return the shared diagnostic; successful calls return a number.
Builds CID-to-Unicode mappings for all text shown with an embedded font.
Types
@type embedded_font() :: %{ type: :embedded, family: String.t(), weight: number(), style: font_style(), id: String.t(), pdf_name: String.t(), data: binary(), units_per_em: pos_integer(), widths: [non_neg_integer()], default_width: non_neg_integer(), cmap: %{optional(non_neg_integer()) => non_neg_integer()}, kerning: %{optional({non_neg_integer(), non_neg_integer()}) => integer()}, ascent: integer(), descent: integer(), line_gap: integer(), bbox: {integer(), integer(), integer(), integer()}, embedding_flags: non_neg_integer(), variable_font?: boolean(), source: :configured | :bundled | :system }
@type font_face() :: built_in_font() | embedded_font()
@type font_style() :: :normal | :italic
@type pdf_encoding() :: %{ :codepoint_to_cid => %{ optional(non_neg_integer() | {non_neg_integer(), non_neg_integer()}) => pos_integer() }, :cid_to_gid => %{optional(pos_integer()) => non_neg_integer()}, :cid_to_unicode => %{ optional(pos_integer()) => non_neg_integer() | String.t() }, optional(:latin_ligatures) => %{optional(String.t()) => non_neg_integer()} }
A document-scoped mapping from Unicode or selected glyph pairs to PDF CIDs and glyphs.
@type registry() :: %{ :embedded => [embedded_font()], :fallback => [embedded_font()], :system_font_discovery => boolean(), optional(:scoped) => %{ optional(reference()) => %{ embedded: [embedded_font()], fallback: [embedded_font()] } }, optional(:active_scope) => reference() | nil }
Functions
@spec css_glyph_advances(String.t(), embedded_font(), number(), number()) :: [{non_neg_integer(), non_neg_integer(), number()}] | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}
Returns selected-font CSS glyph advances for validated text, sharing shaping, caches and work budgets.
@spec css_text_width(String.t(), font_face(), number(), number()) :: number() | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}
Measures a validated selected font's CSS linear advances with fixed FreeType precision.
@spec encode_embedded_text(String.t(), pdf_encoding() | embedded_font(), number()) :: String.t()
Encodes original text for an embedded Type0 font content stream.
Applies the encoding's available ligatures unless letter spacing is nonzero.
Older three-map encodings without :latin_ligatures retain their original
shaping based on available Unicode ligature mappings. Explicit metadata,
including an empty map, takes precedence.
@spec fallback_faces(registry(), number(), font_style()) :: [embedded_font()]
Returns configured and bundled fallback faces in family declaration order, ordering each family's faces by the closest weight and style.
Reads glyph ink bounds from the selected TrueType font in design units.
Tuple positions are glyph IDs and contain {xmin, ymin, xmax, ymax}. Empty
outlines have zero bounds. Parsing is lazy and reuses identical source bytes
within the font budget; decoded geometry consumes max_font_math_work.
@spec load_byte_faces(term()) :: {:ok, [embedded_font()]} | {:error, {atom(), map()}}
Loads validated embedded byte faces without bundled font loading or system discovery.
@spec load_configured_faces(term()) :: {:ok, [embedded_font()]} | {:error, {atom(), map()}}
Loads only explicit caller TrueType configurations, without bundled fonts or system discovery.
@spec load_registry(keyword()) :: {:ok, registry()} | :error | {:error, {:invalid_document | :resource_limit_exceeded, map()}}
Loads explicit TTF font options into a registry.
Accepted font entries are maps, keyword lists, or {family, path} tuples. Map
and keyword entries must include :family and one or more :path or :data
candidates; :weight and :style are optional.
Reads the selected font's OpenType MATH constants, glyph corrections,
height-dependent kerning, stretch variants, and assemblies in design units.
The :substitutions map contains the default math language's ssty, flac,
and dtls features. Each feature retains ordered lookup maps from glyph IDs
to alternate glyph lists. :substitution_kinds retains each lookup's single
or alternate kind, so a single substitution is not mistaken for a one-item
alternate set. Scaling and positioning are separate layout work.
Parsing is lazy and reused within the font-loading budget scope. Missing or malformed metrics return a diagnostic; another font's metrics are never used.
@spec pdf_encoding([String.t() | {String.t(), number()}], embedded_font()) :: pdf_encoding()
Builds a document-scoped CID encoding for text shown with an embedded font.
Entries may be strings or {text, letter_spacing} pairs for spaced glyph runs.
Returns the PDF resource key for a selected font face.
@spec resolve(String.t() | [String.t()], number(), font_style(), registry()) :: {:ok, [String.t()], font_face()} | :error | {:error, {:resource_limit_exceeded, map()}}
Resolves a CSS font-family value or fallback list to a supported font face.
Shapes common Latin ligatures authorized by the selected font's Latin GSUB liga feature when letter spacing is zero.
Returns whether a font face can safely encode every codepoint in text.
Built-in PDF fonts are limited to printable ASCII. Embedded fonts are checked against their Unicode character map.
@spec text_width(String.t(), map(), number(), number()) :: number() | {:error, {atom(), NativeElixirPdfUtilities.Diagnostics.diagnostic()}}
Measures glyph advances in PDF points for the selected font and size. Nonzero letter spacing disables optional ligatures; callers add spacing separately. Standalone work-limit failures return the shared diagnostic; successful calls return a number.
@spec unicode_mappings([String.t()], embedded_font()) :: %{ optional(non_neg_integer()) => non_neg_integer() }
Builds CID-to-Unicode mappings for all text shown with an embedded font.