Skip to content

global font

The font library provides the interface into the internals of the font system, and it also contains helper functions to load traditional TeX font metrics formats. Other font loading functionality is provided by the fontloader library that will be discussed in the next section.

😱 Types incomplete or incorrect? 🙏 Please contribute!

methods

font.read_tfm

function font.read_tfm(
  name: string,
  at_size: integer
) ->  TfmFont {
    name = string,
    area = string,
    used = boolean,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    designsize = integer,
    direction = FontDirection,
    parameters = FontParameters,
    size = integer,
    tounicode = integer,
}
@param at_size - If at_size is positive, it specifies an “at size” in scaled points. If at_size is negative, its absolute value represents a “scaled” setting relative to the designsize of the font.

Parse a font metrics file, at the size indicated by the number.

Load a TFM (TeX font metric) file.

Example:

font.read_tfm('cmr10', tex.sp('10pt'))

Reference:

font.read_vf

function font.read_vf(
  name,
  at_size: integer
) ->  VfFont {
    name = string,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    fonts = table,
    header = string,
    type = string,
}
@param at_size - If s is positive, it specifies an “at size” in scaled points. If at_size is negative, its absolute value represents a “scaled” setting relative to the designsize of the font.

Parse a virtual font metrics file, at the size indicated by the number.

Load a VF (virtual font) file.

Example:

font.read_vf('ptmr8t', tex.sp('8pt'))

The meaning of the number at_size and the format of the returned table are similar to the ones in the read_tfm function.

Reference:

font.setfont

function font.setfont(
  font_id: integer,
  f: Font {
    name = string,
    area = string,
    used = boolean,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    designsize = integer,
    direction = FontDirection,
    encodingbytes = integer,
    encodingname = string,
    fonts = table,
    psname = string,
    fullname = string,
    ...(+24)
}
)

Set an internal font id from a lua table.

Reference:

font.getfont

function font.getfont(font_id: integer) -> Font table

Fetch an internal font id as a Lua table.

Note that at the moment, each access to the font.fonts or call to font.getfont creates a Lua table for the whole font unless you cached it.

Reference:

font.getcopy

function font.getcopy(font_id: integer) -> Font table

Copy the internal data of a font.

Reference:

font.getparameters

function font.getparameters(font_id: integer) -> p table

Return a table of the parameters as known to TeX. These can be different from the ones in the cached table.

Reference:

font.frozen

function font.frozen(font_id: integer) ->  boolean?

Test for the status of a font.

Return true if the font is frozen and can no longer be altered.

The return value is one of true (unassignable), false (can be changed) or nil (not a valid font at all).

Reference:

font.define

function font.define(f: Font {
    name = string,
    area = string,
    used = boolean,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    designsize = integer,
    direction = FontDirection,
    encodingbytes = integer,
    encodingname = string,
    fonts = table,
    psname = string,
    fullname = string,
    ...(+24)
}) -> font_id integer

Define a font into font.fonts.

Reference:

font.define

function font.define(
  font_id: integer,
  f: Font {
    name = string,
    area = string,
    used = boolean,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    designsize = integer,
    direction = FontDirection,
    encodingbytes = integer,
    encodingname = string,
    fonts = table,
    psname = string,
    fullname = string,
    ...(+24)
}
) -> i integer

An alternative call is:

Where the first argument is a reserved font id (see below).

font.addcharacters

function font.addcharacters(
  font_id: integer,
  f: Font {
    name = string,
    area = string,
    used = boolean,
    characters = table<integer,FontCharacter>,
    checksum = integer,
    designsize = integer,
    direction = FontDirection,
    encodingbytes = integer,
    encodingname = string,
    fonts = table,
    psname = string,
    fullname = string,
    ...(+24)
}
)

Add characters to a font.

The table passed can have the fields characters which is a (sub)table like the one used in font.define(), and for virtual fonts a fonts table can be added. The characters defined in the characters table are added (when not yet present) or replace an existing entry. Keep in mind that replacing can have side effects because a character already can have been used. Instead of posing restrictions we expect the user to be careful. (The setfont helper is a more drastic replacer.)

Example:

local newcharacters = {}
for gid = 0, #glyphs do
  local glyph = glyphs[gid]
  if glyph.used then
    local character = characters[gid + gid_offset]
    newcharacters[gid + gid_offset] = character
    local unicode = nominals[gid]
    if unicode then
      newcharacters[unicode] = character
    end
    character.tounicode = glyph.tounicode or unicode or "FFFD"
    character.used = true
  end
end
font.addcharacters(font_id, { characters = newcharacters })

Reference:

font.nextid

function font.nextid() -> font_id integer

Return the next free font id number.

Return the font id number that would be returned by a font.define call if it was executed at this spot in the code flow.

This is useful for virtual fonts that need to reference themselves. If you pass true as argument, the id gets reserved and you can pass to font.define as first argument. This can be handy when you create complex virtual fonts.

Reference:

font.id

function font.id(csname: string) -> font_id integer

Return the font id of the font accessed by the csname given.

Return the font id associated with csname, or -1 if csname is not defined.

Reference:

font.max

function font.max() -> max_font_id integer

@return max_font_id - The largest used index in font.fonts.

😱 Types incomplete or incorrect? 🙏 Please contribute!

Return the highest used font id at this moment.

Get the largest used index in font.fonts.

Reference:

font.current

function font.current(font_id: integer)

Set the currently used / active font number.

Reference:

font.current

function font.current(font_id) -> font_id integer

Get the currently used / active font number.

Reference:

font.each

function font.each() ->  fun() -> (integer,Font)

Iterate over all the defined fonts.

This is an iterator over each of the defined TeX fonts. The first returned value is the index in font.fonts, the second the font itself, as a Lua table. The indices are listed incrementally, but they do not always form an array of consecutive numbers: in some cases there can be holes in the sequence.

Example:

local inspect = require('inspect')
for font_id, font in font.each() do
  print(font_id, inspect(font))
end

Reference:

font.setexpansion

function font.setexpansion(
  font_id: integer,
  stretch: integer,
  shrink: integer,
  step: integer
)

Because we store the actual state of expansion with each glyph and don't have special font instances, we can change some font related parameters before lines are constructed, like:

font.setexpansion(font.current(),100,100,20)

This is mostly meant for experiments (or an optimizing routing written in Lua) so there is no primitive.

Reference:

fields

font.fonts

font.fonts: table

The whole table of TeX fonts is accessible from Lua using a virtual array. Because this is a virtual array, you cannot call pairs on it

😱 Types incomplete or incorrect? 🙏 Please contribute!