msdf-bmfont
v1.1.0
Published
Creates a bitmap font of signed distance fields from a font file
Downloads
36
Readme
msdf-bmfont
Converts a .ttf
font file into multichannel signed distance fields, then outputs packed spritesheets and a json representation of an AngelCode BMfont.
Signed distance fields are a method of reproducing vector shapes from a texture representation, popularized in this paper by Valve. This tool uses Chlumsky/msdfgen to generate multichannel signed distance fields to preserve corners. The distance fields are created from vector fonts, then rendered into texture pages. A BMFont object is provided for character layout.
Install
$ npm install msdf-bmfont
Unless previously installed you'll need Cairo, since node-canvas depends on it. For system-specific installation view the node-canvas wiki.
You can quickly install the dependencies by using the command for your OS:
OS | Command
----- | -----
OS X | brew install pkg-config cairo libpng jpeg giflib
Ubuntu | sudo apt-get install libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev build-essential g++
Fedora | sudo yum install cairo cairo-devel cairomm-devel libjpeg-turbo-devel pango pango-devel pangomm pangomm-devel giflib-devel
Solaris | pkgin install cairo pkg-config xproto renderproto kbproto xextproto
Windows | Instructions on the node-canvas wiki
El Capitan users: If you have recently updated to El Capitan and are experiencing trouble when compiling, run the following command: xcode-select --install
. Read more about the problem on Stack Overflow.
Examples
Writing the distance fields and font data to disk:
const generateBMFont = require('msdf-bmfont');
const fs = require('fs');
generateBMFont('Some-Font.ttf', (error, textures, font) => {
if (error) throw error;
textures.forEach((sheet, index) => {
font.pages.push(`sheet${index}.png`);
fs.writeFile(`sheet${index}.png`, sheet, (err) => {
if (err) throw err;
});
});
fs.writeFile('font.json', JSON.stringify(font), (err) => {
if (err) throw err;
});
});
Generating a single channel signed distance field with a custom character set:
const generateBMFont = require('msdf-bmfont');
const opt = {
charset: 'ABC.ez_as-123!',
fieldType: 'sdf'
};
generateBMFont('Some-Font.ttf', opt, (error, textures, font) => {
...
});
Usage
generateBMFont(fontPath, [opt], callback)
Renders a bitmap font from the font at fontPath
with optional opt
settings, triggering callback
on complete.
Options:
charset
(String|Array)- the characters to include in the bitmap font. Defaults to all ASCII printable characters.
fontSize
(Number)- the font size at which to generate the distance field. Defaults to
42
- the font size at which to generate the distance field. Defaults to
textureWidth, textureHeight
(Number)- the dimensions of an output texture sheet, normally power-of-2 for GPU usage. Both dimensions default to
512
- the dimensions of an output texture sheet, normally power-of-2 for GPU usage. Both dimensions default to
texturePadding
(Number)- pixels between each glyph in the texture. Defaults to
2
- pixels between each glyph in the texture. Defaults to
transparent
(Boolean)- generate texture atlases with a transparent background, instead of white
fieldType
(String)- what kind of distance field to generate. Defaults to
msdf
. Must be one of:msdf
Multi-channel signed distance fieldsdf
Monochrome signed distance fieldpsdf
monochrome signed pseudo-distance field
- what kind of distance field to generate. Defaults to
distanceRange
(Number)- the width of the range around the shape between the minimum and maximum representable signed distance in pixels, defaults to
3
- the width of the range around the shape between the minimum and maximum representable signed distance in pixels, defaults to
The callback
is called with the arguments (error, textures, font)
error
on success will be null/undefinedtextures
an array of Buffers, each containing the PNG data of one texture sheetfont
an object containing the BMFont data, to be used to render the font
Since opt
is optional, you can specify callback
as the second argument.
License
MIT, see LICENSE.md for details.