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
• Requirements
• Building
• Running
• Architecture
• Camera System
• Development
• Vulkan Examples
• 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)

# From project root directory
mkdir build && cd build
cmake .. && cmake --build . --config Release

Platform-Specific Build

Windows (Visual Studio)

mkdir build && cd build
cmake .. -G "Visual Studio 16 2019" -A x64
cmake --build . --config Release

Linux

mkdir build && cd build
cmake .. && make -j$(nproc)

macOS

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.

Running

Basic Usage

# From build output directory
cd build/bin/Release
./ProceduralEngine3D

Command Line Options

Use --help to see all available options:

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

# 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

# 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 for additional credits and attributions.