# `Cauldron3D.Camera`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_3d/lib/cauldron_3d/camera.ex#L1)

Where a picture is taken from: a position, a facing, and a projection.

The world is right-handed with `z` up. `yaw` turns about `z`, 0 facing `+x` and
`:math.pi() / 2` facing `+y`; `pitch` above zero looks up; `roll` above zero tips the
picture clockwise. A `:perspective` camera sees `fov` radians across; an
`:orthographic` one sees `extent` world units across, the same at every distance.

    Cauldron3D.Camera.first_person({0.0, 0.0, 56.0}, yaw, pitch)
    Cauldron3D.Camera.follow(target, yaw, distance: 120.0, height: 40.0)
    Cauldron3D.Camera.side(target, extent: 640.0)
    Cauldron3D.Camera.top_down(target, extent: 1024.0)

# `projection`

```elixir
@type projection() :: :perspective | :orthographic
```

# `t`

```elixir
@type t() :: %Cauldron3D.Camera{
  extent: float(),
  fov: float(),
  near: float(),
  pitch: float(),
  position: Cauldron3D.Vec.t(),
  projection: projection(),
  roll: float(),
  yaw: float()
}
```

# `basis`

```elixir
@spec basis(t()) :: {Cauldron3D.Vec.t(), Cauldron3D.Vec.t(), Cauldron3D.Vec.t()}
```

The camera's axes in the world: `{forward, right, up}`, each of length one.

# `first_person`

```elixir
@spec first_person(Cauldron3D.Vec.t(), number(), number(), keyword()) :: t()
```

A perspective camera at `position` looking along `yaw` and `pitch`. Takes `new/1`'s options.

# `follow`

```elixir
@spec follow(Cauldron3D.Vec.t(), number(), keyword()) :: t()
```

A perspective camera behind `target`, facing along `yaw` and looking down at it.

## Options

  * `:distance` — how far behind, default 128.0
  * `:height` — how far above the target the camera sits, default 48.0
  * `:look_height` — the height above the target the camera aims at, default 0.0
  * anything `new/1` takes

# `forward`

```elixir
@spec forward(number(), number()) :: Cauldron3D.Vec.t()
```

The direction `yaw` and `pitch` face, of length one.

# `new`

```elixir
@spec new(keyword()) :: t()
```

A camera from options: `:position`, `:yaw`, `:pitch`, `:roll`, `:projection`, `:fov`,
`:extent` and `:near`, each defaulting as the struct does.

# `side`

```elixir
@spec side(Cauldron3D.Vec.t(), keyword()) :: t()
```

An orthographic camera looking across the world at `target` from the `-y` side, as a
side-scroller sees it. `:extent` (default 512.0) is how wide the view is; `:distance`
(default 4096.0) how far back it stands.

# `top_down`

```elixir
@spec top_down(Cauldron3D.Vec.t(), keyword()) :: t()
```

An orthographic camera looking straight down at `target`, `+y` at the top of the
picture. `:extent` (default 512.0) is how wide the view is; `:distance` (default
4096.0) how high it hangs.

---

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