fyroxengine--fyrox/ARCHITECTURE.md

# Architecture

** WORK IN PROGRESS **

This document describes high-level architecture and basic concepts of Fyrox. It should help you to understand
basics of the engine's architecture and find a right place for your modifications.

## Overview

Fyrox is a monolithic game engine with very few replaceable parts. This means that Fyrox itself has relatively
strong coupling between modules. However, some of its parts can be used as standalone crates - core, UI and 
sound are independent of the engine. Internal coupling is one-way in most of the places, this means that, for
instance, a renderer **is** dependent on a scene, but scene does **not** know anything about the renderer.
This fact makes changes in the engine very easy even for beginners.

Fyrox consists of the four crates - fyrox-core, fyrox-sound, fyrox-ui, and Fyrox itself. fyrox-core, fyrox-sound and
fyrox-ui are **standalone** crates and can be used separately, the only place where these three are meet is the
Fyrox. Previously each crate had a separate repository, but then I decided to put everything in single repository
because it was too much of a pain to build any project that uses the engine.

Another important fact is that Fyrox **does not** use ECS, instead it uses generational arenas (pools in Fyrox's
terminology) for efficient memory management (fast allocation/deallocation, CPU cache efficiency). This means
that you are working with good old structures which are placed in contiguous memory block (pool). Once an
object was placed in a pool, you get a handle to the object which can be used to access (borrow) the object
when you need. Such approach allows you to make any relations between the objects - handle is just a pair of 
numbers, it won't cause issues with borrow checker. For more info check 
[pool.rs](https://github.com/FyroxEngine/Fyrox/blob/master/fyrox-core/src/pool.rs).

### Core

Core contains some of very common algorithms and data structures that are used across other parts of the engine.
It contains linear algebra, accelerating structures, color-space functions, etc. In other words it contains 
"building blocks" that are very widely used across other parts of the engine. 

### Renderer

Fyrox uses a combination of deferred + forward renderers. The deferred renderer is used to render opaque objects,
when the forward renderer is used to render transparent objects. The renderer provides lots of very common 
graphical effects. The renderer is suitable for most of the needs, however it is not flexible enough yet and 
there is no way of using custom shaders yet.

### User Interface

Fyrox uses custom user interface library. It is node-based, has very powerful layout system, uses messages
to communicate between widgets, supports styling. The library has 30+ widgets (including docking manager,
windows, file browsers, etc). Please keep in mind that the library does not render anything, instead it
just prepares a set of drawing commands which can be used with any kind of renderer - a software (GDI for
instance) or a hardware (OpenGL, DirectX, Vulkan, Metal, etc.).

### Sound

Fyrox uses software sound engine [fyrox-sound](https://github.com/FyroxEngine/Fyrox/tree/master/fyrox-sound).
The sound engine provides support for binaural sound rendering using HRTF, which gives excellent sound 
spatialization. 

## Code Map

Code map should help you find a right place for your modifications. This is the most boring part of the 
document, here is the table of contents for your comfort:

- [fyrox-core](#fyrox-core)
    - [math](#mathmodrs)
- [fyrox-ui](#fyrox-ui)
    - [widgets](#borderrs)
- [fyrox-sound](#fyrox-sound)
    - [buffer](#buffermodrs)
    - [decoder](#decodermodrs)
    - [device](#devicemodrs)
- [Fyrox](#fyrox)

### fyrox-core

As it was already said up above, fyrox-core is just a set of useful algorithms. If you want to add a thing
that will be used in dependent crates then you're in the right place. Here is the very brief description
of each module.

#### math/mod.rs

The module contains some intersection check algorithms, vector projection methods (tri-planar mapping for 
example), generic rectangle struct, and other stuff that cannot be easily classified.

#### math/aabb.rs

The module contains Axis-Aligned Bounding Box (AABB) structure. It is used as a bounding volume to accelerate
spatial checks (like ray casting, coarse intersection checks, etc).

#### math/frustum.rs

The module contains Frustum structure. Its purpose (in the project) is to perform visibility checks - for
example camera is using frustum culling to determine which objects must be rendered on screen. 

#### math/plane.rs

The module contains Plane structure that basically represents just plane equation. Planes are used for 
intersection tests.

#### math/ray.rs

The module contains Ray structure which is used for intersection tests. For example the engine uses rays
in lightmapper to do ray tracing to calculate shadows.

#### math/triangulator.rs

The module contains a set of triangulation algorithms for polygon triangulation. There are two algorithms:
simple one is for quadrilaterals, and generic one is the ear-clipping algorithm. The stuff from the module is
used to triangulate polygons in 3d models to make them suitable to render on GPU.

#### color.rs

The module contains structure and methods to work with colors in HSV and RGB color spaces, and to convert 
colors HSV <-> RGB.

#### color_gradient.rs

The module contains simple linear color gradient with multiple points. It is widely used in particle systems
to change color of particles over time. For example a spark starts from white color and becomes more red over
time and finally becomes black.

#### lib.rs

The module contains BiDirHashMap and very few other algorithms.

#### numeric_range.rs

The module contains fool-proof numeric range - there is no way to create a range with incorrect bounds - bounds
will be determined at the sampling moment.

#### octree.rs

The module contains Octree acceleration structure which is used to accelerate ray casting, point-probing, 
box intersection tests and so on.

#### pool.rs

The module contains the heart of the engine: pool is one of the most commonly used structure in the engine.
Its purpose is to provide a storage for objects of a type in a contiguous block of memory. Any object
can be accessed later by a handle. Handles are some sort of indices, but with additional information that 
is used to check if handle is valid.

#### profiles.rs

The module contains a simple intrusive profiler. It uses special macro (scope_profile!()) to time a scope.

#### rectpack.rs

The module contains rectangle packing algorithm (most commonly known as "bin-packing problem"). It is used
to create texture atlases.

#### visitor.rs

The module contains node-based serializer/deserializer (visitor). Everything in the engine serialized by 
this serializer. It supports serialization of basic types, many std types (including
Rc/Arc) and user-defined types.

### fyrox-ui

fyrox-ui is a standalone, graphics API-agnostic, node-based, general-purpose user interface library.

#### lib.rs

The module contains UserInterface structure and Control trait. 

#### border.rs

The module contains Border widget which is basically just a rectangle with variable width of borders, and
an ability to be a container for child widgets.

#### brush.rs

The module contains Brush structure which describes a way of drawing graphics primitives. 

#### button.rs

The module contains Button widget and its builder.

#### canvas.rs

The module contains Canvas widget and its builder. Canvas is a simple container for child widgets,
it allows setting position of children widgets directly. 

#### check_box.rs

The module contains CheckBox widget and its builder. CheckBox is a three-state (checked, unchecked,
undefined) switch.

#### color.rs

The module contains widgets to work with colors and their builders. There are separate widgets to change
hue, saturation, brightness and compound color selector widget.

#### decorator.rs

The module contains Decorator widget and its builder. Decorator is a simple container for child widgets,
it has built-in behaviour for most common actions: it changes appearance when mouse enters or leaves bounds,
when user clicks on it, etc. 

#### dock.rs

The module contains DockingManager and Tile widgets and their builders. Docking manager is able to combine
multiple Window widgets in its tiles, each tile can be resized, docked or undocked. This is the must-have
widget for any kind of editor.

#### draw.rs

The module is responsible for "drawing". It is in quotes, because it does not actually draw anything, it just 
emits drawing commands in a queue for later interpretation. 

#### dropdown_list.rs

The module contains DropdownList widget and its builder. DropdownList is a small field that shows selected
item and a "popup" that contains list of items.

#### expander.rs

The module contains Expander widget and its builder. Expander is a collapsable container for child widgets
with a field that describes a content. 

#### file_browser.rs

The module contains a set of widgets that displays file system. FileBrowser widget is a simple file system
tree, FileSelector is a window with FileBrowser and few buttons. 

#### formatted_text.rs

The module is responsible for text formatting and "rendering". The latter is in quotes, because the library 
just uses glyph info from a font to layout each glyph in a line of text with word wrapping and other 
useful features (like text size calculation, etc).

#### grid.rs

The module contains Grid widget and its builder. Grid is a powerful layout widget, it allows arranging child
widgets in a series of rows and columns.

#### image.rs

The module contains Image widget and its builder. Image is a simple rectangle with a texture.

#### list_view.rs

The module contains ListView widget and its builder. ListView is a container for items which arranged 
as a stack. ListView supports item selection.

#### menu.rs

The module contains menu widgets. Menu here means a classic menu which is a strip with root items and a 
set of child sub-menus.

#### message.rs

The module contains all supported messages for every widget in the library. 

#### messagebox.rs

#### node.rs

#### numeric.rs

#### popup.rs

#### progress_bar.rs

#### scroll_bar.rs

#### scroll_panel.rs

#### scroll_viewer.rs

#### stack_panel.rs

#### tab_control.rs

#### text.rs

#### tree.rs

#### ttf.rs

#### utils.rs

#### vec.rs

#### vector_image.rs

#### widget.rs

#### window.rs

#### wrap_panel.rs

### fyrox-sound

fyrox-sound is a standalone sound engine with multiple renderers and high-quality sound. The sound engine
provides support for binaural sound rendering using HRTF, which gives excellent sound spatialization.

#### buffer/mod.rs

#### buffer/generic.rs

#### buffer/streaming.rs

#### decoder/mod.rs

#### decoder/vorbis.rs

#### decoder/wav.rs

#### device/mod.rs

#### device/alsa.rs

#### device/coreaudio.rs

#### device/dsound.rs

#### device/dummy.rs

### Fyrox

The engine itself. It has: a renderer, resource manager, animations, scenes, and various utilities like 
lightmapper, uv-mapper, navigation mesh, logger, pathfinder.

#### animation/mod.rs
#### animation/machine/mod.rs
#### animation/machine/blend_nodes.rs
#### engine/mod.rs
#### engine/error.rs
#### engine/resource_manager.rs
#### renderer/mod.rs
#### renderer/framework/mod.rs
#### renderer/framework/framebuffer.rs
#### renderer/framework/geometry_buffer.rs