(Feat): Initial Commit.
This commit is contained in:
239
README.md
Normal file
239
README.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user