vladimirgamalyan / fontbm

BMFont compatible, cross-platform (Linux/macOS/Windows) command line bitmap font generator (FreeType2 based).

fontbm

BMFont compatible, cross-platform (Linux/macOS/Windows) command line bitmap font generator (FreeType2 based render).

Status

Linux	macOS	Windows

Usage

Download compiled version (fontbm.zip for Windows, fontbm for Linux) from Releases. Run:

fontbm --font-file FreeSans.ttf --output myfont

It will produce myfont.fnt (file format) and myfont_0.png (how to render text).

Available options (bold options are required):

option	default	comment
--font-file		path to ttf file, required
--output		output files name without extension, required
--font-size	32	font size (it matches to BMFont size, when "Match char height" option in Font Settings dialog is ticked)
--chars	32-126	required characters, for example 32-64,92,120-126 (without spaces), default value is 32-126 if 'chars-file' option is not defined
--texture-size	32x32,64x32,64x64,128x64, 128x128,256x128,256x256, 512x256,512x512,1024x512, 1024x1024,2048x1024,2048x2048	comma separated list of allowed texture sizes (without spaces), the first suitable size will be used
--texture-crop-width		crop unused parts of output textures (width)
--texture-crop-height		crop unused parts of output textures (height)
--color	255,255,255	foreground RGB color, for example: 32,255,255 (without spaces)
--background-color		background RGB color, for example: 0,0,128 (without spaces), transparent by default
--chars-file		optional path to UTF-8 text file with additional required characters (will be combined with 'chars' option), can be set multiple times
--data-format	txt	output data file format: txt, xml, bin, json, cbor
--kerning-pairs	disabled	generate kerning pairs: disabled, basic, regular (tuned by hinter), extended (bigger output size, but more precise)
--padding-up	0	padding up
--padding-right	0	padding right
--padding-down	0	padding down
--padding-left	0	padding left
--spacing-vert	0	spacing vertical
--spacing-horiz	0	spacing horizontal
--monochrome		disable anti-aliasing
--extra-info		write extra information to data file
--max-texture-count		maximum generated texture count (unlimited if not set)
--texture-name-suffix	index_aligned	texture name suffix: "index_aligned", "index" or "none"

Building Linux

Dependencies:

• GCC-4.9
• CMake 3.0
• FreeType

Build:

cmake .  
make

Building Windows (using vcpkg)

Download and install vcpkg and CMake 3.10.2 (or above). Run:

vcpkg install freetype
cmake -G "Visual Studio 14 2015" -DCMAKE_TOOLCHAIN_FILE=<path to vcpkg dir>/scripts/buildsystems/vcpkg.cmake

Open .sln in Visual Studio 2015 and rebuild all.

Building Windows

Download and install CMake 3.0 (or above) and FreeType. Run:

cmake -G "Visual Studio 14 2015"

Open .sln file in Visual Studio 2015, configure paths to FreeType and rebuild all.

Building macOS

(thanx to andycarle Moddable-OpenSource/moddable#325 (comment))

brew install freetype
git clone https://github.com/vladimirgamalyan/fontbm.git
cd fontbm
cmake .
make

Contributors

• AMDmi3
• cherniid
• Radfordhound
• phoddie

Special thanks

• phoddie

License

MIT License

The project also bundles third party software under its own licenses:

• lvandeve/lodepng - PNG encoder and decoder in C and C++ - zlib
• juj/RectangleBinPack - 2d rectangular bin packing - Public Domain
• leethomason/tinyxml2 - a simple, small, efficient, C++ XML parse - zlib
• UTF8-CPP - UTF-8 with C++ in a Portable Way - BSL-1.0
• catchorg/Catch2 - A modern, C++-native, header-only, test framework for unit-tests - BSL-1.0
• jarro2783/cxxopts - Lightweight C++ command line option parser - MIT
• nlohmann/json - JSON for Modern C++ - MIT

fontbm's Issues

Some kerning missing

TTF vs BMFont vs FontBM (ươ ượ VA ...).
From image, bitmap font from fontbm with --include-kerning-pairs but kerning amount is wrong.

TTF embedded bitmaps handled incorrectly

Some TTF fonts, for example Terminus TTF (https://files.ax86.net/terminus-ttf/), embed bitmaps for several font sizes. Freetype correctly loads these bitmaps when asked in FT_Load_Char - but in monochrome format (bitmap.num_grays = 2, bitmap.pixel_mode == FT_PIXEL_MODE_MONO), so you need to check and unpack monochrome bits to 8-bit grayscale bytes first before mixin in 4-byte color and alpha.

Wrong baseline?

Just compare fontbm vs BMFont vs Hiero, chars: A Á Â Ấ Ắ Ễ Ỗ
From image, I found some issues

• Glyph rendered, not good as Hiero (freetype).
• The baseline seem wrong
  BMFont: size=-48, lineHeight=56 base=44
  fontbm: size=48, lineHeight=57 base=36

kerning-pairs not available in current release build

Is there a chance that you could build a new executable release with the kerning-pairs feature in please?

The current build was before the kerning-pairs feature was added

Cheers

Nigel

Horizontal scaling factor is wrong when image cropped.

This may also apply to vertical cropping.

When using the "--texture-crop-width" option, my image was cropped to 128x138, but the horizontal scaling factor in the binary FNT file was 128.

Multiple font files in case of glyph not found

Hey @vladimirgamalyan,
First of all, thank you for this wonderful bitmap font generator.
I wonder if there is a possibility to add the option, to give under --font-file more than one font, so in case that some chars aren't included in the font file, it will fall back to other font file or maybe a default font file like rubik.ttf or ariel.ttf.
Maybe add a new parameter to the command like --default-font-file which will be the fallback font in case of glyph not found.

Feature Request: Dynamic height

Automatically increase the height accordingly.

Fonts generated by FontBM differ from their BMFont equivalents in size

Hi Vlad,

First off, FontBM seems like a great tool that should work perfectly for my project. I appreciate the work you've done with it.

I've been able to integrate it seamlessly so far, I'm just running into one issue.

I generated a font using FontBM on macOS, and I noticed the size of the characters generated by FontBM differ quite a lot from the exact same (or even slightly lesser) font size on BMFont.

BMFont

FontBM

This is strange since the font size on FontBM is even a tad smaller than the one on BMFont, yet the fonts themselves are still larger. You can also see this numerically by checking the width/height values of each character.

BMFont (truncated to save space)

info face="Bebas Neue" size=104 bold=0 italic=0 charset="" unicode=1 stretchH=100 smooth=1 aa=1 padding=0,0,0,0 spacing=1,1 outline=0
common lineHeight=105 base=83 scaleW=256 scaleH=256 pages=1 packed=0 alphaChnl=1 redChnl=0 greenChnl=0 blueChnl=0
page id=0 file="bebas_time_large_0.png"
chars count=11
char id=48   x=61    y=0     width=28    height=63    xoffset=3     yoffset=21    xadvance=34    page=0  chnl=15

FontBM (also truncated)

info face="Bebas Neue" size=-103 bold=0 italic=0 charset="" unicode=1 stretchH=100 smooth=0 aa=1 padding=0,0,0,0 spacing=1,1 outline=0
common lineHeight=103 base=92 scaleW=256 scaleH=256 pages=1 packed=0 alphaChnl=0 redChnl=4 greenChnl=4 blueChnl=4
page id=0 file="bebas_time_large_0.png"
chars count=11
char id=48   x=1     y=149   width=34    height=74    xoffset=3     yoffset=19    xadvance=40    page=0  chnl=15

The command I'm using to generate this font is:

fontbm --font-file fonts/bebas_regular.ttf --output ./notenduro/resources-round-240x240/fonts/watchface/bebas_time_large --background-color 0,0,0 --spacing-vert 1 --spacing-horiz 1 --chars 48,49,50,51,52,53,54,55,56,57,58 --font-size 88

Is there something I'm doing wrong here?

Thank you very much for your time.

How to turn off smoothing?

Is there any way to turn smoothing off with this library so that it's not anti-aliasing my textures?

Feature suggestion - output outlines

This idea may be stretching the scope of fontbm a bit much, but...

...we sometimes render a few characters of a font using an outline renderer. This is great for animated text effects with scaling and rotating text. We aren't trying to render TrueType fonts in general.

Would it make sense for fontbm to have an option to output the selected glyphs in a font as FreeType/TrueType outlines? We have the ability to render FreeType outlines now in the Moddable SDK, so either format could work.

Request: Compiled Version

This seems like a great tool, however i have no idea how to actually use it.

Does compiled version exist somewhere?

Thanks.

Feature: glyph alignment

Moddable is experimenting with a GPU that is more efficient when the x coordinate of a glyph is an even number. I couldn't find a way to achieve this with the existing command line options of fontbm. As a quick experiment, I changed line 19 of App.cpp App::getGlyphRectangles to round with glyph width:

result.emplace_back(((glyphInfo.width + additionalWidth) + 1) & ~1, glyphInfo.height + additionalHeight, kv.first);

This succeeds in forcing all the glyphs to an even horizontal position. Perhaps this could be an option like --align-horiz=2 and --align-vert=10. The default would be 1 to maintain the current behavior.

I am willing to try to make the changes, but first want to check if the approach is reasonable and you are willing to consider the feature. Thank you.

Whether the chnl value can be set？

Is it possible to set the value of A R G B chnl and generate the corresponding png. By default, it generates alphaChnl=0 redChnl=4 greenChnl=4 blueChnl=4, so png is not completely transparent in some background.

adding some new features

Hello thank you for the great project
I only have some suggestion that I think would be awesome if you can add them to the tool In future updates

• as you know the original BMFont have 2 option name Equalize the cell heights and Force offsets to zero that can be used to force tool to generate bitmap in 0 offset, but your project don't have these options, having those option can be really helpful in some case...
• you think its possible to add an option to the tool to generate SDF fonts? it could be very helpful in so many cases...
• and last but not least one thing that I thought about is can you create the project as a library too? so we can use it in our own projects? its less important but still could be very helpful.

feature request, solid round stroke color

H!,

Are you going to build solid round border function in it, in the near future ?
Say for example, a white text, and a [n.n] 'px' black border.

Like this program https://www.71squared.com/glyphdesigner , https://www.bmglyph.com

Glyph quality?

fontbm vs notepad vs hiero.

Glyph rendered, not good as Hiero (freetype).
Please take a look,
Chars: Ẳ Ầ Ặ Ẫ Ấ Ắ

---

fontbm vs bmfont
Baseline still not correct (char: g): #8

Italic or bold option

The original tool can also have an option for bold and italic is also available here :
http://www.angelcode.com/products/bmfont/doc/file_format.html

Crash when character has an glyph index but the glyph cannot be loaded

Greetings! First of all, thanks for making this wonderful tool. I'm experiencing a crash when trying to render a font with some characters that exist in the font but for some reason cannot be loaded.

The following font file reproduces the issue for me - Hack-Regular.ttf. A sample char range that leads to crashing is 8300-8400. The message is 'Load glyph error'.

Here's what happens - isGlyphProvided reports true, then renderGlyph throws an exception because of FT_Load_Char failure.

For some reason shrinking the range towards the offending character sometimes fixes the issue, which makes me think that there could be a side effect from loading specific glyphs that affects the ones that are loaded afterwards. But it's just a speculation, I'm not very familiar with freetype internals so I may be way off. Since I'm using an autogenerated chars file shrinking the range is not an option for me (and there's no way of cleaning up the file without knowing which characters are offending).

TL;DR: Replacing FT_Get_Char_Index with FT_Load_Char (like in renderGlyph) fixes the issue, skipping the offending character (having incomplete font is better than no font, right?). I'll send a PR with this solution soon.

Image text output

Can you add an option to output the image in a text format

Supplementary options could include

• What character to use for background and foreground
• The aspect ratio of a character

Thanks

unexpectedly large kerning table

When kerning is enabled with the --include-kerning-pairs option, the kerning tables can be surprisingly large. For example, when kerning is disabled the .fnt file generated from OpenSans using the Basic Latin, Latin-1 Supplement, and Cyrillic Unicode blocks is 9 KB. With kerning enabled, it is 489 KB.

fontbm is doing something very clever. It calculates synthetic kerning data for each possible glyph pair, even if the font does not contain a non-zero kerning offset for that pair. The relevant code is here:

fontbm/src/freeType/FtFont.h

Lines 205 to 216 in df0c2a8

	const auto error = FT_Get_Kerning(face, indexLeft, indexRight, FT_KERNING_UNFITTED, &kerning);
	if (error)
	throw std::runtime_error("Couldn't find glyphs kerning");
	// X advance is already in pixels for bitmap fonts
	if (!FT_IS_SCALABLE(face))
	return static_cast<int>(kerning.x);
	float firstRsbDelta = static_cast<float>(renderGlyph(nullptr, 0, 0, 0, 0, left, 0).rsbDelta);
	float secondLsbDelta = static_cast<float>(renderGlyph(nullptr, 0, 0, 0, 0, right, 0).lsbDelta);
	return static_cast <int> (std::floor((secondLsbDelta - firstRsbDelta + static_cast<float>(kerning.x) + 32) / static_cast<float>(1 << 6)));

This is clever because it allows effect of fractional adjustments for horizontal advance to be carried into the .fnt file which has only integer offsets. See the pseudocode for handling lsb_delta and rsb_delta in the FreeType documentation for details.

As an experiment, I disabled the generation of kerning pairs for pairs that have kerning offset of 0 by adding this check after line 207 in getKerning:

		if (!kerning.x)
			return 0;

With this in place, the .fnt output is 23 KB. That feels more reasonable.

FWIW – there is an inconsistency in the generation of the synthetic kerning pairs. If the font contain no kerning table !FT_HAS_KERNING(face) they are not generated.

The behavior currently implemented is clever, but it has a cost by increasing the kerning table output significantly (about 34x in this example). Further, it generates kerning data for pairs that are extremely unlikely to be used. The patch above could be a more reasonable default, or at least an option. For applications that want very precise layout and have the storage space for the larger tables, the current behavior seems great and could even be applied to fonts that do not containing a kerning table.

fontsize value is negative

I'm not sure why the fontsize value that you write to the output file is negative, when this should be positive integer.

(first line of text format .fnt file)
info face="Noto Sans" size=-48 bold=0 italic=0 charset="" unicode=1 stretchH=100 smooth=0 aa=1 padding=2,2,2,2 spacing=0,0 outline=0

Command line input has
fontbm.exe --font-file NotoSans-Regular.ttf --output notosans --chars 0-0,32-126,160,163,169,180,183,225,231,233,697-701,714-715,748,750,756-758,8210-8213,8216-8217,8220,8221,8471 --chars-file charsfile_pronunciation.txt --padding-left 2 --padding-right 2 --padding-up 2 --padding-down 2 --font-size 48 --texture-size 256x256,512x512,1024x512,1024x1024 --data-format txt

It looks like you set the value on line 257 of App.cpp as follows:

f.info.size = -static_cast<std::int16_t>(config.fontSize);

but I think you should not be negating the value from config.fontSize

instead it should be

f.info.size = static_cast<std::int16_t>(config.fontSize);

This is coming through as a negative value both in the txt format output and the bin format output (probably others as well). We use the binary value for our projects.

Cheers

Nigel

Mac version?

This isn't a bug report but a question. If here's a better place to post it, please let me know.

Your fontbm tool looks great. The rectangle packing is particularly impressive. We use BMFonts in the Moddable SDK to render anti-aliased text on a variety of microcontrollers. Our graphics documentation provides details about the features we use.

To generate BMFonts we usually use Glyph Designer, which is excellent but only available for macOS. We would like to have a single tool that works on all our development environments - macOS, Windows, and Linux. That way we can provide developers with consistent instructions and build integration no matter what platform they develop on.

One member of our community has already been successful using fontbmwith the Moddable SDK on Windows.

So... I wanted to ask if you had plans to support macOS at some point down the road.

Thank you!

Feature Request: Add a config option to use chars from a UTF-8 file

Hiya, thanks for writing this tool! I've been looking for a cross platform implementation of BMFont.
That said, it's missing possibly the most useful BMFont feature, and i'd like to request it: the "add characters from file" option. This option would take a path to a UTF-8 formatted text file, and include all the characters contained in the file in the font. This is very useful if you have, for example, a file full of Japanese text you wish to display with your program, but you don't want to include all 10000+ characters in the CJK unicode planes in your font images.