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

Fitting a frame of a fixed shape into a picture of another, with bars on the sides or
above and below.

A `:picture` scene that names its `:frame` — the shape the game's screen is shown at,
`{320, 240}` for a 320×200 VGA screen shown 4:3 — draws its screen into the rectangle
`letterbox/3` gives, and the surface maps the pointer into that same rectangle, so a
game reads the pointer as a point of its own screen.

    Cauldron2D.Fit.letterbox({400, 200}, 1.0, {320, 240})
    #=> {66, 0, 267, 200}

# `letterbox`

```elixir
@spec letterbox({pos_integer(), pos_integer()}, number(), {number(), number()}) ::
  {non_neg_integer(), non_neg_integer(), pos_integer(), pos_integer()}
```

The rectangle `{x, y, width, height}` of a `{width, height}` picture, whose pixels are
`aspect` times as tall as they are wide, that shows a frame of shape `frame` as large
as it fits, centred.

# `within`

```elixir
@spec within(
  {number(), number()},
  {pos_integer(), pos_integer()},
  number(),
  {number(), number()}
) ::
  {float(), float()} | nil
```

The point of the frame under picture fraction `{fx, fy}` (as a `:picture` surface
reports the pointer), as fractions of the letterboxed frame, or `nil` outside it.

---

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