# `Cauldron3D.Bsp.Light`
[🔗](https://github.com/jaman/cauldron/blob/v0.2.2/cauldron_3d/lib/cauldron_3d/bsp/light.ex#L1)

How brightly a world is lit at a point: the lightmap of the nearest upward-facing
solid face directly below it, within `:reach` units, each light style at its scale.
Models standing at the point are lit by it.

    Cauldron3D.Bsp.Light.at(bsp, origin, styles)
    #=> {r, g, b}

`styles` is a tuple or map from style number to scale, 256 normal. The result is per
channel, 0 and up (a world with grey lightmaps gives three equal values); `nil` when
no face is below.

`point/4` finds the light the way the world's own tree finds it: down from the point
through the nodes to the first node whose plane the line crosses with a lit face under
the crossing.

# `at`

```elixir
@spec at(Cauldron3D.Bsp.t(), Cauldron3D.Vec.t(), tuple() | map(), keyword()) ::
  {number(), number(), number()} | nil
```

The light at `point`. Options: `:reach`, how far below to look, default 2048.

# `on_face`

```elixir
@spec on_face(
  Cauldron3D.Bsp.t(),
  Cauldron3D.Bsp.Face.t(),
  Cauldron3D.Vec.t(),
  tuple() | map()
) ::
  {number(), number(), number()}
```

The light of `face`'s lightmap at `point` on it, each style at its scale; black for an unlit face.

# `point`

```elixir
@spec point(Cauldron3D.Bsp.t(), Cauldron3D.Vec.t(), map(), keyword()) ::
  {Cauldron3D.Vec.t(), Cauldron3D.Vec.t()}
```

The light at `point` and the direction it comes from, `{{r, g, b}, direction}`, found
along the line from `point` straight down `:distance` units (default 8192): walking
the world's nodes front side first, the first node whose plane the line crosses whose
faces include one, not sky or liquid, whose texture area holds the crossing point.
Its lightmap sample there, each style's sample times the style's scale over 255 and
its colour, is the light, from `{1, 0, 1}` (of length one); a face with no lightmap
gives black from `{0, 1, -1}`, and no face at all black from `{0, 1, 1}`.

`styles` maps a style number to its scale (256 normal) or to `{scale, {r, g, b}}`; a
style not in it is 256 and white.

---

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