240 lines
6.3 KiB
Markdown
240 lines
6.3 KiB
Markdown
# 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
|