diff --git a/README.md b/README.md index 43a3aea..3d2f5f5 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,122 @@ # Multi-channel signed distance field atlas generator 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 ` – sets the input font file. +- `-charset ` – 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 ` – see [Atlas types](#atlas-types) + +`` can be one of: + +- `hardmask` – a non-anti-aliased binary image +- `softmask` – an anti-aliased image +- `sdf` – a true signed distance field (SDF) +- `psdf` – a pseudo-distance field +- `msdf` (default) – a multi-channel signed distance field (MSDF) +- `mtsdf` – a combination of MSDF and true SDF in the alpha channel + +### Atlas image format + +`-format ` + +`` can be one of: + +- `png` – a compressed PNG image +- `bmp` – an uncompressed BMP image +- `tiff` – an uncompressed floating-point TIFF image +- `text` – a sequence of pixel values in plain text +- `textfloat` – a sequence of floating-point pixel values in plain text +- `bin` – a sequence of pixel values encoded as raw bytes of data +- `binfloat` – a sequence of pixel values encoded as raw 32-bit floating-point values + +### Atlas dimensions + +`-dimensions ` – sets fixed atlas dimensions + +Alternativelly, the minimum possible dimensions may be selected automatically if a dimensions constraint is set instead: + +- `-pots` – a power-of-two square +- `-potr` – a power-of-two square or rectangle (2:1) +- `-square` – any square dimensions +- `-square2` – square with even side length +- `-square4` (default) – square with side length divisible by four + +### Outputs + +Any subset of the following may be specified: + +- `-imageout ` – saves the atlas bitmap as a plain image file. Format matches `-format` +- `-json ` – writes the atlas's layout data as well as other metrics into a structured JSON file +- `-csv ` – writes the glyph layout data into a simple CSV file +- `-arfont ` – saves the atlas and its layout data as an [Artery Font](https://github.com/Chlumsky/artery-font-format) file +- `-shadronpreview ` – 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 ` – sets the size of the glyphs in the atlas in pixels per EM +- `-minsize ` – sets the minimum size. The largest possible size that fits the same atlas dimensions will be used +- `-emrange ` – sets the distance field range in EM's +- `-pxrange ` (default = 2) – sets the distance field range in output pixels + +### Distance field generator settings + +- `-angle ` – sets the minimum angle between adjacent edges to be considered a corner. Append D for degrees (`msdf` / `mtsdf` only) +- `-errorcorrection ` – sets the threshold used to detect and correct potential artifacts. 0 disables error correction (`msdf` / `mtsdf` only) +- `-miterlimit ` – sets the miter limit that limits the extension of each glyph's bounding box due to very sharp corners (`psdf` / `msdf` / `mtsdf` only) +- `-nooverlap` – disables resolution of overlapping contours +- `-noscanline` – disables the scanline pass, which corrects the distance field's signs according to the non-zero fill rule +- `-seed ` – 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"` diff --git a/msdf-atlas-gen/main.cpp b/msdf-atlas-gen/main.cpp index fb21ee1..1cc4731 100644 --- a/msdf-atlas-gen/main.cpp +++ b/msdf-atlas-gen/main.cpp @@ -62,7 +62,7 @@ OUTPUT SPECIFICATION - one or more can be specified GLYPH CONFIGURATION -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 Specifies the minimum size. The largest possible size that fits the same atlas dimensions will be used. -emrange