# `HarfbuzzEx`
[🔗](https://github.com/jkwchui/harfbuzz_ex/blob/main/lib/harfbuzz_ex.ex#L1)

Elixir wrapper for Rust `rustybuzz` crate for OpenType shaping.

If I/O and memory are not concerns (the font file is small, or the task infrequent), use `get/3` to access data from the shaped glyphs directly.  This creates a shaper on a one-off basis.

If the font file-size is large and shaping is done frequently, explicitly use the `new/1` to load the font into memory. Shaping with `shape/2` is then CPU bound.  Use `stop/1` to release the memory.

# `child_spec`

Generates the child spec, automatically using the `:name` as the `:id`

# `get`

# `get!`

Input a string, shape with the font, and return a list of shaped glyphs.

Use `:all` for a list of `%HarfbuzzEx.Glyph{}` structs, or one of `:name`, `:x_advance`, `:y_advance`, `:x_offset`, `:y_offset` for a list of string (`:name`) or integers.

# `new`

Starts a new Rust instance for the given font.

Returns `{:ok, pid}` on success.

# `new!`

Same as `new/2` but raises on error.

# `shape`

Shapes text using the given Shaper process, returning the full set of shaped instructions as a map of:
* `:name` (glyph name)
* `:x_advance`
* `:y_advance`
* `:x_offset`
* `:y_offset`

# `shape`

Same as `shape!/3` but returns an `:ok` tuple.

# `shape!`

Same as `shape/2` but raises on error.

# `shape!`

Shapes text using the given Shaper process, returning *only* the requested parameter as a list.  This is most useful for extracting a list of glyphnames by invoking `shape!(pid, text, :name)`.

# `start_link`

Starts a GenServer to hold the Rust instance.  Accepts a keyword list of options for configuration:
* `:font_path`: path to the font file (typically `priv/fonts/your_font_file.ttf`)
* `:name`: the registered name for the GenServer

# `stop`

Stops the Shaper process.
This drops the reference to the Rust resource, allowing the BEAM
to garbage collect the memory (font data + parsed tables).

---

*Consult [api-reference.md](api-reference.md) for complete listing*