# `Cauldron2D.Drafter.Client.Picture`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_2d_drafter/lib/cauldron_2d/drafter/client/picture.ex#L1)

How a game's picture (a scene's `:picture`) reaches a terminal that keeps images: the
size it is drawn at, how each frame is encoded, and whether frames are double
buffered. Options are a list, or a comma-separated string:

  * `native` — drawn at the game's own size times the largest whole number that fits
    the pane, the terminal scaling it to the pane
  * `native:N` — at the game's own size times `N`
  * `size:WxH` — the game's own size is `W` by `H` pixels, over what the game declares
    (a scene's `:native`, else the look's `:native`)
  * `png` — each frame is sent as a PNG, palette when it has at most 256 colours, in
    place of deflated raw pixels
  * `swap` — each frame is stored before the last is let go, so the pane never blanks
    between frames
  * `none` — none of these

Without `native`, or with it when neither the game nor `size` gives a size, the picture
is drawn at the pane's cells times the surface's density and sent as raw pixels.

`options/2` reads a client's options from its mount props (`:picture`), else the
application env `config :cauldron_2d_drafter, picture: ...`, else the environment
variable `CAULDRON_PICTURE`, else the game's look (`:picture`), else `default/0`. `surface_props/3` turns them into
`Cauldron2D.Drafter.Surface` props.

    iex> Cauldron2D.Drafter.Client.Picture.parse("native:2,png,swap")
    {:ok, [{:native, 2}, :png, :swap]}

# `option`

```elixir
@type option() ::
  :native
  | {:native, pos_integer()}
  | {:size, {pos_integer(), pos_integer()}}
  | :png
  | :swap
```

# `default`

```elixir
@spec default() :: [option()]
```

The options used when none are given.

# `options`

```elixir
@spec options(map(), map()) :: [option()]
```

The options for a client of a game whose look is `look`, mounted with `props`: the
`:picture` prop, else the application env, else `CAULDRON_PICTURE`, else the look's
`:picture`, else `default/0`. Raises `ArgumentError` when the one found does not parse.

# `parse`

```elixir
@spec parse(String.t() | [option()]) :: {:ok, [option()]} | {:error, String.t()}
```

The options a string names, or the list given back, with the first that is not an
option as the error.

# `surface_props`

```elixir
@spec surface_props([option()], map(), map()) :: keyword()
```

The `:native`, `:native_scale`, `:picture_format` and `:swap` props of a
`Cauldron2D.Drafter.Surface` showing `scene` under `look` with `options`.

---

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