Font rasterizer for Heaps based on Msdfgen. Primary target is automation of font rasterization with Signed Distance Field method.
So far tool is built only with Hashlink VM and Windows, but with appropriate config should also work on Mac/Linux, as well as HXCPP/Eval/HLC.
Command-line interface is currently limited to input config file and logger switches.
Note that on Windows, HL should see the msdfgen.dll
and ammer_msdfgen.hdll
, so it should be either current working directory or in PATH.
Warning: Some image viewers do not follow PNG specification properly and show some rasterized images as pure white.
This is an issue with particular decoder and file itself is correct. Known affected viewers: XNView, FastStone Image Viewer.
Run tool with: hl fontgen.hl <input file> [switches]
Input file should contain a JSON object or array of objects describing font rasterization parameters.
{
"input": String,
"inputs": Array<String>,
"output": String,
"mode": SDFMode,
"dfSize": Int,
"charset": Array<CharsetConf>,
"options": Array<ProcessorOption>,
"fontSize": Int,
"padding": { "top": Int, "bottom": Int, "left": Int, "right": Int },
"spacing": { "x": Int, "y": Int },
"packer": {
"size": Int,
"width": Int,
"height": Int,
"pot": Bool,
"exact": Bool,
"sort": String,
"algorithm": String,
"heuristic": String,
"useWasteMap": String
}
}
-
input
- path to TTF file relative to JSON file. Optional ifinputs
is present. -
inputs
- An array of TTF files relative to JSON file. Can be used as fallback fonts in order of appearance. Optional ifinput
is present. -
output
- Path to output .fnt file relative to JSON file. -
mode
- Describes mode in which glyphs are going to be generated. Possible values are:msdf
,sdf
,psdf
andraster
. MSDF provides best accuracy by utilizing RGB channels, all others produce grayscale image. -
dfSize
- Distance field range in pixels. Can be omitted forraster
mode. -
charset
- An array describing which characters should be rasterized in next priority:- Try to find unicode block charset (or alias) described in
Charset.hx
- If string points to a file, try to interpret it's contents.
- If file is a valid XML file, rasterizer will use characters present in all nodes that contain text. (Attributes and comments are ignored)
- Use contents of a file as a list of characters to rasterize.
- Use string as a list of characters to rasterize.
Additionally, array nesting is supported.
- Try to find unicode block charset (or alias) described in
-
fontSize
- desired font size in pixels. -
padding
- optional and defaults to0
. Describes extra padding for glyphs on the texture in pixels. -
spacing
- optional and defaults to1
. Describes spacing between glyphs on the texture in pixels. -
options
- optional list of extra configuration flags. See below.
Optional packer configuration allows to fine-tune atlas creation.
size
- Shortcut to set bothwidth
andheight
with same value. Default max atlas size is 4096x4096width
- Maximum output atlas width in pixels. Note that it does not ensure atlas would be of specified size.height
- Maximum output atlas height in pixels.pot
- Output image will be power-of-two in dimensions. Note that this operation can override maximum size (for example 122 max size can output 128px image), and packing of content happens within boundaries of define sizes, not power-of-two boundaries. Default: falseexact
- Ensures that output image is always of specified size. Default: falsesort
- Sets sorting function for glyphs prior packing. Prefixing name with-
would reverse sort results.
Available values:width
,height
,area
,perimeter
andchar
. Defaults to-height
.algorithm
- Allows to select packing algorithm. Available values presented below. Defaults tomax-rect
guillotine
- Uses Guillotine algorithm. Currently not configurable and usesBestLongSideFit
andMaximizeArea
heuristics.naive-shelf
- Uses naive Shelf algorithm.shelf
- Uses Shelf algorithm. Default Heuristic isBestArea
. Allows usage of waste map.simple-max-rect
- Uses simplified Max Rects algorithm.skyline
- Uses Skyline algorithm. Default Heuristic isMinWasteFit
.max-rect
- Uses Max Rects algorithm. Default Heuristic isBestLongSideFit
.
heuristic
- Specifies exact heuristic to use for some algorithms. Case-sensitive.shelf
- Dictates which shelf to choose:Next
- Always add the new rectangle to the last open shelfFirst
- Test each rectangle against each shelf in turn and pack it to the first where it fitsBestArea
- Choose the shelf with smallest remaining shelf areaWorstArea
- Choose the shelf with the largest remaining shelf areaBestHeight
- Choose the smallest shelf (height-wise) where the rectangle fitsBestWidth
- Choose the shelf that has the least remaining horizontal shelf space available after packingWorstWidth
- Choose the shelf that will have most remainining horizontal shelf space available after packing
skyline
- Dictates prefered insertion location:BottomLeft
MinWasteFit
max-rect
- Dictates which rects is preferred when inserting:BestShortSideFit
BestLongSideFit
BestAreaFit
BottomLeftRule
ContactPointRule
useWasteMap
- Enables or disables usage of waste maps for some algorithms.
See test/config.json
for example config.
-info
- enables logging of processing progress.-nowarnings
- disables logging of processing warnings.-timings
- enables logging of processing timings for each step.-printmissing
- enables printing of all characters that were not present in ttf files but were required by charsets.-silent
- suppresses all logging.-verbose
- enables all logging.-help
- Prints help file and exits.
All processor options can be used as switches to enable them on all configurations. For example -allownonprint
allownonprint
- Enables rasterization of non-printing characters from range U+00 to U+1F plus U+7F (DEL). Disabled by default as to not produce warning about missing glyphs.r8raster
- Forces greyscale rasterization without usage of alpha when usingraster
mode.
Tool adds extra line at the end of .fnt
file describing used SDF method that would allow decoder to determine parameters that are required to render the font.
SDF descriptor presents itself as:
sdf mode=<mode> size=<dfSize>
It is put at the end of file, because some parsers depend on ordering of lines and may break if inserted between info
and chars
blocks.
TODO: More detailed
- Haxe Libraries:
- ammer
- bin-packing (Haxelib version)
- Use MSVC in x86 mode, because ammer/hl don't like x64.
- Compile msdfgen in
native/msdfgen
Windows note: when usingcmake
it may fail at findingfreetype
lib. It's includes and .lib files are located innative/msdfgen/freetype/
directory. - Compile ammer library in
native
Mac/Linux note: Makefile is not valid, as it should also point at compiledmsdfgen.so/dylib
andfreetype.so/dylib
. Feel free to PR fixes, as I'm not using those OS ;) - Run
build-hl.hxml
to compile hdll and the tool.
Windows note: Make sure you are running in msvc envrionment, sicne ammer needs it to compile .hdll file.
Ammer note: You probably will need to point at hashlink includes and lib files with-D ammer.hl.hlInclude=<path-to-hashlink>/include -D ammer.hl.hlLibrary=<path-to-hashlink>
, see ammer lib for more details. - Put
msdfgen.dll
fromnative
andammer_msdfgen.hdll
fromnative/hl
nearbin/fontgen.hl
- You're good to go.
- Source code is licensed under MIT
ammer
,bin-packing
andmsdfgen
are under MIT- Sample font files are licensed under SIL Open Font License, see LICENSE folder for their respective license files.
- Msdfgen dependencies
FreeType
- GPL2lodepng
- Zlibtinyxml
- Zlib
Welcome to licensing hell.