
<!-- I release these notes into the public domain -->

# Planning Documentation for fennec

## Table of Contents

<!-- TOC -->
* [Planning Documentation for fennec](#planning-documentation-for-fennec)
  * [Table of Contents](#table-of-contents)
  * [Introduction](#introduction)
  * [Definitions](#definitions)
  * [Libraries](#libraries)
    * [C++ Language Library](./CPP_LANGUAGE.md#c-language-library-lang)
    * [Platform Support Library](./PLATFORM_SUPPORT.md#platform-support-library-platform)
<!-- TOC -->

## Introduction

&ensp; These files serve as general planning documentation for engine structure, systems,
pipelines, and implementation.


&ensp; 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 goal requiring the entire engine to be `O(1)`,
we should more specifically look at achieving `O(1)` performance on hot paths.
I distinctly use 'strive' and 'goal' as different concepts, where designs should
*strive* to accommodate function implementations for `O(1)`, however the specifics
of the implementation might not always be able to achieve that, so the end *goal* is
that hot paths should be `O(1)`.

&ensp; Functions should be highly verbose and any bugprone or erroneous behaviour should
throw assertions. **DO NOT USE EXCEPTIONS**.

&ensp; 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.

&ensp; The engine should not care about the types of objects loaded from a so/dll. In
fact, most of the code should be type independent. Any shared information among a
collection of objects should be held either implicitly or explicitly in the super-class.
It will be the responsibility of the linked code to initialize and cleanup the objects
related to it. This principle should extend to the submodules of the engine.

&ensp; It is also best to avoid objects having behaviour that is not defined by the system
they are in. There are some exceptions in extensions or mods, which should be given
configurability and programmability within those systems and their stages. This can 
be achieved using events at different stages of those engines that are on-demand.


## External Libraries

 * `cpptrace`
   * Walking the stack and retrieving information about the code is *very* platform
     dependent, and it makes little sense spending days writing a library that will
     be less effective.


## Definitions

&ensp; Many subpages of these documents will contain tables that use symbols to
denote implementation and testing progress. The symbols are defined below.

| Symbol | Meaning                 | Notes                                                     |
|:------:|:------------------------|:----------------------------------------------------------|
|   ✅    | Completed               | Complete implementation and all tests passing.            |
|   🚧   | Partial                 | Partial implementation and all tests implemented passing. |
|   ⛔    | Unimplemented / Failing | Not implemented or any test is failing.                   |



## Libraries
 - [C++ Language Library](./CPP_LANGUAGE.md#c-language-library-lang)
 - [Platform Support Library](./PLATFORM_SUPPORT.md#platform-support-library-platform)
 - [Memory Library](./MEMORY.md#memory-library-memory)
 - [Containers Library](./CONTAINERS.md#containers-library-containers)
 - [Language Processing Library](./LANGUAGE_PROCESSING.md#language-processing-library-lang)