zanewalker/ASCIIRenderer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: integrate TUI module and apply professional refactoring

Browse Source
This commit is contained in:
Zane Walker
2026-04-16 20:39:48 +00:00
parent 42529be0f8
commit 72e0ef4022
18 changed files with 1340 additions and 2106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
README.md
View File

@@ -1,239 +1,59 @@
# ASCII 3D Renderer v2.0
# ASCII 3D Renderer
An advanced, high-quality ASCII 3D text renderer written in C for fun.
An advanced software-based 3D text renderer pipeline written purely in C11.
## Features
By avoiding proprietary graphics stacks, this engine demonstrates foundational rendering principles—like Z-buffer processing, Phong illumination models, matrices integration, and anti-aliasing sweeps—executing cleanly inside standard POSIX terminal boundaries.
### Rendering
## Architecture & Documentation
- **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
Review [DOCUMENTATION.md](DOCUMENTATION.md) for deeper knowledge of subsystems, technical boundaries, and lighting logic optimizations employed in the source code.
Review [CHANGELOG.md](CHANGELOG.md) for version release tracking constraints.
### Visual Quality
## Technical Feats
- **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
- Real-time `termios`-driven TUI with non-blocking key capture for dynamic typing
- Mathematically robust 3D normal computations leveraging 2D glyph extrusion passes
- Configurable AA (multi-sampling) and shading density metrics per-pixel
- Support for RGB Truecolor processing directly through terminal escape sequences
- Strictly isolated C11 components minimizing external dependencies
### 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
## Rapid Compilation via Makefile
```bash
# Build release version
make
# Deploys standard -O3 and -flto compiler optimizations
make release
# Run with default text
# Run directly, observing standard parameters
./bin/ascii3d
# Run with custom text
./bin/ascii3d HELLO
# Truecolor with all-axis rotation
./bin/ascii3d -a -c3 WORLD
```
### Build Targets
## Interactive TUI Controls
Upon executing, the renderer spins into an active TTY session:
- **Type Alphanumeric Characters** – Immediately replaces the internal 3D model with your input in real-time.
- `[w]` and `[s]` – Increase / decrease rotational velocity.
- `[Space]` – Toggle rotation engine pause constraints.
- `[m]` – Cycles between topology rendering (Wireframe -> Shaded Pipeline -> Solid Geometry -> Points).
- `[c]` – Switch between rendering spaces (Mono Base -> 16/256 ANSI -> Full Truecolor mapping).
- `[p]` – Change ASCII shading dictionaries on the fly.
- `[q]` or `ESC` – Safely detaches the IO hooks and shuts the process down cleanly.
## Execution Options
Command-line invocations to bypass or configure TUI session states:
```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
# Tumbling rotation utilizing Truecolor ANSI standards
./bin/ascii3d -a -c3 WORLD
# Fast wireframe mode
./bin/ascii3d -m1 -s2 WIRE
# High quality with anti-aliasing
# Quality override with heavy Anti-Aliasing pipeline
./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
# Show full parameter dictionary
./bin/ascii3d -h
```
Press `Ctrl+C` to exit.
## Contributing
## 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
The codebase attempts strict functional modularity. We accept modifications introducing new geometry patterns, deeper PBR emulation methods, or expanded rendering logic assuming complete dependency evasion.