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

A frame as a list of pictures placed in pixels, and the raster it draws.

An item is a map:

  * `:picture` — any term naming a picture; `render/4` looks it up
  * `:position` — `{x, y}` in world pixels, where the picture's origin lands
  * `:depth` — greater depth is drawn first, further back; items of equal depth draw
    in list order. Default `0`
  * `:origin`, `:scale`, `:angle`, `:blend`, `:alpha`, `:mode` — as `Cauldron2D.Blend.draw/6`
    takes them

Items hold only terms, so a draw list can be sent to another machine and drawn there
from that machine's own pictures.

    items = [
      %{picture: {:sprite, 4, 0}, position: {120, 88}, origin: {9, 28}, depth: 0},
      %{picture: {:tile, 2, 17}, position: {96, 96}, depth: 100}
    ]

    raster = Cauldron2D.DrawList.render(items, {320, 200}, &MyGame.picture/1,
      view: {40, 0}, background: {20, 20, 40, 255})

A `:picture` scene returns that raster from its function of the pane's size.

# `item`

```elixir
@type item() :: %{
  :picture => term(),
  :position => {number(), number()},
  optional(:depth) => number(),
  optional(:origin) => {number(), number()},
  optional(:scale) => {number(), number()},
  optional(:angle) => number(),
  optional(:blend) => {byte(), byte(), byte()},
  optional(:alpha) => number(),
  optional(:mode) =>
    :over | :add | :subtract | {:gamemaker, :over | :add | :subtract}
}
```

# `extent`

```elixir
@spec extent(map(), {pos_integer(), pos_integer()}) ::
  {float(), float(), float(), float()}
```

`{left, top, right, bottom}`, a rectangle in `item`'s pixels that holds every pixel
its picture, `size` `{width, height}`, can cover, whatever its scale and angle.

# `in_depth_order`

```elixir
@spec in_depth_order([item()]) :: [item()]
```

`items` in the order they are drawn: greatest depth first, ties in list order.

# `render`

```elixir
@spec render(
  [item()],
  {pos_integer(), pos_integer()},
  (term() -> FrenchCurve.Raster.t() | nil),
  keyword()
) :: FrenchCurve.Raster.t()
```

The raster of `items`, `size` `{width, height}` pixels, each item's picture found by
`pictures`, a function from the item's `:picture` to a `FrenchCurve.Raster` or `nil`
(an item whose picture is `nil` is skipped).

Options:

  * `:view` — `{x, y}`, the world pixel at the raster's top-left corner; default `{0, 0}`
  * `:zoom` — raster pixels per world pixel; default `1`
  * `:background` — `{r, g, b, a}` the raster starts as; default transparent
  * `:native`, `:bands` — as `Cauldron2D.Render.render/3` takes them

Items that cannot reach the raster are left out before drawing.

---

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