# ASCII 3D Renderer

A 3D text rendering engine that runs entirely in your terminal, written in C. Type any word and watch it spin in 3D with proper lighting, shading, and depth — all drawn with ASCII characters.

No OpenGL, no GPU, no graphics libraries. Just math, a framebuffer made of characters, and ANSI escape codes.

## What it does

You give it a string like `HELLO`, and it renders each letter as a 3D object by extruding a built-in 5×7 bitmap font along the Z-axis. A Blinn-Phong lighting model (with a 3-point light setup — key, fill, and rim) calculates the brightness at each surface point, which then gets mapped to an ASCII character from a density palette like `.:-=+*#%@`.

The whole thing runs as an interactive TUI. You can type new text on the fly, change render modes, toggle color output, adjust rotation speed — all without restarting.

## Docs

- [DOCUMENTATION.md](DOCUMENTATION.md) — how the rendering pipeline works, module breakdown, and how things fit together.
- [CHANGELOG.md](CHANGELOG.md) — version history.

## Features

- Interactive TUI with non-blocking input via `termios` — no need to restart to change text or settings
- 3D normal estimation from 2D glyph bitmaps using neighbor-vacancy checks
- Multiple render modes: solid, wireframe, points, and shaded
- Anti-aliasing via multi-sample jittered rays
- Color output: monochrome, 16-color ANSI, 256-color ANSI, or full RGB truecolor
- Four different ASCII shade palettes (standard, extended 70-char, block characters, minimal)
- 60 FPS target with frame timing via `CLOCK_MONOTONIC` and `nanosleep`

## Building

You need `clang` and `make`. The only library dependency is `libm` (math).

```bash
# optimized build with -O3 and LTO
make release

# debug build with AddressSanitizer and UBSan
make debug

# run it
./bin/ascii3d
```

There's also `make profile` for gprof, `make analyze` for cppcheck, and `make format` for clang-format.

## Controls

Once it's running, you're in an interactive session:

| Key | What it does |
|-----|-------------|
| Any letter/number | Changes the displayed 3D text in real-time |
| `w` / `s` | Speed up / slow down rotation |
| `Space` | Pause or resume rotation |
| `m` | Cycle render mode (Solid → Wireframe → Points → Shaded) |
| `c` | Cycle color mode (Mono → ANSI 16 → ANSI 256 → Truecolor) |
| `p` | Cycle ASCII shade palette |
| `q` or `ESC` | Quit cleanly |

## Command-line examples

```bash
# Rotate on all axes, truecolor mode
./bin/ascii3d -a -c3 WORLD

# Anti-aliasing on, 1.5x oversampling, 256-color mode
./bin/ascii3d -A -q1.5 -c2 HQ

# Show all options
./bin/ascii3d -h
```