mirror
/
msdf-atlas-gen
mirror of https://github.com/Chlumsky/msdf-atlas-gen.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Added Readme

This commit is contained in:
Chlumsky 2020-03-08 14:50:29 +01:00
parent cad221afcd
commit 59af32a278
2 changed files with 120 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
README.md
View File

@ -2,3 +2,122 @@
# Multi-channel signed distance field atlas generator # Multi-channel signed distance field atlas generator
This is a utility for generating compact font atlases using [MSDFgen](https://github.com/Chlumsky/msdfgen). This is a utility for generating compact font atlases using [MSDFgen](https://github.com/Chlumsky/msdfgen).
It can read TTF and OTF font files, select a subset of characters, generate distance fields or bitmaps for each, and tightly pack them into an atlas bitmap, which can be e.g. used as a texture in video games. The atlas can be exported as an image file or an [Artery Font](https://github.com/Chlumsky/artery-font-format) file, and its layout written into a CSV or structured JSON file.
![Atlas example](https://user-images.githubusercontent.com/18639794/76163889-811f2e80-614a-11ea-9b28-1eed54dbb899.png)
## Getting started
This project can be used either as a library or as a console program.
To start using the program immediately, there is a Windows binary available for download in the ["Releases" section](https://github.com/Chlumsky/msdf-atlas-gen/releases).
To build the project, you may use the included [Visual Studio solution](msdf-atlas-gen.sln) or the [Unix Makefile](Makefile).
## Atlas types
The utility can generate the atlas bitmap in the following six ways:
| |Hard mask|Soft mask|SDF|PSDF|MSDF|MTSDF|
|-|-|-|-|-|-|-|
| |![Hard mask](https://user-images.githubusercontent.com/18639794/76163903-9eec9380-614a-11ea-92cb-d49485bbad31.png)|![Soft mask](https://user-images.githubusercontent.com/18639794/76163904-a1e78400-614a-11ea-912a-b220fed081cb.png)|![SDF](https://user-images.githubusercontent.com/18639794/76163905-a4e27480-614a-11ea-93eb-c80819a44e6e.png)|![PSDF](https://user-images.githubusercontent.com/18639794/76163907-a6ac3800-614a-11ea-8d97-dafc1db6711d.png)|![MSDF](https://user-images.githubusercontent.com/18639794/76163909-a9a72880-614a-11ea-9726-e825ee0dde94.png)|![MTSDF](https://user-images.githubusercontent.com/18639794/76163910-ac098280-614a-11ea-8b6b-811d864cd584.png)|
|Channels:|1 (1-bit)|1|1|1|3|4|
|Anti-aliasing:|-|Yes|Yes|Yes|Yes|Yes|
|Scalability:|-|-|Yes|Yes|Yes|Yes|
|Sharp corners:|-|-|-|-|Yes|Yes|
|Soft effects:|-|-|Yes|-|-|Yes|
|Hard effects:|-|-|-|Yes|Yes|Yes|
Notes:
- *Sharp corners* refers to preservation of corner sharpness when upscaled.
- *Soft effects* refers to the support of effects that use true distance, such as glows, rounded borders, or simplified shadows.
- *Hard effects* refers to the support of effects that use pseudo-distance, such as mitered borders or thickness adjustment.
## Command line arguments
### Input
- `-font <fontfile.ttf/otf>` &ndash; sets the input font file.
- `-charset <charset.txt>` &ndash; sets the character set. The ASCII charset will be used if not specified. See [the syntax specification](#character-set-specification-syntax) of `charset.txt`.
### Bitmap atlas type
`-type <type>` &ndash; see [Atlas types](#atlas-types)
`<type>` can be one of:
- `hardmask` &ndash; a non-anti-aliased binary image
- `softmask` &ndash; an anti-aliased image
- `sdf` &ndash; a true signed distance field (SDF)
- `psdf` &ndash; a pseudo-distance field
- `msdf` (default) &ndash; a multi-channel signed distance field (MSDF)
- `mtsdf` &ndash; a combination of MSDF and true SDF in the alpha channel
### Atlas image format
`-format <format>`
`<format>` can be one of:
- `png` &ndash; a compressed PNG image
- `bmp` &ndash; an uncompressed BMP image
- `tiff` &ndash; an uncompressed floating-point TIFF image
- `text` &ndash; a sequence of pixel values in plain text
- `textfloat` &ndash; a sequence of floating-point pixel values in plain text
- `bin` &ndash; a sequence of pixel values encoded as raw bytes of data
- `binfloat` &ndash; a sequence of pixel values encoded as raw 32-bit floating-point values
### Atlas dimensions
`-dimensions <width> <height>` &ndash; sets fixed atlas dimensions
Alternativelly, the minimum possible dimensions may be selected automatically if a dimensions constraint is set instead:
- `-pots` &ndash; a power-of-two square
- `-potr` &ndash; a power-of-two square or rectangle (2:1)
- `-square` &ndash; any square dimensions
- `-square2` &ndash; square with even side length
- `-square4` (default) &ndash; square with side length divisible by four
### Outputs
Any subset of the following may be specified:
- `-imageout <filename.*>` &ndash; saves the atlas bitmap as a plain image file. Format matches `-format`
- `-json <filename.json>` &ndash; writes the atlas's layout data as well as other metrics into a structured JSON file
- `-csv <filename.csv>` &ndash; writes the glyph layout data into a simple CSV file
- `-arfont <filename.arfont>` &ndash; saves the atlas and its layout data as an [Artery Font](https://github.com/Chlumsky/artery-font-format) file
- `-shadronpreview <filename.shadron> <sample text>` &ndash; generates a [Shadron script](https://www.arteryengine.com/shadron/) that uses the generated atlas to draw a sample text as a preview
### Glyph configuration
- `-size <EM size>` &ndash; sets the size of the glyphs in the atlas in pixels per EM
- `-minsize <EM size>` &ndash; sets the minimum size. The largest possible size that fits the same atlas dimensions will be used
- `-emrange <EM range>` &ndash; sets the distance field range in EM's
- `-pxrange <pixel range>` (default = 2) &ndash; sets the distance field range in output pixels
### Distance field generator settings
- `-angle <angle>` &ndash; sets the minimum angle between adjacent edges to be considered a corner. Append D for degrees (`msdf` / `mtsdf` only)
- `-errorcorrection <threshold>` &ndash; sets the threshold used to detect and correct potential artifacts. 0 disables error correction (`msdf` / `mtsdf` only)
- `-miterlimit <value>` &ndash; sets the miter limit that limits the extension of each glyph's bounding box due to very sharp corners (`psdf` / `msdf` / `mtsdf` only)
- `-nooverlap` &ndash; disables resolution of overlapping contours
- `-noscanline` &ndash; disables the scanline pass, which corrects the distance field's signs according to the non-zero fill rule
- `-seed <N>` &ndash; sets the initial seed for the edge coloring heuristic
## Character set specification syntax
The character set file is a text file with UTF-8 or ASCII encoding.
The characters can be denoted in the following ways:
- Single character: `'A'` (UTF-8 encoded), `65` (decimal Unicode), `0x41` (hexadecimal Unicode)
- Range of characters: `['A', 'Z']`, `[65, 90]`, `[0x41, 0x5a]`
- String of characters: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ"` (UTF-8 encoded)
The entries should be separated by commas or whitespace.
In between quotation marks, backslash is used as the escape character (e.g. `'\''`, `'\\'`, `"!\"#"`).
The order in which characters appear is not taken into consideration.
Additionally, the include directive can be used to include other charset files and combine character sets in a hierarchical way.
It must be written on a separate line:
`@include "base-charset.txt"`

2
msdf-atlas-gen/main.cpp
View File

@ -62,7 +62,7 @@ OUTPUT SPECIFICATION - one or more can be specified
GLYPH CONFIGURATION GLYPH CONFIGURATION
-size <EM size> -size <EM size>
Specified the size of the glyphs in the atlas bitmap in pixels per EM. Specifies the size of the glyphs in the atlas bitmap in pixels per EM.
-minsize <EM size> -minsize <EM size>
Specifies the minimum size. The largest possible size that fits the same atlas dimensions will be used. Specifies the minimum size. The largest possible size that fits the same atlas dimensions will be used.
-emrange <EM range> -emrange <EM range>