70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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
|
||
``` |