# `Cauldron2D.Sectors.Pictures`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_2d/lib/cauldron_2d/sectors/pictures.ex#L1)

The pictures a sector view draws from — wall textures, floor textures, sprites — and the
light tables that darken them, held ready for `Cauldron2D.Sectors.Frame`.

    pictures =
      Cauldron2D.Sectors.Pictures.new(
        [{"STARTAN3", %{width: 128, height: 128, pixels: columns, mask: nil}}, ...],
        Cauldron2D.Sectors.Light.tables(palette)
      )

    Cauldron2D.Sectors.Pictures.id(pictures, "STARTAN3")

A picture is indexed colour stored **column by column**: `pixels` holds `height` bytes
for column 0, then column 1, and so on, `width * height` bytes in all. `mask` is `nil`
for a picture with no holes, or as many bytes as `pixels` with `0` where the picture is
transparent. Every picture is addressed by its position in the list given to `new/2`,
which `id/2` looks up by name.

`tables` is the light tables: 256 bytes each, a colour index in, the colour to draw out.
Table `0` draws a picture as it is. How many there are and what each does is the
caller's; `Cauldron2D.Sectors.Light` builds a ramp from a palette.

Where the NIF loaded, the pictures are copied into it once, and a set may be shared
between processes and drawn from by any number of frames.

# `picture`

```elixir
@type picture() :: %{
  :width => pos_integer(),
  :height => pos_integer(),
  :pixels => binary(),
  optional(:mask) => binary() | nil
}
```

# `t`

```elixir
@type t() :: %Cauldron2D.Sectors.Pictures{
  maps: pos_integer(),
  names: %{required(term()) => non_neg_integer()},
  native: reference() | nil,
  pictures: tuple() | nil,
  sizes: tuple(),
  tables: binary()
}
```

# `count`

```elixir
@spec count(t()) :: non_neg_integer()
```

How many pictures the set holds.

# `from_rows`

```elixir
@spec from_rows(pos_integer(), pos_integer(), binary(), binary() | nil) :: picture()
```

A picture from rows: `rows` is `width * height` bytes, row by row, as most images are
stored; `mask_rows` likewise or `nil`. Gives the column-by-column picture `new/2` takes.

# `id`

```elixir
@spec id(t(), term()) :: non_neg_integer() | nil
```

The id of the picture called `name`, or `nil`.

# `new`

```elixir
@spec new([{term(), picture()}], binary(), keyword()) :: t()
```

A set of `named` pictures, `[{name, picture}]`, with the light `tables`.

`native: false` keeps them in Elixir even where the NIF loaded. Raises `ArgumentError`
for a picture whose bytes do not match its size, or tables that are not whole tables.

# `size`

```elixir
@spec size(t(), non_neg_integer()) :: {pos_integer(), pos_integer()}
```

The `{width, height}` of picture `id`.

---

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