# `Cauldron2D.Renderer`
[🔗](https://github.com/jaman/cauldron/blob/v0.1.3/cauldron_2d/lib/cauldron_2d/renderer.ex#L1)

Chooses between drawing a surface as pixels or as glyphs.

Modes are `:text`, `:pixel`, `:kitty`, `:iterm2` and `:sixel`. `:pixel` means "whichever
protocol this terminal has"; the other three name one outright.

A mode is resolved most specific first:

  1. an override passed by the caller, when it is one of the modes
  2. `CAULDRON_MODE` in the environment
  3. the `:cauldron_2d` application environment's `:mode` key
  4. `:pixel`

A resolved `:pixel` is then asked of `FrenchCurve.Capability.detect/0`. Its `:braille`
answer counts as no pixel protocol, and the text renderer takes over.

# `describe`

```elixir
@spec describe(atom() | nil) :: String.t()
```

The resolved protocol's name, or `"text"`, for a status bar.

# `mode`

```elixir
@spec mode(atom() | nil) :: :pixel | :text
```

Whether the surface is drawn as an image or as characters.

`:pixel` when `protocol/1` finds one, `:text` otherwise. `override` is a mode name, or `nil`
to leave the choice to the environment and configuration.

# `modes`

```elixir
@spec modes() :: [atom()]
```

The mode names accepted as an override, in `CAULDRON_MODE`, or in application config.

# `parse`

```elixir
@spec parse(String.t() | nil) :: atom() | nil
```

The mode `value` names, or `nil` when it names none.

Surrounding whitespace and case are ignored. `nil` in gives `nil` out.

# `protocol`

```elixir
@spec protocol(atom() | nil) :: :kitty | :iterm2 | :sixel | nil
```

The pixel protocol to draw with, or `nil` for the text renderer.

`override` is a mode name, or `nil` to leave the choice to the environment and
configuration. An override that is not one of `modes/0` is ignored.

---

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