Class Packing
Class that represents a truetype packing context.
N.B. These APIs are only lightly tested at the moment, so use at your own risk!
Tables
- Packing.PackRange
-
Representation of a packed range.
Fields:
- font_size As per Packing:PackFontRange. (Required)
- codepoints Either a single uint codepoint or an array of the same. In the second case these are the codepoints themselves; otherwise, this is the first point in a range. (Required)
- num_chars Number of characters in the range. (Ignored when codepoints is an array, required otherwise.)
Methods
- Packing:GetBitmap (how)
-
Getter.
Parameters:
- how This may be "as_bytes" to return the bitmap as Bytes.
Returns:
-
Bytes or string
Bitmap pixels with size
width * height, cf. NewPacking. As a string, this is a snapshot at the time of the call; otherwise, a proxy object that implements Bytes and reflects the current contents. - Packing:PackEnd ()
- Cleans up the packing context and frees all memory. (The garbage collector will also do this.)
- Packing:PackFontRange (bytes, font_size, codepoint, nchars[, index=1])
-
Given the font data, prepare bitmap layouts for nchars Unicode values, starting at codepoint.
Parameters:
- bytes Bytes or string Font data, typically the contents of a file.
- font_size number or string Target font height. As a number, this will be scaled according to FontInfo:ScaleForPixelHeight; strings, on the other hand, are assumed to come from PointSize and will be handled by FontInfo:ScaleForMappingEmToPixels.
- codepoint uint First Unicode character in range.
- nchars uint Number of characters.
- index uint Font index, ≥ 1. (default 1)
Returns:
-
CharArray or nil
On success, rendering data which may be retrieved by CharArray:GetPackedQuad; nil otherwise.
- Packing:PackFontRanges (bytes, ranges[, index=1])
-
Given the font data, prepare bitmap layouts for multiple ranges of characters.
This will usually create a better-packed bitmaps than multiple calls to Packing:PackFontRange. Note that you can call this multiple times without calling Packing:PackEnd.
Parameters:
- bytes Bytes or string Font data, typically the contents of a file.
- ranges {PackRange,...} One or more packed ranges.
- index uint Font index, ≥ 1. (default 1)
Returns:
-
{CharArray,...} or nil
On success, an array of CharArrays, cf. Packing:PackFontRange; nil otherwise.
- Packing:PackFontRangesGatherRects (font, ranges)
-
Calculates the dimensions for all the characters to be packed, taking into account font size and
oversampling, cf. Packing:PackFontRange and Packing:PackSetOversampling respectively.
Calling this, Packing:PackFontRangesPackRects, and Packing:PackFontRangesRenderIntoRects in sequence is roughly equivalent to calling Packing:PackFontRanges.
If you more control over the packing of multiple fonts, or if you want to pack custom data into a font texture, you can create a custom version of PackFontRanges using these functions, e.g. gather rects multiple times, concatenate the resulting arrays into one, pack that, then render repeatedly. This may result in a better packing than calling PackFontRanges multiple times (or it may not).
Parameters:
- font FontInfo Info for a specific font.
- ranges {PackRange,...} One or more packed ranges.
Returns:
-
RectArray or nil
On success, the characters' rects with proper dimensions and default
positions; nil otherwise.
- Packing:PackFontRangesPackRects (rects)
-
Assign packed locations to rectangles.
Parameters:
- rects RectArray On input, only the dimensions are considered. Afterward, valid positions will have been assigned to each successfully packed rect, cf. RectArray:WasPacked.
- Packing:PackFontRangesRenderIntoRects (font, ranges, rects)
-
Renders any successfully packed characters into the packing's bitmap.
Parameters:
- font FontInfo Info for a specific font.
- ranges {PackRange,...} One or more packed ranges.
- rects RectArray Packed locations and dimension information.
Returns:
-
CharArray or nil
On success, packed character rendering data; nil otherwise.
- Packing:PackSetOversampling (hoversampling, voversampling)
-
Oversampling a font increases the quality by allowing higher-quality subpixel
positioning, and is especially valuable at smaller text sizes.
This function sets the amount of oversampling for all following calls to Packing:PackFontRange, Packing:PackFontRanges, or Packing:PackFontRangesGatherRects for a given packing. The default (no oversampling) is achieved by
hoversampling == 1andvoversampling == 1. The total number of pixels required ishoversampling * voversamplinglarger than the default; for example, 2x2 oversampling requires 4x the storage of 1x1. For best results, render oversampled textures with bilinear filtering.The readme for stb's oversample tests has some good information about oversampled fonts.
To use with Packing:PackFontRangesGatherRects and friends, oversampling must be set before the sequence of calls, cf. the docs for the same.
Parameters:
- hoversampling uint Horizontal oversampling...
- voversampling uint ...and vertical.