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

Light as table lookups: a ramp of light tables built from a palette, and which table a
surface at some light level and distance is drawn through.

    tables = Light.tables(palette)
    Light.table(160, 384.0)

A light table maps a colour index to the index of that colour darkened, so lighting a
picture costs one lookup a pixel whatever the light. `tables/2` builds `maps` of them,
table `0` the palette as it is and each further table darker, the last nearly black.
A game may instead bring its own tables made for its palette.

A surface's light level is `0..255`. `start/2` turns it into the table it is drawn
through close up, and `table/3` moves that table brighter or darker with distance:
`start - floor(fade / distance)`, clamped to the tables, so nearer is brighter and a
surface fades by its light level's own amount as it recedes.

## Options

  * `:maps` — how many tables the ramp has. Default `32`
  * `:levels` — how many steps the `0..255` light level is cut into. Default `16`
  * `:fade` — how strongly distance darkens, in world units. Default `1280.0`

# `option`

```elixir
@type option() ::
  {:maps, pos_integer()} | {:levels, pos_integer()} | {:fade, number()}
```

# `start`

```elixir
@spec start(integer(), [option()]) :: integer()
```

The table a surface at `light` (`0..255`) is drawn through close up.

# `table`

```elixir
@spec table(integer(), number(), [option()]) :: non_neg_integer()
```

The table a surface at `light` is drawn through from `distance` away.

# `tables`

```elixir
@spec tables(binary(), [option()]) :: binary()
```

`maps` light tables for a 768-byte `palette`, darkening towards black: table `n` holds
for each colour the palette entry nearest that colour scaled by `(maps - n) / maps`.

---

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