# `ExRatatui.Widgets.Viewport3D`
[🔗](https://github.com/mcass19/ex_ratatui/blob/v0.13.0/lib/ex_ratatui/widgets/viewport3d.ex#L1)

A 3D viewport widget that renders a scene with software rasterization or ray
tracing, as true pixel graphics or blitted into terminal cells.

The widget is pure data: the scene and camera are rebuilt and rendered every
frame, so it works over every transport. Drive animation and camera movement
from application state between frames (see `ExRatatui.ThreeD.Camera`).

A true-color terminal is required, since every mode emits 24-bit colors.

## Fields

  * `:scene` - an `ExRatatui.ThreeD.Scene`
  * `:camera` - an `ExRatatui.ThreeD.Camera`
  * `:render_mode` - a pixel-graphics protocol (`:auto`, the default; `:kitty`;
    `:sixel`; `:iterm2`) or a cell-blit mode (`:half_block`, `:braille`, `:ascii`)
  * `:pipeline` - `:rasterize` (default) or `:raytrace`
  * `:block` - optional `ExRatatui.Widgets.Block` container (borders, title)

## Render modes

Pixel-graphics modes render the scene as an image at native terminal resolution
(crisp, non-blocky) on capable terminals, and fall back to `:braille` where no
graphics protocol is available (CellSession/Livebook, SSH/distributed without
passthrough, unsupported terminals):

  * `:auto` - the best protocol the terminal supports, else braille (default)
  * `:kitty` - Kitty graphics protocol (Ghostty, WezTerm, Kitty)
  * `:sixel` - Sixel graphics
  * `:iterm2` - iTerm2 inline images

Cell-blit modes pack the render into character cells (always available):

  * `:half_block` - one `▀` per cell, fg/bg are the upper/lower pixel
  * `:braille` - supersampled `▀` for anti-aliased edges
  * `:ascii` - a shaded ASCII ramp with colored characters

## Examples

    iex> alias ExRatatui.Widgets.Viewport3D
    iex> alias ExRatatui.ThreeD.{Scene, Object, Light, Mesh}
    iex> %Viewport3D{
    ...>   scene: %Scene{
    ...>     objects: [%Object{mesh: Mesh.cube()}],
    ...>     lights: [Light.directional({-1.0, -1.0, -1.0}, {255, 255, 255})]
    ...>   },
    ...>   render_mode: :ascii
    ...> }.render_mode
    :ascii

    iex> %ExRatatui.Widgets.Viewport3D{}.render_mode
    :auto

    iex> %ExRatatui.Widgets.Viewport3D{}.pipeline
    :rasterize

# `pipeline`

```elixir
@type pipeline() :: :rasterize | :raytrace
```

# `render_mode`

```elixir
@type render_mode() ::
  :auto | :kitty | :sixel | :iterm2 | :half_block | :braille | :ascii
```

# `t`

```elixir
@type t() :: %ExRatatui.Widgets.Viewport3D{
  block: ExRatatui.Widgets.Block.t() | nil,
  camera: ExRatatui.ThreeD.Camera.t(),
  pipeline: pipeline(),
  render_mode: render_mode(),
  scene: ExRatatui.ThreeD.Scene.t()
}
```

---

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