@spec frame(FrenchCurve.Raster.t(), term(), keyword()) :: frame() | nil

The sequences for drawing raster into a cell box, and for drawing it again.

Use this rather than assembling a frame from FrenchCurve.Backend.Kitty's pieces. The kitty protocol can store an image under an id and place it repeatedly, which is the cheap way to animate — but not every terminal that speaks kitty implements that part, and one that does not draws nothing at all when sent a store and then a placement. FrenchCurve.Capability.placements?/0 is the question, and this function asks it.

Either way the image is named and clear really removes it. That matters more than it looks: a kitty image is an overlay rather than cells, so text drawn over it does not rub it out and leaving the alternate screen does not discard it. An unnamed one cannot be taken off at all, and is still on the screen after the program has exited.

id names the region across frames — any term; the same one must come back each time so the picture replaces itself rather than piling up. nil for a terminal with no pixels at all, which is the caller's cue to draw text instead.

Options

• :fit — {cols, rows}, the cell box to draw into. Omitted sizes from the pixels
• :compress — deflate the payload where the protocol allows, default true
• :protocol — force one instead of detecting. :placements forces the kitty dialect

Examples

iex> raster = FrenchCurve.Raster.new(8, 8)
iex> {paint, clear, place} =
...>   FrenchCurve.frame(raster, :meter, fit: {10, 2}, protocol: :kitty, placements: true)
iex> {paint =~ "a=t,", paint =~ "a=p", clear =~ "a=d", is_binary(place)}
{true, true, true, true}

iex> raster = FrenchCurve.Raster.new(8, 8)
iex> {paint, clear, place} =
...>   FrenchCurve.frame(raster, :meter, fit: {10, 2}, protocol: :kitty, placements: false)
iex> {paint =~ "a=T", paint =~ "a=p", clear =~ "a=d", place}
{true, false, true, nil}

iex> FrenchCurve.frame(FrenchCurve.Raster.new(8, 8), :meter, protocol: :braille)
nil

@spec image_id(term()) :: pos_integer()

The kitty image id for id, a positive integer inside the protocol's range.

Any term becomes the same number every time, so a caller can name its regions however it likes and still have each one replace itself.

iex> FrenchCurve.image_id({:roll, 3}) == FrenchCurve.image_id({:roll, 3})
true
iex> FrenchCurve.image_id(:anything) > 0
true

@spec render(
  FrenchCurve.Raster.t(),
  keyword()
) :: term()

Renders raster with the protocol given in opts, or with the detected one.

Options are passed through to the backend, plus:

• :protocol — :kitty, :sixel, :iterm2 or :braille. Defaults to FrenchCurve.Capability.detect/0.

Returns a binary for the pixel protocols and [[FrenchCurve.Backend.Braille.cell()]] for :braille.

@spec render(FrenchCurve.Raster.t(), atom(), keyword()) :: term()

Renders raster with protocol, delegating to that backend's render/2.

protocol must be one of :kitty, :sixel, :iterm2 or :braille; any other atom raises FunctionClauseError from FrenchCurve.Capability.backend/1. opts are the options of the backend selected — see FrenchCurve.Backend.Kitty.render/2, FrenchCurve.Backend.Sixel.render/2, FrenchCurve.Backend.Iterm2.render/2 and FrenchCurve.Backend.Braille.render/2.

Returns a binary for the pixel protocols and cell rows for :braille.

@spec to_terminal(FrenchCurve.Raster.t(), atom(), keyword()) :: binary()

Renders raster with protocol as a binary ready to write to the terminal.

Identical to render/3 except that :braille cell rows are converted to a newline-separated ANSI string. opts are the selected backend's options.