ASCIIRenderer/README.md

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

# 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

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

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

# 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

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):

 .:-=+*#%@

Extended (70 levels):

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

Block (5 levels):

 ░▒▓█

Configuration

Edit include/config.h to customize:

/* 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