151 lines
5.7 KiB
Markdown
151 lines
5.7 KiB
Markdown
lv_font_conv - font convertor to compact bitmap format
|
|
======================================================
|
|
|
|
[](https://github.com/lvgl/lv_font_conv/actions)
|
|
[](https://www.npmjs.org/package/lv_font_conv)
|
|
|
|
Converts TTF/WOFF/OTF fonts to __[compact format](https://github.com/lvgl/lv_font_conv/blob/master/doc/font_spec.md)__, suitable for small embedded systems. Main features are:
|
|
|
|
- Allows bitonal and anti-aliased glyphs (1-4 bits per pixel).
|
|
- Preserves kerning info.
|
|
- Compression.
|
|
- Users can select required glyphs only (subsetting).
|
|
- Multiple font sources can be merged.
|
|
- Simple CLI interface, easy to integrate into external build systems.
|
|
|
|
|
|
## Install the script
|
|
|
|
[node.js](https://nodejs.org/en/download/) v10+ required.
|
|
|
|
Global install of the last version, execute as "lv_font_conv"
|
|
|
|
```sh
|
|
# install release from npm registry
|
|
npm i lv_font_conv -g
|
|
# install from github's repo, master branch
|
|
npm i lvgl/lv_font_conv -g
|
|
```
|
|
|
|
**run via [npx](https://www.npmjs.com/package/npx) without install**
|
|
|
|
```sh
|
|
# run from npm registry
|
|
npx lv_font_conv -h
|
|
# run from github master
|
|
npx github:lvgl/lv_font_conv -h
|
|
```
|
|
|
|
Note, runing via `npx` may take some time until modules installed, be patient.
|
|
|
|
|
|
## CLI params
|
|
|
|
Common:
|
|
|
|
- `--bpp` - bits per pixel (antialiasing).
|
|
- `--size` - output font size (pixels).
|
|
- `-o`, `--output` - output path (file or directory, depends on format).
|
|
- `--format` - output format.
|
|
- `--format dump` - dump glyph images and font info, useful for debug.
|
|
- `--format bin` - dump font in binary form (as described in [spec](https://github.com/lvgl/lv_font_conv/blob/master/doc/font_spec.md)).
|
|
- `--format lvgl` - dump font in [LittlevGL](https://github.com/lvgl/lvgl) format.
|
|
- `--force-fast-kern-format` - always use more fast kering storage format,
|
|
at cost of some size. If size difference appears, it will be displayed.
|
|
- `--lcd` - generate bitmaps with 3x horizontal resolution, for subpixel
|
|
smoothing.
|
|
- `--lcd-v` - generate bitmaps with 3x vertical resolution, for subpixel
|
|
smoothing.
|
|
- `--use-color-info` - try to use glyph color info from font to create
|
|
grayscale icons. Since gray tones are emulated via transparency, result
|
|
will be good on contrast background only.
|
|
- `--lv-include` - only with `--format lvgl`, set alternate path for `lvgl.h`.
|
|
|
|
Per font:
|
|
|
|
- `--font` - path to font file (ttf/woff/woff2/otf). May be used multiple time for
|
|
merge.
|
|
- `-r`, `--range` - single glyph or range + optional mapping, belongs to
|
|
previously declared `--font`. Can be used multiple times. Examples:
|
|
- `-r 0x1F450` - single value, dec or hex format.
|
|
- `-r 0x1F450-0x1F470` - range.
|
|
- `-r '0x1F450=>0xF005'` - single glyph with mapping.
|
|
- `-r '0x1F450-0x1F470=>0xF005'` - range with mapping.
|
|
- `-r 0x1F450 -r 0x1F451-0x1F470` - 2 ranges.
|
|
- `-r 0x1F450,0x1F451-0x1F470` - the same as above, but defined with single `-r`.
|
|
- `--symbols` - list of characters to copy (instead of numeric format in `-r`).
|
|
- `--symbols 0123456789.,` - extract chars to display numbers.
|
|
- `--autohint-off` - do not force autohinting ("light" is on by default).
|
|
- `--autohint-strong` - use more strong autohinting (will break kerning).
|
|
|
|
Additional debug options:
|
|
|
|
- `--no-compress` - disable built-in RLE compression.
|
|
- `--no-prefilter` - disable bitmap lines filter (XOR), used to improve
|
|
compression ratio.
|
|
- `--no-kerning` - drop kerning info to reduce size (not recommended).
|
|
- `--full-info` - don't shorten 'font_info.json' (include pixels data).
|
|
|
|
|
|
## Examples
|
|
|
|
Merge english from Roboto Regular and icons from Font Awesome, and show debug
|
|
info:
|
|
|
|
`env DEBUG=* lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F --font FontAwesome.ttf -r 0xFE00=>0x81 --size 16 --format bin --bpp 3 --no-compress -o output.font`
|
|
|
|
Merge english & russian from Roboto Regular, and show debug info:
|
|
|
|
`env DEBUG=* lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F -r 0x401,0x410-0x44F,0x451 --size 16 --format bin --bpp 3 --no-compress -o output.font`
|
|
|
|
Dump all Roboto glyphs to inspect icons and font details:
|
|
|
|
`lv_font_conv --font Roboto-Regular.ttf -r 0x20-0x7F --size 16 --format dump --bpp 3 -o ./dump`
|
|
|
|
**Note**. Option `--no-compress` exists temporary, to avoid confusion until LVGL
|
|
adds compression support.
|
|
|
|
|
|
## Technical notes
|
|
|
|
### Supported output formats
|
|
|
|
1. **bin** - universal binary format, as described in https://github.com/lvgl/lv_font_conv/tree/master/doc.
|
|
2. **lvgl** - format for LittlevGL, C file. Has minor limitations and a bit
|
|
bigger size, because C does not allow to effectively define relative offsets
|
|
in data blocks.
|
|
3. **dump** - create folder with each glyph in separate image, and other font
|
|
data as `json`. Useful for debug.
|
|
|
|
### Merged font metrics
|
|
|
|
When multiple fonts merged into one, sources can have different metrics. Result
|
|
will follow principles below:
|
|
|
|
1. No scaling. Glyphs will have exactly the same size, as intended by font authors.
|
|
2. The same baseline.
|
|
3. `OS/2` metrics (`sTypoAscender`, `sTypoDescender`, `sTypoLineGap`) will be
|
|
used from the first font in list.
|
|
4. `hhea` metrics (`ascender`, `descender`), defined as max/min point of all
|
|
font glyphs, are recalculated, according to new glyphs set.
|
|
|
|
|
|
## Development
|
|
|
|
Current package includes WebAssembly build of FreeType with some helper
|
|
functions. Everything is wrapped into Docker and requires zero knowledge about
|
|
additional tools install. See `package.json` for additional commands. You may
|
|
need those if decide to upgrade FreeType or update helpers.
|
|
|
|
This builds image with emscripten & freetype, usually should be done only once:
|
|
|
|
```
|
|
npm run build:dockerimage
|
|
```
|
|
|
|
This compiles helpers and creates WebAssembly files:
|
|
|
|
```
|
|
npm run build:freetype
|
|
```
|