# ASCII 3D Renderer v2.0

An advanced, high-quality ASCII 3D text renderer written in C for fun.

## Features

### Rendering

- **Phong Lighting Model** - Realistic lighting with ambient, diffuse, and specular components
- **Multiple Light Sources** - Key light, fill light, and rim light for professional 3-point lighting
- **Smooth Normals** - Averaged surface normals for smoother shading on edges
- **Multiple Render Modes** - Solid, wireframe, points, and full shaded rendering
- **Anti-Aliasing** - Optional sub-pixel sampling for smoother output

### Visual Quality

- **Extended ASCII Palettes** - 70-level gradient for detailed shading
- **Block Characters** - Unicode block shading option (░▒▓█)
- **ANSI Color Support** - 16-color, 256-color, and 24-bit truecolor modes
- **Configurable Quality** - Adjustable voxel density for performance/quality tradeoff

### Technical

- **Pure C11** - No external graphics dependencies
- **60 FPS** - Smooth real-time animation
- **Depth Buffering** - Proper 3D occlusion
- **Modular Architecture** - Clean separation of concerns
- **Production-Ready** - Strict compiler warnings, proper error handling

## Supported Characters

- Uppercase letters: `A-Z`
- Lowercase letters: `a-z` (rendered as uppercase)
- Digits: `0-9`

## Building

### Requirements

- Clang or GCC (C11 support)
- GNU Make
- POSIX-compliant system (Linux, macOS, WSL)

### Quick Start

```bash
# Build release version
make

# Run with default text
./bin/ascii3d

# Run with custom text
./bin/ascii3d HELLO

# Truecolor with all-axis rotation
./bin/ascii3d -a -c3 WORLD
```

### Build Targets

```bash
make release   # Optimized build (default)
make debug     # Debug build with sanitizers
make profile   # Build with profiling support
make clean     # Remove build artifacts
make install   # Install to /usr/local/bin
make help      # Show all targets
```

## Usage

```bash
ascii3d [OPTIONS] [TEXT]

ROTATION OPTIONS:
  -s <speed>    Rotation speed multiplier (default: 1.0)
  -x            Enable X-axis rotation
  -y            Enable Y-axis rotation (default)
  -z            Enable Z-axis rotation
  -a            Enable all axis rotations

RENDER MODE OPTIONS:
  -m <mode>     Render mode:
                  0 = Solid (filled)
                  1 = Wireframe (edges only)
                  2 = Points (sparse)
                  3 = Shaded (full Phong lighting) [default]

COLOR OPTIONS:
  -c <mode>     Color mode:
                  0 = Monochrome ASCII [default]
                  1 = 16-color ANSI
                  2 = 256-color ANSI
                  3 = Truecolor (24-bit RGB)

QUALITY OPTIONS:
  -q <quality>  Render quality (0.5 - 2.0, default: 1.0)
  -A            Enable anti-aliasing
  -p <palette>  Shading palette:
                  0 = Standard (10 levels)
                  1 = Extended (70 levels) [default]
                  2 = Block characters
                  3 = Minimal (6 levels)

OTHER OPTIONS:
  -f            Show FPS counter
  -h            Show help message
```

### Examples

```bash
# Simple Y-axis rotation (default)
./bin/ascii3d HELLO

# Tumbling rotation with truecolor
./bin/ascii3d -a -c3 WORLD

# Fast wireframe mode
./bin/ascii3d -m1 -s2 WIRE

# High quality with anti-aliasing
./bin/ascii3d -A -q1.5 -c2 HQ

# Block character style
./bin/ascii3d -p2 BLOCKS

# Show FPS counter
./bin/ascii3d -f -a TEST

# Slow, high quality render
./bin/ascii3d -s0.3 -q2 -A SMOOTH
```

Press `Ctrl+C` to exit.

## Project Structure

```bash
ASCIIRenderer/
├── include/
│   ├── config.h      # Configuration and constants
│   ├── vec3.h        # 3D vector mathematics
│   ├── font.h        # Bitmap font interface
│   ├── lighting.h    # Phong lighting system
│   ├── renderer.h    # Core rendering engine
│   └── timing.h      # High-precision timing
├── src/
│   ├── vec3.c        # Vector operations
│   ├── font.c        # 5x7 bitmap font data
│   ├── lighting.c    # Lighting calculations
│   ├── renderer.c    # Advanced rendering
│   ├── timing.c      # Timing utilities
│   └── main.c        # Entry point and CLI
├── Makefile          # Build system (Clang)
└── README.md         # This file
```

## How It Works

### Rendering Pipeline

1. **Font Lookup** - Characters are defined as 5x7 bitmap glyphs
2. **3D Extrusion** - Each pixel is extruded along Z-axis to create depth
3. **Surface Detection** - Only surface voxels are rendered (optimization)
4. **Normal Calculation** - Smooth normals computed from adjacent faces
5. **Rotation** - 3D rotation matrices transform points and normals
6. **Projection** - Perspective projection maps 3D to 2D screen space
7. **Lighting** - Phong model calculates illumination per voxel
8. **Depth Test** - Z-buffer ensures correct occlusion
9. **Shading** - Intensity mapped to ASCII character from palette
10. **Color** - Optional ANSI escape codes for colored output

### Lighting Model

The renderer uses a 3-point lighting setup:

- **Key Light** - Main light from upper-right-front (warm white)
- **Fill Light** - Softer light from left (cool blue tint)
- **Rim Light** - Back light for edge definition

Phong components:

- **Ambient** - Base illumination (15%)
- **Diffuse** - Lambertian reflection (70%)
- **Specular** - Blinn-Phong highlights (40%, shininess 32)

### ASCII Shading Palettes

**Standard (10 levels):**

```bash
 .:-=+*#%@
```

**Extended (70 levels):**

```bash
 .'`^",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$
```

**Block (5 levels):**

```bash
 ░▒▓█
```

## Configuration

Edit `include/config.h` to customize:

```c
/* Screen dimensions */
#define SCREEN_WIDTH        120
#define SCREEN_HEIGHT       45

/* Rendering quality */
#define EXTRUSION_DEPTH     4.0f    // 3D depth of characters
#define CHAR_SCALE          2.0f    // Character size
#define VOXEL_STEP          0.15f   // Voxel density (smaller = higher quality)

/* Lighting */
#define AMBIENT_INTENSITY   0.15f
#define DIFFUSE_INTENSITY   0.70f
#define SPECULAR_INTENSITY  0.40f
#define SPECULAR_POWER      32.0f

/* Animation */
#define TARGET_FPS          60
```

## Performance

- **60 FPS** on modern hardware
- **Surface-only rendering** - Interior voxels skipped
- **Efficient depth buffer** - Single-pass rendering
- **Minimal memory** - Static buffers, no dynamic allocation
- **Quality scaling** - `-q` option for performance tuning