Fidelity Engine

Fidelity is a modern real-time 3D rendering engine built with OpenGL 4.1 and C++17, designed for Windows and macOS platforms. The engine implements state-of-the-art graphics rendering techniques through a modular, component-based architecture optimized for learning and experimentation with advanced rendering algorithms.

The project focuses on providing an accessible yet powerful framework for implementing cutting-edge graphics techniques, making it ideal for educational purposes, research, and prototype development.

Current Status: Under active development - expect ongoing improvements and occasional breaking changes.

Features

Rendering Pipeline

• Physically Based Deferred Rendering: Modern PBR implementation with metallic-roughness workflow
• Advanced Shadow System:
  • Cascaded Shadow Maps: High-quality directional light shadows with 4 cascade levels
  • Enhanced Point Light Shadows: Omnidirectional shadow mapping with contact hardening, temporal stability, and performance optimizations
  • Unified Shadow Quality: Both directional and point lights feature advanced soft shadows with Poisson disc sampling, early termination PCF, and sophisticated bias calculation
• Screen Space Ambient Occlusion (SSAO): Enhanced depth-based ambient occlusion
• HDR Rendering: High Dynamic Range rendering with exposure control
• Physically Based Bloom: Energy-conserving bloom effect for HDR content
• Tone Mapping: Multiple tone mapping operators for HDR-to-LDR conversion

Scene Management

• Hierarchical Scene Graph: Efficient spatial organization with transform inheritance
• Frustum Culling: Optimized view frustum culling for performance
• Component-Based Architecture: Flexible game object composition system
• Resource Management: Efficient asset loading and memory management

Development Tools

• Real-time Editor UI: ImGui-based interface for debugging and parameter tuning
• Performance Profiling: Built-in timing and statistics collection
• Shader Hot-Reloading: Development-time shader recompilation support
• Multiple Test Applications: Comprehensive testing and demonstration scenarios

Supported Platforms

• Windows: Primary development platform with Visual Studio support
• macOS: Cross-platform compatibility with Xcode support
• Linux: Experimental support (community contributions welcome)

Screenshots

Building

Prerequisites

• CMake 3.21 or higher - Download from cmake.org
• Visual Studio 2019 or later (on Windows) with C++ development tools
• Git for cloning the repository and submodules

Clone with Submodules

git clone --recursive https://github.com/your-username/Fidelity.git
cd Fidelity

If you already cloned without --recursive, initialize submodules:

git submodule update --init --recursive

Windows Build Instructions

Option 1: Using the Build Script (Recommended)

The easiest way to build on Windows is using the provided PowerShell script:

# From the project root directory
.\build-windows.ps1

This script will:

• Create a build/release directory
• Configure CMake with Release settings
• Build all targets
• Copy resources to the output directory

Option 2: Manual CMake Build

If you prefer to build manually or need custom configuration:

# Create and enter build directory
mkdir build\release
cd build\release

# Configure with CMake
cmake -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release ..\..

# Build the project
cmake --build . --config Release

# Copy resources (optional, for running examples)
cmake --build . --target copy_resources --config Release

Build Options

The CMake build system supports several configuration options:

• FIDELITY_ENABLE_WARNINGS (Default: ON) - Enable comprehensive compiler warnings
• FIDELITY_BUILD_TESTS (Default: ON) - Build unit test executables
• CMAKE_BUILD_TYPE - Build configuration: Debug, Release, RelWithDebInfo, MinSizeRel

Example with custom options:

cmake -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug -DFIDELITY_ENABLE_WARNINGS=OFF ..\..

Application Targets

After building, you'll find several executable applications in the build/release/bin/Release/ directory:

• Test3D (build/release/bin/Release/Test3D.exe)
  Basic 3D rendering test with primitive shapes and basic lighting

• Sponza (build/release/bin/Release/Sponza.exe)
  Comprehensive scene demonstration featuring the classic Sponza atrium with full PBR pipeline

• CullingTest (build/release/bin/Release/CullingTest.exe)
  Frustum culling performance demonstration with large numbers of objects

• Tests (build/release/bin/Release/Tests.exe)
  Comprehensive unit test suite for engine mathematics and core systems

All applications include the editor UI for real-time parameter adjustment and debugging.

Running the Applications

You can run the applications from the project root directory:

# Run the Sponza demo (most comprehensive)
.\build\release\bin\Release\Sponza.exe

# Run the basic 3D test
.\build\release\bin\Release\Test3D.exe

# Run the culling performance test
.\build\release\bin\Release\CullingTest.exe

# Run the unit tests
.\build\release\bin\Release\Tests.exe

Or navigate to the executable directory and run them directly:

cd build\release\bin\Release
.\Sponza.exe

Note: All required resources (shaders, textures, models, fonts) are automatically copied to the executable directory during the build process, so the applications will find all necessary assets regardless of how they are launched.

Troubleshooting

Common Issues and Solutions:

• CMake version error: Ensure CMake 3.21+ is installed and in PATH
• Missing submodules: Run git submodule update --init --recursive
• Visual Studio not found: Install Visual Studio 2019+ with "C++ CMake tools" workload
• OpenGL errors: Update graphics drivers; ensure OpenGL 4.1+ support
• Build errors: Try a clean build by deleting build/ directory and rebuilding
• Runtime crashes: Verify all resources are copied; check console for OpenGL errors
• Poor performance: Ensure Release build; check GPU compatibility

Debug Build Performance: Debug builds include extensive validation and may run significantly slower than Release builds.

Development Roadmap

Completed Features ✅

• Core Rendering Pipeline: Deferred rendering with G-buffer
• Physically Based Rendering: Full PBR material system
• Advanced Shadow System:
  • Cascaded Shadow Maps: High-quality directional light shadows with contact hardening
  • Enhanced Point Light Shadows: Omnidirectional shadow mapping with contact hardening, temporal stability, early termination PCF, and advanced bias calculation
  • Unified Shadow Quality: Feature parity between directional and point light shadows
• Post-Processing: SSAO, HDR bloom, tone mapping
• Scene Management: Component-based architecture with scene graph
• Resource Loading: Model, texture, and shader loading systems

In Progress 🚧

• Octree Spatial Partitioning: Improved culling and spatial queries
• Image Based Lighting: Environment mapping and reflection probes

Future Enhancements 🎯

• Advanced Lighting: Clustered forward rendering for many lights
• Post-Processing Effects: Screen-space reflections, motion blur, depth of field
• Anti-Aliasing: FXAA, TAA, and MSAA support
• Volumetric Effects: Fog, god rays, and atmospheric scattering
• Animation System: Skeletal animation and morphing
• Audio Integration: 3D positional audio system
• Physics Integration: Collision detection and rigid body dynamics
• Scripting Support: Lua or C# scripting interface
• Platform Expansion: Linux native support, mobile platforms

Performance Optimizations 🚀

• GPU-Driven Rendering: Indirect draw calls and GPU culling
• Level-of-Detail: Automatic LOD generation and management
• Texture Streaming: Dynamic texture loading and compression
• Multi-threading: Parallel command buffer generation

Architecture Overview

Fidelity Engine follows a modular, component-based architecture designed for extensibility and maintainability. The engine is structured around several key subsystems:

Core Architecture Components

Application Layer: The main application framework handles window management, input processing, and the primary game loop.

Scene Management: A hierarchical scene graph system manages game objects, transforms, and spatial relationships.

Rendering Pipeline: A deferred rendering pipeline optimized for physically-based rendering (PBR) with multiple render passes.

Resource Management: Efficient loading and management of textures, models, shaders, and other assets.

Mathematics Library: Custom mathematics implementation for 3D graphics operations.

Rendering Pipeline

The engine implements a modern deferred rendering pipeline with the following stages:

1. Geometry Pass: Renders scene geometry to G-buffer
2. Shadow Pass: Generates cascaded shadow maps for directional lights and omnidirectional cubemap arrays for point lights
3. Lighting Pass: Performs physically-based lighting calculations with shadow sampling
4. Post-Processing: Applies SSAO, bloom, tone mapping, and other effects
5. Forward Pass: Handles transparent objects and UI elements

Key Directories Explained

Source/Engine/: The heart of the engine, organized by functional domains:

• Core: Fundamental engine systems and object lifecycle management
• Rendering: High-level rendering abstractions and pipeline management
• RenderApi: Low-level graphics API abstraction layer
• Maths: Custom mathematics library optimized for graphics operations

Resources/: All engine assets organized by type:

• Shaders: GLSL shaders implementing the rendering pipeline
• Models: 3D assets for testing and demonstration
• Textures: Image assets including PBR material textures

Externals/: Carefully selected third-party libraries:

• assimp: Robust model loading supporting 40+ formats
• glad: Modern OpenGL loader with extensions support
• glfw: Cross-platform window and input management
• glm: Header-only mathematics library for graphics

Documentation

Technical Documentation

The Documentation/ folder contains comprehensive technical analysis and architectural guides for the engine's core systems:

• Shadow Mapping Analysis: Complete breakdown of the cascaded shadow mapping implementation, including performance optimizations, contact hardening, and quality analysis
• Point Light Shadows Analysis: Comprehensive guide to omnidirectional point light shadow mapping using TextureCubeArray, including multi-light support, soft shadow filtering, and performance optimization
• Point Light Shadow Comparison Analysis: Detailed comparison between directional and point light shadow implementations, with comprehensive analysis of quality gaps and improvement roadmap
• Point Light Shadow Improvements Summary: Implementation summary of advanced point light shadow improvements, including contact hardening, temporal stability, early termination PCF, and advanced bias calculation
• Screen Space Ambient Occlusion Analysis: Comprehensive technical analysis of the SSAO implementation, including kernel generation strategy, noise texture creation, performance considerations, and best practices
• PBR Pipeline Analysis: In-depth review of the deferred PBR workflow, BRDF implementation, resource bindings, and performance tuning
• Tone Mapping Analysis: Detailed analysis of the tone mapping implementation, including operator selection, exposure control, and performance considerations

References and Acknowledgments

The Fidelity Engine is built upon the collective knowledge of the graphics programming community. The following resources have been instrumental in the development of various engine systems:

Core Graphics Programming

• Learn OpenGL - Comprehensive modern OpenGL tutorial series
• Lighthouse3D Tutorials - Classic computer graphics tutorials and techniques
• 3D Game Shaders for Beginners - Practical shader programming guide

Performance Analysis and Optimization

• Sponza Frame Analysis - Detailed analysis of modern rendering pipeline performance

Culling and Spatial Optimization

• View Frustum Culling - Mathematical foundations of frustum culling algorithms

Shadow Mapping Techniques

• Shadow Mapping - Comprehensive shadow mapping implementation guide
• MJP's Shadow Maps - Advanced shadow mapping techniques and optimizations
• Microsoft Shadow Depth Maps - Industry best practices for shadow quality

Screen Space Techniques

• SSAO Tutorial - Screen-space ambient occlusion implementation details

Physically Based Rendering

• Epic Games PBR Notes - Real-time PBR implementation in Unreal Engine
• Physics and Math of Shading - Mathematical foundations of physically based shading

HDR and Post-Processing

• HDR Bloom Tutorial - High-quality bloom implementation for HDR rendering
• Catlike Coding Bloom - Step-by-step bloom effect implementation

HDR and Tone Mapping References

• ACES Tone Mapping Curve - In-depth article on ACES filmic curve
• Unreal Engine ACES Implementation - Guidance on ACES integration in UE pipeline

Advanced Lighting

• Clustered Shading - Modern many-light rendering techniques

Third-Party Libraries

• GLFW: Multi-platform library for window management and input
• GLAD: OpenGL loader and extension manager
• GLM: Header-only mathematics library for graphics software
• Assimp: Comprehensive 3D model loading library
• ImGui: Immediate mode GUI for tool development

License

This project is open source and available under the MIT License.