# `Cauldron2D.Parallax`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_2d/lib/cauldron_2d/parallax.ex#L1)

A background of several depths, each read at its own share of the camera's motion.

    layers = [
      Cauldron2D.Parallax.layer(name: :sky, cell: sky, factor: 0.0, void: :opaque),
      Cauldron2D.Parallax.layer(name: :hills, cell: hills, factor: {0.2, 0.05}),
      Cauldron2D.Parallax.layer(name: :trees, cell: trees, factor: {0.6, 0.2}),
      Cauldron2D.Parallax.layer(name: :grass, cell: grass, factor: {1.4, 1.0}, front: true)
    ]

    behind = Cauldron2D.Parallax.compose(:atlas, layers, focus: focus, size: {40, 24}, at: now)
    Cauldron2D.Surface.compose(:atlas, cells, movers, under: behind, void: :transparent)

`compose/3` draws the layers of one side into one raster the size of the pane, back to
front in list order: the layers behind the world by default, those with `front: true`
when given `front: true`. The backmost layer wants `void: :opaque` so the picture has a
background; every other layer wants `:transparent`.

A layer's picture is kept while the camera stays within one of that layer's tiles. A
layer whose movers move must be built with `cache: false`.

A layer's movers are `Cauldron2D.Surface` movers in the layer's own tiles —
`{art, {x, y}}` or `{art, {x, y}, tint}`.

# `bands`

```elixir
@spec bands([{Range.t(), number()}]) :: Cauldron2D.Parallax.Bands.t()
```

Bands of rows with their own factors, as `Bands.new/1` builds them.

# `compose`

```elixir
@spec compose(
  Cauldron2D.Atlas.name() | Cauldron2D.Atlas.t(),
  [Cauldron2D.Parallax.Layer.t()],
  keyword()
) :: FrenchCurve.Raster.t() | nil
```

The layers of one side composed into one raster, or `nil` where that side has none.

## Options

  * `:focus` — the world point the camera is on, required
  * `:size` — `{columns, rows}` of the pane in whole tiles, required
  * `:at` — the time in milliseconds, for animation and drift. Default `0`
  * `:scale` — a positive integer dividing the tile size, as
    `Cauldron2D.Surface.compose/4` takes. Default `1`
  * `:pixels` — the result's exact size in pixels, for a caller that has one already and
    needs the picture to match it. Default `:size` times the tile
  * `:front` — `true` for the layers over the world, `false` for those behind it.
    Default `false`

# `forget`

```elixir
@spec forget(Cauldron2D.Atlas.name()) :: :ok
```

Forget every kept layer picture of `atlas`.

# `layer`

```elixir
@spec layer(keyword()) :: Cauldron2D.Parallax.Layer.t()
```

A layer, as `Cauldron2D.Parallax.Layer.new/1` builds it.

# `legend`

```elixir
@spec legend([String.t()], map()) :: [[term()]]
```

Rows of cells from rows of characters, as `Strip.legend/2` builds them.

# `panorama`

```elixir
@spec panorama(keyword()) :: Cauldron2D.Parallax.Layer.t()
```

A layer that is one picture repeated, as `Panorama.layer/1` builds it.

# `scatter`

```elixir
@spec scatter(keyword()) :: ({integer(), integer()} -> term())
```

A cell function placing art by hashing the coordinate, as `Scatter.cells/1` builds it.

# `strip`

```elixir
@spec strip([[term()]], keyword()) :: ({integer(), integer()} -> term())
```

A cell function over authored tiles, as `Strip.cells/2` builds it.

# `view`

```elixir
@spec view(Cauldron2D.Parallax.Layer.t(), keyword()) :: Cauldron2D.Camera.t()
```

The camera for one layer: its own origin, its own cells and its own sub-tile scroll.

## Options

  * `:focus` — the world point the camera is on, required
  * `:size` — `{columns, rows}` of the pane in tiles, required
  * `:at` — the time in milliseconds. Default `0`

---

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