procedural-3d-engine/README.md

# Procedural 3D Engine

A modern Vulkan-based 3D engine featuring procedural shape generation, scene management, and ImGui integration. Built on top of Sascha Willems' Vulkan examples framework with dynamic rendering support and C++20 standards.

## Table of Contents
+ [Features](#features)
+ [Requirements](#requirements)
+ [Building](#building)
+ [Running](#running)
+ [Architecture](#architecture)
+ [Camera System](#camera-system)
+ [Development](#development)
+ [Vulkan Examples](#vulkan-examples)
+ [Credits and Attributions](#credits-and-attributions)

## Features

- **Modern Vulkan Rendering**: Built on Vulkan 1.3+ with dynamic rendering (VK_KHR_dynamic_rendering)
- **Procedural Shape Generation**: Generate and manipulate 3D shapes procedurally
- **Scene Management**: Hierarchical scene graph with object management
- **ImGui Integration**: Real-time UI for parameter adjustment and debugging
- **Advanced Camera System**: Orbit camera with focus functionality (F key)
- **Cross-Platform**: Windows, Linux, and macOS support
- **C++20 Standards**: Modern C++ codebase with latest language features

## Requirements

### Software Dependencies
- **Vulkan SDK** 1.3.0 or higher (required)
- **CMake** 3.10.0 or higher
- **C++20** compatible compiler:
  - Visual Studio 2019/2022 (Windows)
  - GCC 10+ or Clang 13+ (Linux)
  - Xcode 13+ (macOS)

### Hardware Requirements
- Vulkan-compatible GPU
- 2GB+ VRAM recommended
- GPU with dynamic rendering support preferred

## Building

### Quick Build (All Platforms)
```bash
# From project root directory
mkdir build && cd build
cmake .. && cmake --build . --config Release
```

### Platform-Specific Build

#### Windows (Visual Studio)
```bash
mkdir build && cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release
```

#### Linux
```bash
mkdir build && cd build
cmake .. && make -j$(nproc)
```

#### macOS
```bash
mkdir build && cd build
cmake .. && make -j$(sysctl -n hw.ncpu)
```

### Output Location
- **Executable**: `build/bin/Release/ProceduralEngine3D.exe` (Windows) or `build/bin/Release/ProceduralEngine3D` (Unix)
- **Assets**: Automatically copied to output directory

For detailed build instructions, see [BUILD.md](BUILD.md).

## Running

### Basic Usage
```bash
# From build output directory
cd build/bin/Release
./ProceduralEngine3D
```

### Command Line Options
Use `--help` to see all available options:
```bash
./ProceduralEngine3D --help
```

**Common Options:**
- `-v, --validation`: Enable Vulkan validation layers (recommended for development)
- `-w, --width`: Set window width (default: 1920)
- `-h, --height`: Set window height (default: 1080)
- `-f, --fullscreen`: Start in fullscreen mode
- `-g, --gpu`: Select specific GPU device
- `--listgpus`: Display available Vulkan devices

### Controls
- **Mouse**: Look around (standard mode) or orbit (after F key focus)
- **WASD**: Move camera
- **F**: Focus camera on selected object
- **Mouse Wheel**: Zoom (in orbit mode changes distance)
- **ImGui panels**: Adjust parameters and debug information

**Note**: Multi-GPU systems may require using `--listgpus` and `-g` to select a compatible device.

## Architecture

### Core Systems
- **Application Core** (`src/core/Application.cpp`): Main Vulkan application class inheriting from VulkanExampleBase
- **Scene Management** (`src/scene/`): Hierarchical scene graph and object management
- **UI System** (`src/ui/`): ImGui-based interface with real-time parameter adjustment
- **Camera System** (`base/camera.hpp`): Advanced orbit camera with focus functionality
- **Base Framework** (`base/`): Sascha Willems' Vulkan infrastructure

### Vulkan Features
- **Dynamic Rendering**: Uses VK_KHR_dynamic_rendering (no render passes/framebuffers)
- **Modern API Usage**: Vulkan 1.3+ practices with timeline semaphores
- **Multi-platform**: Window system integration for Windows, Linux, macOS
- **Validation Support**: Comprehensive debugging with validation layers

### Project Structure
```
├── src/                    # Engine source code
│   ├── core/              # Core application classes
│   ├── scene/             # Scene management
│   └── ui/                # ImGui interface
├── base/                  # Vulkan base framework
├── shaders/glsl/          # GLSL shader sources
├── assets/                # 3D models and textures
└── build/                 # Build output directory
```

## Camera System

### F Key Focus Feature
The camera system supports advanced focusing functionality:
- **Press F**: Focus camera on selected object
- **Automatic Distance**: Calculates optimal viewing distance
- **Orbit Mode**: Mouse rotation orbits around focused object center
- **Hybrid System**: Combines standard camera with orbit mode using `glm::lookAt()`

### Implementation
- `camera.focusOnObject()`: Sets orbit center and optimal distance
- `camera.updateOrbitPosition()`: Handles spherical coordinate positioning
- Seamless switching between standard and orbit modes

## Development

### Testing Changes
```bash
# Build and test
cd build
cmake --build . --config Release
bin/Release/ProceduralEngine3D -v  # Enable validation layers
```

### Debugging
- Use `-v` flag for Vulkan validation layers
- Check console output for debug information
- Use `--listgpus` to verify device support
- ImGui panels provide real-time debugging information

### Adding Features
- Follow Sascha Willems patterns for Vulkan code
- Use dynamic rendering (no render passes required)
- Implement proper buffer management and synchronization
- Add ImGui panels for new feature parameters

## Vulkan Examples

This engine is built on top of Sascha Willems' comprehensive Vulkan examples. While the main engine focuses on procedural generation and scene management, the original examples remain available for learning Vulkan concepts.

### Available Examples
The `examples/` directory contains over 100 Vulkan examples covering:

- **Basics**: Triangle rendering, pipelines, descriptor sets, textures
- **Advanced Rendering**: Shadow mapping, deferred shading, PBR, ray tracing
- **Compute Shaders**: GPU particles, N-body simulation, image processing
- **Modern Features**: Dynamic rendering, mesh shaders, descriptor buffers
- **Extensions**: Conservative rasterization, variable rate shading, timeline semaphores

### Official Khronos Samples
For the most up-to-date Vulkan learning resources, also check the official Khronos Vulkan Samples repository at: https://github.com/KhronosGroup/Vulkan-Samples

### Building Individual Examples
```bash
# Build specific example (from build directory)
cmake --build . --target triangle --config Release
```

For a complete reference of all available examples with detailed descriptions, see the original Sascha Willems Vulkan repository documentation. Each example demonstrates specific Vulkan concepts and can be built individually using the CMake targets.

## Credits and Attributions
See [CREDITS.md](CREDITS.md) for additional credits and attributions.