Class FontInfo

Class that represents font info.

Many methods have both Unicode and glyph variants. The full signatures of the Unicode versions are shown; the glyph versions are elided but structurally identical to their Unicode counterparts. (Both in fact take uint arguments, cf. FontInfo:FindGlyphIndex.)

Methods

FontInfo:FindGlyphIndex (codepoint)
If you're going to perform multiple operations on the same character and you want a speed-up, call this function with the character you're going to process, then use glyph-based functions instead of the codepoint-based functions.

Parameters:

  • codepoint uint Unicode point.

Returns:

    uint Index of glyph in this font.
FontInfo:GetCodepointBitmap (xscale, yscale, codepoint, how)
Allocates a large-enough single-channel 8bpp bitmap and renders the specified character at the provided scale into it, with antialiasing. Bitmap values range from 0, for no coverage (transparent), to 255 when fully covered (opaque).

The bitmap is stored left-to-right, top-to-bottom.

If either xscale or yscale is 0, it will be assigned the value of the other. (Both being 0 is an error.)

Parameters:

  • xscale number How much to scale the character's width...
  • yscale number ...and height.
  • codepoint uint Unicode point.
  • how How to return the bitmap.

Returns:

  1. Bytes or string If how is "as_bytes", the internally allocated bitmap is given some Bytes machinery and returned directly, which should avoid some garbage; otherwise, a copy of its contents are returned as a string.
  2. uint Width of the bitmap...
  3. uint ...and height.
  4. int Offset in pixel space from the glyph origin to the top-left corner of the bitmap, x-coordinate...
  5. int ...and y-coordinate.

Or

    nil, indicating failure.

See also:

FontInfo:GetCodepointBitmapBox (codepoint, xscale, yscale)
Get the bounding box of the bitmap, centered around the glyph origin. Following the snippet below, the bitmap has width of ix1 - ix0 and height iy1 - iy0; the location to place the bitmap's top-left corner is (ix0, iy0). (N.B. the lower-right corner is actually just outside the bitmap.)

Note that the bitmap uses y-increases-down, but the shape uses y-increases-up, so this and FontInfo:GetCodepointBox are inverted.

This is a convenience wrapper for the following:

local ok, x0, y0, x1, y1 = font:GetCodepointBox(codepoint)

if ok then
  local ix0, iy0 = math.floor(x0 * xscale), math.floor(-y1 * yscale)
  local ix1, iy1 = math.ceil(x1 * xscale), math.ceil(-y0 * yscale)

  return ix0, iy0, ix1, iy1
else
  return 0, 0, 0, 0
end

Parameters:

  • codepoint uint Unicode point.
  • xscale number How much to scale the character's width...
  • yscale number ...and height.

Returns:

  1. uint Upper-left corner, x-coordinate...
  2. uint ...and y-coordinate.
  3. uint Lower-right corner, x-coordinate...
  4. uint ...and y-coordinate.

See also:

FontInfo:GetCodepointBitmapBoxSubpixel (codepoint, xscale, yscale, xshift, yshift)
Variant of FontInfo:GetCodepointBitmapBox that accepts a subpixel shift.

This is a convenience wrapper for the following:

local ok, x0, y0, x1, y1 = font:GetCodepointBox(codepoint)

if ok then
  local ix0, iy0 = math.floor(x0 * xscale + xshift), math.floor(-y1 * yscale + yshift)
  local ix1, iy1 = math.ceil(x1 * xscale + xshift), math.ceil(-y0 * yscale + yshift)

  return ix0, iy0, ix1, iy1
else
  return 0, 0, 0, 0
end

Parameters:

  • codepoint uint Unicode point.
  • xscale number How much to scale the character's width...
  • yscale number ...and height.
  • xshift number Subpixel shift of scaled x-coordinate...
  • yshift number ...and y-coordinate.

Returns:

  1. uint Upper-left corner, x-coordinate...
  2. uint ...and y-coordinate.
  3. uint Lower-right corner, x-coordinate...
  4. uint ...and y-coordinate.
FontInfo:GetCodepointBitmapSubpixel (xscale, yscale, xshift, yshift, codepoint[, opts])
Variant of FontInfo:GetCodepointBitmap that accepts a subpixel shift, cf. FontInfo:GetCodepointBitmapBoxSubpixel for details.

Parameters:

  • xscale number How much to scale the character's width...
  • yscale number ...and height.
  • xshift number Subpixel shift of scaled x-coordinate...
  • yshift number ...and y-coordinate.
  • codepoint uint Unicode point.
  • opts table As per FontInfo:GetCodepointBitmap. (optional)

Returns:

  1. Bytes or string As per FontInfo:GetCodepointBitmap.
  2. uint Width of the bitmap...
  3. uint ...and height.
  4. int Offset in pixel space from the glyph origin to the top-left corner of the bitmap, x-coordinate...
  5. int ...and y-coordinate.

Or

    nil, indicating failure.
FontInfo:GetCodepointBox (codepoint)
Gets the bounding box of the visible part of the glyph, in unscaled coordinates.

Parameters:

  • codepoint uint Unicode point.

Returns:

  1. true, indicating success.
  2. uint Upper-left corner, x-coordinate...
  3. uint ...and y-coordinate.
  4. uint Lower-right corner, x-coordinate...
  5. uint ...and y-coordinate.

Or

    false, meaning failure.
FontInfo:GetCodepointHMetrics ()
Get various horizontal metrics for a particular codepoint in the font.

Returns:

  1. uint Advance width, the offset from the current horizontal position to the next horizontal position, expressed in unscaled coordinates.
  2. int Left side bearing, the offset from the current horizontal position to the left edge of the character.
FontInfo:GetCodepointKernAdvance (char_index_1, char_index_2)
Find the kerning between two adjacent characters, an additional amount to add to the 'advance' value.

Parameters:

  • char_index_1 uint First Unicode point...
  • char_index_2 uint ...and second.

Returns:

    int Kerning.
FontInfo:GetCodepointShape (codepoint)
Get the series of contours that describe the character.

Parameters:

  • codepoint uint Unicode point.

Returns:

    Shape or nil On success, the character's shape; otherwise nil.
FontInfo:GetFontBoundingBox ()
Get the bounding box around all possible characters.

Returns:

  1. uint Upper-left corner, x-coordinate...
  2. uint ...and y-coordinate.
  3. uint Lower-right corner, x-coordinate...
  4. uint ...and y-coordinate.
FontInfo:GetFontVMetrics ()
Get various vertical metrics from the font.

You should advance the vertical position by ascent - descent + line_gap. These are expressed in unscaled coordinates, so you must multiply by the scale factor for a given size.

Returns:

  1. int Ascent, the coordinate above the baseline the font extends.
  2. int Descent, the coordinate below the baseline the font extends (i.e. it is typically negative).
  3. int Line gap, the spacing between one row's descent and the next row's ascent...
FontInfo:GetGlyphBitmap ()
Like FontInfo:GetCodepointBitmap, but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphBitmapBox ()
Like FontInfo:GetCodepointBitmapBox but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphBitmapBoxSubpixel ()
Like FontInfo:GetCodepointBitmapBoxSubpixel, but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphBitmapSubpixel ()
Like FontInfo:GetCodepointBitmapSubpixel, but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphBox ()
Like FontInfo:GetCodepointBox, but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphHMetrics ()
Like FontInfo:GetCodepointHMetrics, but takes a glyph index rather than a codepoint.
FontInfo:GetGlyphKernAdvance ()
Like FontInfo:GetCodepointKernAdvance, but takes glyph indices rather than codepoints.
FontInfo:GetGlyphShape ()
Like FontInfo:GetCodepointShape, but takes a glyph index rather than a codepoint.
FontInfo:IsGlyphEmpty (glyph_index)
Predicate.

Parameters:

Returns:

    boolean Is anything drawn for this glyph?
FontInfo:MakeCodepointBitmap (output, ow, oh, xscale, yscale, codepoint[, opts])
This is like FontInfo:GetCodepointBitmap, but you pass in storage for the bitmap in the form of output, with row spacing of stride bytes. The bitmap is clipped to the output region, if necessary. Call FontInfo:GetCodepointBitmapBox to get the width, height, and positioning info first; see also its details on scaling.

Parameters:

  • output MemoryBlob Blob that will receive the bitmap.
  • ow uint Output bitmap width...
  • oh uint ...and height.
  • xscale number How much to scale the character's width...
  • yscale number ...and height.
  • codepoint uint Unicode point.
  • opts table

    Make options, which include:

    • stride: Bytes per row, defaulting to 0 (a synonym for ow).
    • x: Horizontal offset into blob... (Default 0.)
    • y: ...and vertical offsset. (Ditto.)
    (optional)

Returns:

    boolean Was a blob provided and could the output region be placed inside it (resizing, if necessary and possible)?
FontInfo:MakeCodepointBitmapSubpixel (ow, oh, xscale, yscale, xshift, yshift, codepoint[, opts])
Variant of FontInfo:MakeCodepointBitmap that accepts a subpixel shift, cf. FontInfo:GetCodepointBitmapBoxSubpixel for details.

Parameters:

  • ow uint Output bitmap width...
  • oh uint ...and height.
  • xscale number How much to scale the character's width...
  • yscale number ...and height.
  • xshift number Subpixel shift of scaled x-coordinate...
  • yshift number ...and y-coordinate.
  • codepoint uint Unicode point.
  • opts table As per FontInfo:MakeCodepointBitmap. (optional)

Returns:

    Bytes or string
FontInfo:MakeGlyphBitmap ()
Like FontInfo:MakeCodepointBitmap, but takes a glyph index rather than a codepoint.
FontInfo:MakeGlyphBitmapSubpixel ()
Like FontInfo:MakeCodepointBitmapSubpixel, but takes a glyph index rather than a codepoint.
FontInfo:ScaleForMappingEmToPixels (pixels)
Computes a scale factor—from our actual font to an ideal one—according to the height of "M".

Parameters:

  • pixels number Desired pixel height.

Returns:

    number Scale factor, where pixels = scale * height("M").
FontInfo:ScaleForPixelHeight (pixels)
Compute a scale factor—from our actual font to an ideal one—according to the distance from the highest ascender to the lowest descender.

In other words, it's equivalent to calling FontInfo:GetFontVMetrics and computing scale = pixels / (ascent - descent), so if you prefer to measure height by the ascent only, use a similar calculation.

Parameters:

  • pixels number Desired pixel height.

Returns:

    number Scale factor, as described above.
generated by LDoc 1.4.6 Last updated 2018-09-03 18:10:34