# `raster-fonts` [![Crates.io][crates-img]][crates] [![Documentation][docs-img]][docs]

[crates-img]: https://img.shields.io/crates/v/raster-fonts.svg
[crates]:     https://crates.io/crates/raster-fonts
[docs-img]:   https://docs.rs/raster-fonts/badge.svg
[docs]:       https://docs.rs/raster-fonts

This crate provides a command line utility for rasterizing true type fonts into bitmaps,
both traditional and signed distance fields. It also provides a tiny library for deserializing
the metadata required for dynamic text layout calculations; both [`serde`][serde] and
[`rkyv`][rkyv] are supported here.

[serde]: https://crates.io/crates/serde
[rkyv]:  https://crates.io/crates/rkyv

## The `font2img` CLI

### Installation Using `cargo`

```
> cargo install raster-fonts --features="bin"
```

### Basic Usage

```
> font2img <InputFontFile> <OutputImagePath> <OutputMetadataPath>
```

This will generate a monochrome signed distance field texture containing all glyphs in the printable
ASCII range from the given font file. [As described by Chris Green, then working for Valve][valve-paper]:

[valve-paper]: https://steamcdn-a.akamaihd.net/apps/valve/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf

> In the simplest case, this texture can then be rendered simply by using the alpha-testing and
> alpha-thresholding feature of modern GPUs, without a custom shader. [...]
> 
> With the use of programmable shading, the technique is extended to perform various special effect
> renderings, including soft edges, outlining, drop shadows, multi-colored images, and sharp corners.

For a short video demonstration of this technique, see [this video by Martin Donald][mdonald-demo].

[mdonald-demo]: https://www.youtube.com/watch?v=1b5hIMqz_wM

**Supported output image formats** include PNG, BMP, TIFF, TGA. The **supported metadata formats**
are [RON][ron], [JSON][json], and [RKYV][rkyv]. Note that kerning information cannot be exported to
JSON, because JSON dictionaries must be indexed by strings, whereas the other formats support indexing
by pairs of characters.

[ron]:  https://crates.io/crates/ron
[json]: https://crates.io/crates/serde_json
[rkyv]: https://crates.io/crates/rkyv

### Specifying Custom Character Ranges

```
> font2img <Font> <Img> <Meta> [Charset]...
```

To rasterize a different set of glyphs, one or more Unicode codepoint ranges must be specified after the
input/output paths. Codepoints are given in hexadecimal, without any prefix, and may stand alone.
Alternatively, a contiguous range may be specified by the inclusive minimum and maximum. For example:

```
# This is equivalent to the basic invocation from the previous section:
> font2img <Font> <Img> <Meta> 20-7F

# Additioanlly rasterize printable characters from the Latin-1 Supplement:
> font2img <Font> <Img> <Meta> 20-7F A1-FF

# Throw in the Pilcrow sign (¶) only:
> font2img <Font> <Img> <Meta> 20-7F B1
```

### Generating Conventional Bitmap Fonts

If you do not wish to use signed distance fields for whatever reason, you can switch to conventional
glyph rendering with the `--coverage-levels <N>` option (`-l <N>` for short), where `<N>` is the number
of distinct grayscale values greater than 0 you want in the output image. Regardless of the number of
levels, the output image will be a monochrome 8bpp image, with the highest level set to 255.

```
# Rasterize with maximum fidelity:
> font2img -l 255 <Font> <Img> <Meta>

# Generate a binary image, i.e. rasterize without anti-aliasing:
> font2img -l 1 <Font> <Img> <Meta>

# Use a happy medium with 16 total distinct values:
> font2img -l 15 <Font> <Img> <Meta>
```

This is still useful, especially if you know the exact text size you need, and want to manually process
the texture after generating it with this tool.

### Full Help Output

```
> font2img --help
Bitmap font creation tool and accompanying metadata deserialization library

Usage: font2img [OPTIONS] <FONT_PATH> <IMG_PATH> <META_PATH> [CHARSET]...

Arguments:
  <FONT_PATH>   Path to the font file to convert
  <IMG_PATH>    Path to where the output image should be written
  <META_PATH>   Path to where the output meta data should be written
  [CHARSET]...  List of Unicode codepoint ranges written in hex

Options:
  -l, --coverage-levels <COVERAGE_LEVELS>
          Enable coverage-based (as opposed to SDF) rasterization with the specified number of distinct levels above 0
  -s, --scale <SCALE>
          Desired font pixel height [default: 24]
  -p, --padding <PADDING>
          Desired number of pixels between glyphs in output texture [default: 8]
  -o, --output-image-size <OUTPUT_IMAGE_SIZE>
          Side length of the square output texture [default: 512]
      --skip-kerning-table
          Exclude additional kerning information from output metadata
  -h, --help
          Print help information
  -V, --version
          Print version information
```

## The `raster_fonts` Library

This is a single-module library of just a few plain-old data types that implement various de-/serialization
traits, depending on the cargo features you set. As such, you'll want to use different features depending on
the data format of your choice. So if you prefer `rkyv`, put this into your `Cargo.toml`:

```toml
[dependencies]
raster-fonts = { version = "0.1", features = ["rkyv-deserialize"] }
rkyv = "0.7"
```

If you want to use `serde`, you'll also need either `serde_json` or the `ron` crate:

```toml
[dependencies]
raster-fonts = { version = "0.1", features = ["serde-deserialize"] }
# depending on data format:
serde_json = "1"
ron = "0.8"
```

### [Documentation][docs]

[docs]: https://docs.rs/raster-fonts