fennec/PLANNING.md

# Planning Documentation for fennec

## Table of Contents

 1. [Introduction](#introduction)
 2. [C++ Language](#c-language)
 3. [Math Library](#math-library)


## Introduction

This file serves as a general planning document for engine structure, systems, pipelines, and implementation.


Implementations of core engine systems should strive to be `O(1)` in implementations, 
both in terms of runtime and memory performance. This is obviously not a realistic goal, 
so rather than the entire engine striving to be `O(1)` we should more specifically look
at achieving `O(1)` performance on hot paths.

Functions should be highly verbose, and in debug mode any bugprone or erroneous behaviour should throw
assertions. **DO NOT USE EXCEPTIONS**.

System implementations should be independent of architecture or platforms. i.e. the code of the graphics system should 
not care if OpenGL or Vulkan is used and should not use any direct calls to OpenGL or Vulkan.


## C++ Language Library (`lang`)

Implement header files for standard functions relating to the C++ Language.
So far this is implemented on an as-needed basis.


## Math Library (`math`)

Implement math functions according to the [OpenGL 4.6 Shading Language Specification](https://registry.khronos.org/OpenGL/specs/gl/GLSLangSpec.4.60.pdf).

Additional extensions should be implemented to provide standard definitions for functions predominantly related
to Linear Algebra, Mathematical Analysis, and Discrete Analysis. Additional extensions will be implemented on a
as-needed basis.


## Memory Library (`memory`)

Implement headers related to memory allocation in C++.

 * Smart Pointers
 - Memory Allocation


## Language Processing (`proclang`)

Pronounced [pɹˈɒkh,læŋ](https://itinerarium.github.io/phoneme-synthesis/?w=pɹˈɒkh,læŋ)

No, this won't include Machine Learning, it will mostly include tools for processing human-readable files.
fennec should be able to use Doxygen and LaTeX externally. Consider including binaries with releases.

 * String Analysis (`proclang/strings`)
   * Search
   * Manipulation
   * Delimiting
   * Regex

 - File Formats (`proclang/formats`)
   - Serialization
     - JSON
     - HTML
     - XML
     - YAML
   - Configuration
     - INI
     - TOML
   - Documents
     - ODF
     - Markdown
     - PDF
   - Spreadsheets & Tables
     - ODS
     - CSV

**MAYBE**
 * Compilation  (`proclang/code`)
   * Lexical Analysis
   * Syntax Analysis
   * Semantic Analysis
   * Intermediate Code Generation
   * Optimization
   * Target Code Generation


## Core (`core`)

This will be the core of the engine.

 - Event System
 - Core Engine Loop
   - System Manager

The priority sequence of the main systems is as follows:

**3D Systems will apply *before* their 2D Variants** 

 - **Update**
   - Scripts
   - AI
 - **Physics**
   - Newtonian Commit
     - Apply Forces (Updates Acceleration and Torque)
     - Apply Torque & Acceleration (Updates Velocities)
     - Apply Velocities (Updates Position and Rotation)
   - Constraint Resolution
   - Collision Detection
   - Collision Resolution (Adjust for Clipping)
     - Soft Bodies resolve before Rigid Bodies
   - Collision Response
     - Calculate Forces
   - 
 - **Graphics**

## 3D Scene (`scene3d`)

* In-Array Directed Tree
  * Elegant method for providing `O(1)` insertions and `O(log(n))` deletions.
* Bounding Volume Hierarchy
    * Octree


## 3D Graphics (`gfx3d`)

Links:
 - https://en.wikipedia.org/wiki/Octree
 - https://www.adriancourreges.com/blog/2015/11/02/gta-v-graphics-study/
 - https://learnopengl.com/PBR/Lighting
 - https://learnopengl.com/PBR/IBL/Diffuse-irradiance
 - https://en.wikipedia.org/wiki/Schlick%27s_approximation
 - https://pixelandpoly.com/ior.html
 - https://developer.download.nvidia.com/SDK/10/opengl/screenshots/samples/dual_depth_peeling.html

**DirectX will never have official support.** If you would like to make a fork, have at it, but know I will hold a deep disdain for you.

This is the set of stages for the graphics pipeline that runs every frame:

 - LOD Selection
 - Visibility Buffer & Culling

 * G-Buffer Pass
   * Depth - Stencil
     * 24-Bit Depth Buffer
     * 8-Bit Stencil Buffer, used to represent the lighting model.
   * Diffuse - RGB8
   * Emission - RGB8
   * Normal - RGB8
   * Specular - RGB8
     * R → Roughness
     * G → Specularity (sometimes called metallicism)
     * B → Index of Refraction (IOR)

 - Lighting Buffer - RGB16
 - Lighting Pass
   - Generate Dynamic Shadows
   - Generate Dynamic Reflections (Optional)
   - SSAO (Optional)
   - Apply Lighting Model

 * Forward Pass
   * Translucent Materials
   * Materials with Forward Shading enabled.

 - Post Processing
   - Depth of Field (Optional)
   - Bloom (Optional)
   - Tonemapping (Optional)
   - HDR Correction

## 3D Physics `(physics3d)`

Links:
 - https://www.researchgate.net/publication/264839743_Simulating_Ocean_Water
 - https://arxiv.org/pdf/2109.00104
 - https://www.youtube.com/watch?v=rSKMYc1CQHE

Systems

 * Rigid Body System
 - Particle Physics
 * Soft Body Physics
   * Elastics → Finite Element Simulation
   * Cloth → Position-Based Dynamics
   * Water
     * Oceans → iWave
       * Reasoning: iWave provides interactive lightweight fluid dynamics suitable for flat planes of water. 
         <br><br>

     * 3D Fluid Dynamics &rarr; Smoothed-Particle Hydrodynamics
       * Reasoning: This is the simplest method for simulating 3D bodies of water. This should exclusively be
         used for small scale simulations where self-interactive fluids are necessary. I.E. pouring water into
         a glass. 
         <br><br>

     * 2D Fluid Dynamics &rarr; Force-Based Dynamics
       * Reasoning: This model, like iWave, provides lightweight interactive fluid dynamics, but is more easily
         adapted to flowing surfaces such as streams and rivers.