Vivid.Font (vivid v1.0.0)

Copy Markdown View Source

Describes a font as a map of codepoints to glyphs, along with the metrics needed to lay them out.

A font is data, so obtain one, hold onto it, and pass it to line/3:

font = Vivid.Font.rowmans()
Vivid.Font.line(font, "hello world", 24)

rowmans/0 is currently the only font available - it reads the Hershey vector font of that name from this library's priv directory via Vivid.Hershey. Since parsing a font costs a file read, prefer holding onto the result over calling rowmans/0 for every line you render.

Glyphs themselves are opaque to this module: anything implementing Vivid.Font.Glyph can be laid out, which is how stroke fonts and outline fonts coexist without this module knowing the difference.

Summary

Types

t()

Functions

glyph(font, codepoint)

Returns the glyph for codepoint in font.

init(glyphs, units_per_em, vertical_offset)

Initialize a font from a map of codepoints to glyphs.

line(font, str, size \\ 32)

Convert a String containing one or more characters into a shape.

rowmans()

Returns the rowmans Hershey font.

Types

t()

@type t() :: %Vivid.Font{
  glyphs: %{required(char()) => Vivid.Font.Glyph.t()},
  units_per_em: number(),
  vertical_offset: number()
}

Functions

glyph(font, codepoint)

@spec glyph(t(), char()) :: Vivid.Font.Glyph.t()

Returns the glyph for codepoint in font.

Example

iex> Vivid.Font.rowmans()
...> |> Vivid.Font.glyph(?A)
...> |> Vivid.Font.Char.width()
18.0

init(glyphs, units_per_em, vertical_offset)

@spec init(%{required(char()) => Vivid.Font.Glyph.t()}, number(), number()) :: t()

Initialize a font from a map of codepoints to glyphs.

  • glyphs a map of codepoint to anything implementing Vivid.Font.Glyph.
  • units_per_em the size of this font's em square in the glyphs' own units, which is what makes a size in pixels mean the same thing across fonts.
  • vertical_offset how far above the origin to place the baseline.

Example

iex> Vivid.Font.init(%{}, 2048, 0)
%Vivid.Font{glyphs: %{}, units_per_em: 2048, vertical_offset: 0}

line(font, str, size \\ 32)

@spec line(t(), String.t(), number()) :: Vivid.Shape.t()

Convert a String containing one or more characters into a shape.

Can only handle characters defined in font, and raises a KeyError for any it doesn't contain. Carriage returns and line feeds are not supported.

The third argument is the size to render at, in pixels per em. Defaults to 32. Since it's measured against the font's em square rather than against the glyphs' own coordinates, the same size means the same thing whichever font it's given.

Example

iex> use Vivid
...> Font.line(Font.rowmans(), "hello world", 24)
...> |> to_string
"@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n" <>
"@ @@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@ @\n" <>
"@ @@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@ @\n" <>
"@ @@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@ @\n" <>
"@ @@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@ @\n" <>
"@ @@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@ @\n" <>
"@ @@     @@@@@@@@@    @@@@@@@ @@@@@ @@@@@@@     @@@@@@@@@@@@@@@@@@ @@@@@ @@@@@ @@@@@@@    @@@@@@@@ @@    @@@ @@@@@@@    @@ @\n" <>
"@ @ @@@@@ @@@@@@@ @@@@ @@@@@@ @@@@@ @@@@@@ @@@@@ @@@@@@@@@@@@@@@@@ @@@@@ @@@@@ @@@@@@ @@@@ @@@@@@@ @ @@@@@@@ @@@@@@ @@@@ @ @\n" <>
"@  @@@@@@ @@@@@@ @@@@@@ @@@@@ @@@@@ @@@@@@ @@@@@@ @@@@@@@@@@@@@@@@@ @@@ @ @@@ @@@@@@@ @@@@@ @@@@@@ @ @@@@@@@ @@@@@@ @@@@@  @\n" <>
"@ @@@@@@@ @@@@@ @@@@@@@@ @@@@ @@@@@ @@@@@ @@@@@@@ @@@@@@@@@@@@@@@@@ @@@ @ @@@ @@@@@@ @@@@@@@ @@@@@  @@@@@@@@ @@@@@ @@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@ @@@@@@@@ @@@@ @@@@@ @@@@@ @@@@@@@@ @@@@@@@@@@@@@@@@ @@@ @ @@@ @@@@@@ @@@@@@@@ @@@@  @@@@@@@@ @@@@@ @@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@          @@@@ @@@@@ @@@@ @@@@@@@@@ @@@@@@@@@@@@@@@@ @@@ @ @@@ @@@@@ @@@@@@@@@ @@@@ @@@@@@@@@ @@@@ @@@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@ @@@@@@@@@@@@@ @@@@@ @@@@ @@@@@@@@@ @@@@@@@@@@@@@@@@@ @ @@@ @ @@@@@@ @@@@@@@@@ @@@@ @@@@@@@@@ @@@@ @@@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@ @@@@@@@@@@@@@ @@@@@ @@@@ @@@@@@@@@ @@@@@@@@@@@@@@@@@ @ @@@ @ @@@@@@ @@@@@@@@@ @@@@ @@@@@@@@@ @@@@ @@@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@ @@@@@@@@@@@@@ @@@@@ @@@@@ @@@@@@@ @@@@@@@@@@@@@@@@@@ @ @@@ @ @@@@@@@ @@@@@@@ @@@@@ @@@@@@@@@ @@@@@ @@@@@@@ @\n" <>
"@ @@@@@@@ @@@@@  @@@@@@  @@@@ @@@@@ @@@@@ @@@@@@@ @@@@@@@@@@@@@@@@@@ @ @@@ @ @@@@@@@ @@@@@@  @@@@@ @@@@@@@@@ @@@@@ @@@@@@  @\n" <>
"@ @@@@@@@ @@@@@@@ @@@@ @@@@@@ @@@@@ @@@@@@  @@@  @@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@  @@@ @@@@@@@ @@@@@@@@@ @@@@@@  @@@ @ @\n" <>
"@ @@@@@@@ @@@@@@@@    @@@@@@@ @@@@@ @@@@@@@@   @@@@@@@@@@@@@@@@@@@@@@ @@@@@ @@@@@@@@@@@   @@@@@@@@ @@@@@@@@@ @@@@@@@@   @@ @\n" <>
"@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@\n"

rowmans()

@spec rowmans() :: t()

Returns the rowmans Hershey font.

Example

iex> Vivid.Font.rowmans()
...> |> Vivid.Font.glyph(?V)
...> |> Vivid.Font.Char.rendered_width()
16.0